# Lumio Docs

> Documentation for Lumio, a multi-platform streaming management application
> for Twitch, YouTube, Kick, Discord and Spotify. Covers the dashboard and
> user guide, platform features, the REST / GraphQL / WebSocket API, RBAC
> permissions, the admin panel, and self-hosted installation.
>
> Lumio is a Rust + TypeScript monorepo. The API (Actix Web) exposes every
> feature over three protocols at once: GraphQL (POST /v1/gql), REST
> (everything under /v1/) and WebSocket (/v1/ws).

---

## Welcome to Lumio Docs

Source: https://docs.lumio.vision/intro

# Welcome to Lumio Docs

Lumio is a multi-platform streaming management application for Twitch, YouTube, Kick, Discord, and Spotify.

## What is Lumio?

Lumio gives streamers a single dashboard for overlays, chat, bots, music, events, and automations across every connected platform:

- **Multi-platform connections** - Channel connections for Twitch, YouTube, Kick and Spotify; Discord as a login and bot/integration platform
- **Overlay editor** - Visual layer-based overlay editor with live preview; every overlay renders as an OBS browser source
- **Widgets & extensions** - 12 system extensions (8 widgets + 4 bot modules) plus third-party extensions from the Extension Store
- **Event system** - Real-time events (follows, subs, cheers, raids, redemptions, tips) with filtering, alerts and history
- **Multichat** - Unified chat across all connected platforms with cross-platform moderation
- **Chat bots** - Four bots (Twitch, YouTube, Kick, Discord) sharing one command system
- **Spotify integration** - Playback control from the dashboard plus a Now Playing overlay widget
- **Automations** - Node-based workflow editor wiring triggers to conditions and actions
- **RBAC** - Fine-grained role-based access control for team management

## Platform at a glance

Lumio is a Rust + TypeScript monorepo: 34 Rust crates (`lo-*`), 18 apps, 9 internal TypeScript packages (`@lumio/*`), 5 public npm packages (`@zaflun/*`), and 12 system extensions (8 widgets + 4 bot modules).

The API is an Actix Web service that exposes every feature over three protocols simultaneously:

| Surface | Endpoint |
|---------|----------|
| GraphQL (primary) | `POST /v1/gql` |
| GraphiQL IDE | `GET /v1/graphiql` |
| GraphQL SDL | `GET /v1/schema` |
| REST | everything under `/v1/` |
| WebSocket | `/v1/ws` |

Data lives in PostgreSQL (relational data), TimescaleDB (time-series: events, chat, audit logs) and Redis (cache and pub/sub).

Production runs on `lumio.vision` (dashboard), `id.lumio.vision` (login), `api.lumio.vision` (API), `admin.lumio.vision` (admin), `overlay.lumio.vision` (overlays) and `widget.lumio.vision` (widgets).

## Quick Links

- [Installation](/getting-started/installation) - Set up a local development environment
- [OAuth Provider Setup](/getting-started/oauth-setup) - Create the OAuth applications Lumio needs
- [Connecting Platforms](/getting-started/connecting-platforms) - Link your streaming accounts
- [First Overlay](/getting-started/first-overlay) - Create your first overlay and add it to OBS
- [API Reference](/api-reference/rest-api) - REST, GraphQL and WebSocket documentation
- [Developer Guide](/developer-guide/bot-modules) - Build custom bot modules

## For AI assistants

This site publishes its documentation in the [llms.txt](https://llmstxt.org/) format, so an AI
assistant can read it without crawling the HTML:

- [llms.txt](pathname:///llms.txt) - structured index of every page with a one-line description
- [llms-full.txt](pathname:///llms-full.txt) - the complete documentation in a single file

Both files are regenerated on every build, so they never drift from the pages above. Extension
developers want the equivalent files on the developer site:
[developers.lumio.vision/llms.txt](https://developers.lumio.vision/llms.txt).

---

## Getting Started / Installation

Source: https://docs.lumio.vision/getting-started/installation

# Installation

Set up a local Lumio development environment.

## Hosted Environments

Lumio runs three environments per app. Production lives on `lumio.vision`; non-production on `zaflun.dev`. Use these strings when configuring OAuth callbacks, CORS, env-var defaults and CI deploy targets.

| App | Production | Production Preview | Staging |
|-----|------------|---------------------|---------|
| Webapp | `lumio.vision` | `lumio.web.prod.zaflun.dev` | `lumio.web.staging.zaflun.dev` |
| ID App | `id.lumio.vision` | `lumio.id.prod.zaflun.dev` | `lumio.id.staging.zaflun.dev` |
| Admin App | `admin.lumio.vision` | `lumio.admin.prod.zaflun.dev` | `lumio.admin.staging.zaflun.dev` |
| Stats App | `stats.lumio.vision` | `lumio.stats.prod.zaflun.dev` | `lumio.stats.staging.zaflun.dev` |
| API | `api.lumio.vision` | `lumio.api.prod.zaflun.dev` | `lumio.api.staging.zaflun.dev` |
| Docs | `docs.lumio.vision` | `lumio.docs.prod.zaflun.dev` | `lumio.docs.staging.zaflun.dev` |
| Developer Docs | `developers.lumio.vision` | `lumio.dev.docs.prod.zaflun.dev` | `lumio.dev.docs.staging.zaflun.dev` |
| Overlay external URL | `overlay.lumio.vision` | _(single per-deployment external host; configurable via `NEXT_PUBLIC_OVERLAY_URL` on the webapp)_ | _(same)_ |
| Widget external URL | `widget.lumio.vision` | _(single per-deployment external host; configurable via `LUMIO__WIDGET__PUBLIC_URL` on the API)_ | _(same)_ |

**Branch mapping:** `next` → staging · `main` → production preview · tag `20*` → production. This mapping is enforced in CI for the Cloudflare-hosted docs family (`docs`, `developer-docs`, `extension-apps`). The core product containers (API, web, admin, id, workers, bots) are container images promoted by release channel instead - `beta` for a pre-release, `latest` for a full release.

The rest of this guide covers a **local** development setup.

## Prerequisites

| Tool | Version / notes |
|------|-----------------|
| Docker + Docker Compose | Runs the local database stack |
| Rust toolchain (`rustup`) | Edition 2024. CI builds on `stable`; the Bazel toolchain pins `1.97.1` |
| `protoc` | Required - `lo-youtube-api`'s build script compiles the YouTube gRPC protos |
| Node.js | `>= 18` |
| pnpm | `10.28.0` (see `packageManager` in the root `package.json`) |
| [`just`](https://just.systems) | Task runner used by every command in these docs |

Bazel is optional locally - it is the CI build system (see [Bazel](#bazel-ci-only) below).

## Dev Stack

`just stack-up` starts the local database + broker stack, merging `dev-stack/db.docker-compose.yml` and `dev-stack/broker.docker-compose.yml`:

```bash
just stack-up
```

| Service | Image | Host port | Database |
|---------|-------|-----------|----------|
| `lumio-postgres` | `postgres:18-alpine` | `127.0.0.1:5432` | `lumio` (user/password `lumio`) |
| `lumio-tsdb` | `timescale/timescaledb-ha:pg18` | `127.0.0.1:5433` | `lumio_tsdb` (user/password `lumio`) |
| `lumio-extensions-postgres` | `postgres:18-alpine` | `127.0.0.1:5434` | `lumio_extensions` (owner `lumio_ext`, DML logins `lumio_ext_api` / `lumio_ext_worker`; password = user name) |
| `lumio-redis` | `redis:8-alpine` | `127.0.0.1:6379` | password `lumio` |
| `lumio-rabbitmq` | `rabbitmq:4-management-alpine` | `127.0.0.1:5672` (AMQP), `127.0.0.1:15672` (UI) | user/password `lumio` |
| `lumio-kafka` | `apache/kafka:3.9.0` | `127.0.0.1:9092` | KRaft mode (no ZooKeeper) |

The brokers back the ingest pipeline: **RabbitMQ** is the job/command bus and **Kafka** is the durable ingest firehose (Redis stays cache-only, TimescaleDB is the system of record). Dev and staging run single-node; only production is the multi-node cluster.

The extensions PostgreSQL's superuser is `postgres` (password `postgres`), and no app uses it: superusers ignore row-level security. On an empty volume `dev-stack/initdb/extensions/10-roles.sh` creates the DDL owner `lumio_ext`, the `lumio_ext_dml` group and the DML logins (see `developer-guide/data-layer-staging.md`, "Extensions PostgreSQL: roles"). A volume created before this change still has `lumio_ext` as its superuser. Delete that volume once with the stack stopped (find it with `docker volume ls | grep lumio-extensions-pg-data`; compose prefixes the project name) so the script runs, or switch it in place as described there.

The databases preload `pg_stat_statements` and log every statement that takes 1 s or longer. Redis has `maxmemory 512mb` with `maxmemory-policy noeviction`: a full Redis rejects writes instead of dropping keys, as on staging (see `developer-guide/data-layer-staging.md`). TimescaleDB keeps its data in the `lumio-tsdb-pgdata` volume. The older `lumio-tsdb-data` volume was mounted at a path the `timescaledb-ha` image does not use, so it holds no data and you can delete it.

The stack runs in the foreground, so use a dedicated terminal. Related recipes:

| Recipe | What it does |
|--------|--------------|
| `just stack-down` | Stop the stack (volumes kept) |
| `just stack-reset` | Stop the stack, **drop the volumes**, start again |
| `just stack-logs` | Tail the stack logs |
| `just mail-up` | MailDev on `http://localhost:1080` |
| `just minio-up` | MinIO console on `http://localhost:9001` |
| `just stack-all` | `stack-up` + `mail-up` + `minio-up` |
| `just psql` / `just tsdb-psql` / `just redis-cli` | Open a CLI against the running containers |
| `just rabbitmq-ui` | Print the RabbitMQ management UI URL (`http://127.0.0.1:15672`, `lumio`/`lumio`) |
| `just kafka-topics` | List Kafka topics on the local KRaft broker |

## Database Migrations

Migrations live in `apps/api/migrations/` (main database) and `apps/api/tsdb_migrations/` (TimescaleDB) and are run by the `migrate` binary:

```bash
just migrate          # run all pending migrations on both databases
just migrate-status   # show what has been applied
just migrate-main     # main database only
just migrate-tsdb     # TimescaleDB only
just db-fresh         # drop, create, migrate
```

The API also runs pending migrations on startup.

> **Migrations are embedded at compile time:**
> `sqlx::migrate!()` embeds the `.sql` files into the binary when it is **compiled**. Adding a new migration file therefore requires a rebuild - `cargo build -p lumio-api` (or `just build-api`) - not just a restart. A restart alone will silently run the old migration set.

New migrations use the reversible `.up.sql` / `.down.sql` pair format. Legacy migrations from before `20260410` use the simple single-file format and are never renamed.

## Running the Apps

Each app has its own recipe and its own port:

| Recipe | App | URL |
|--------|-----|-----|
| `just run-api` (or `just dev-api` for auto-reload, which needs `cargo install cargo-watch`) | Rust API | `http://localhost:3000` |
| `just dev-web` | Webapp / dashboard | `http://localhost:4000` |
| `just dev-admin` | Admin panel | `http://localhost:4001` |
| `just dev-id` | ID / auth app | `http://localhost:4002` |
| `just dev-stats` | Public stats app | `http://localhost:4003` |
| `pnpm --filter @lumio/shopify dev` | Embedded Shopify admin page (`apps/shopify`); renders only inside the Shopify admin, see [Shopify → Embedded page](../features/shopify.md#embedded-page-appsshopify) | `http://localhost:4004` |
| `just dev-docs` | This documentation site | Docusaurus default port - pass `--port` to avoid clashing with the API on `3000` |
| `just dev-developer-docs` | Developer documentation | `http://localhost:3004` |
| `just dev-supervisor` | Extension supervisor (static) | `http://localhost:3200` |
| `just dev-runtime` | Extension runtime (static) | `http://localhost:3201` |


## Bazel (CI Only)

Bazel handles CI builds and container image creation. It is not required for local development -- Cargo covers that. Install [Bazelisk](https://github.com/bazelbuild/bazelisk), which automatically downloads the correct Bazel version:

```bash
# Install Bazelisk (Bazel version manager)
npm install -g @bazel/bazelisk
# Or on macOS:
brew install bazelisk

# Verify
bazel --version
```

See the [Bazel Build System](../developer-guide/bazel.md) guide for details on the build architecture, vendored crates, and image targets.

## Environment Configuration

### Sign-in protection and support code

The API's `[turnstile]` section controls server-side Cloudflare Turnstile verification. `enabled`, `site_key`, `secret_key`, `id_hostnames`, `web_hostnames`, `verify_url`, and `timeout_ms` can be overridden as `LUMIO__TURNSTILE__ENABLED`, `LUMIO__TURNSTILE__SITE_KEY`, `LUMIO__TURNSTILE__SECRET_KEY`, `LUMIO__TURNSTILE__ID_HOSTNAMES`, `LUMIO__TURNSTILE__WEB_HOSTNAMES`, `LUMIO__TURNSTILE__VERIFY_URL`, and `LUMIO__TURNSTILE__TIMEOUT_MS`. Use exact ID-app hosts for registration, login, reset and resend; exact web-app hosts for email setup and resend and for the contact form (action `contact`). The public site key is supplied to the apps at runtime by `GET /v1/auth/turnstile-config`. Keep the secret in the environment. The default pair is Cloudflare's always-pass test pair, so every protected action passes on a local stack. Cloudflare answers the test secret with hostname `example.com`, no action and `metadata.result_with_testing_key: true`; the API accepts that answer without the action and hostname checks, and only when the environment is neither `staging` nor `production`. In staging and production the test secret fails closed, and a test-key answer with a real secret is rejected, so hosted environments use real keys. To run with no check at all, set `LUMIO__TURNSTILE__ENABLED=false`.

The API's `[contact]` section sets where the public contact form (`POST /v1/contact`, GraphQL `submitContactMessage`) sends its messages: `recipient` (default `hey@lumio.vision`, ENV `LUMIO__CONTACT__RECIPIENT`). Each message goes out through the configured `[email]` provider with `Reply-To` set to the sender and is not stored. With `email.enabled = false` the message is only logged as a skipped send.

Set `[support].code_secret` through `LUMIO__SUPPORT__CODE_SECRET`. It is the HMAC secret for each profile's hourly support code; rotating it invalidates existing codes. Never expose it to a browser or put it in a repository TOML file.

Local development needs no setup: when the secret is empty and `environment` is `development` (or `dev`), the API derives codes from a fixed, public development secret and logs this once at `info` on startup. Every other environment takes no default. Staging or production without the secret still starts, but logs `warn` `support code disabled: LUMIO__SUPPORT__CODE_SECRET is empty`; the support code then stays off (`SUPPORT_CODE_UNAVAILABLE`), so the profile header shows no code and the admin **Support Identity** card cannot reveal or check one.

### File storage for profile pictures

Own profile pictures (`POST /v1/users/me/avatar`) are stored through the API's `[storage]` section, the same lo-storage client that channel uploads and GDPR exports use. With `storage.enabled = false` (`LUMIO__STORAGE__ENABLED`) the upload returns `503 AVATAR_UNAVAILABLE`. The files live under the key prefix `users/<user_id>/avatar/` (`<uuid>-512.webp` and `<uuid>-128.webp`), and `users.avatar_url` is `storage.public_url` (`LUMIO__STORAGE__PUBLIC_URL`) plus that key. Point `storage.public_url` at the API itself, `<API origin>/v1/uploads/file` (e.g. `http://localhost:3000/v1/uploads/file`, or your own port): the API serves the current picture under that path (`GET /v1/uploads/file/users/<user_id>/avatar/<uuid>-512.webp`) from storage, so neither the local directory nor an S3 bucket has to be publicly readable. The API re-derives every stored picture URL from the key at start-up, so changing `storage.public_url` heals existing pictures by itself. The dashboard's `img-src` allows the API origin; a CSP set in front of the web app (such as the production edge) has to allow it too. GDPR export archives use the separate `private/data-exports/` prefix, which must stay private. The 5 MB picture cap is fixed in code and independent of `storage.max_upload_size_bytes`. Uploaded channel pictures (`POST /v1/accounts/<id>/avatar`) use the same storage under `accounts/<id>/avatar/` and are served at `GET /v1/uploads/file/accounts/<id>/avatar/<uuid>-512.webp`, with the same `503 AVATAR_UNAVAILABLE` when storage is off.

### Billing without Stripe

Stripe billing is controlled by the API's `[stripe]` section (`enabled`, `secret_key`, `webhook_secret`, `price_id_pro`, `price_id_enterprise`; ENV `LUMIO__STRIPE__ENABLED`, `LUMIO__STRIPE__SECRET_KEY`, …). It is off in `default.toml`, so a local stack runs without Stripe. Then `billingStatus.billingEnabled` (REST `GET /v1/billing/status` → `billing_enabled`) is `false`, the dashboard's Subscription tab still lists the plans (from the database) and the channel's current plan, with checkout, switching to Free and cancelling disabled; the Invoices tab shows that billing is not set up instead of loading invoices; and every other billing call answers `409 BILLING_DISABLED`. New channels are created on Free either way.

Configuration is split by runtime. There is **no repository-root `.env`** - each app is configured on its own.

### Developer payouts and credit notes

Every developer payout is documented by a self-billed credit note (Gutschrift). The issuer printed on it comes from the API's `[billing.issuer]` section: `name`, `address` (one line per address line) and `vat_id` (ENV `LUMIO__BILLING__ISSUER__NAME`, `LUMIO__BILLING__ISSUER__ADDRESS`, `LUMIO__BILLING__ISSUER__VAT_ID`). They are empty in `default.toml`: the API then logs a warning at start-up and refuses every payout, so a local stack books none. `[billing.credit_notes]` sets the number prefix (`number_prefix`, default `GS`) and the VAT rate for German standard-rated developers (`domestic_vat_rate_bp`, default `1900`). Storing and mailing the PDFs needs `[storage]` and `[email]`. Details: [Developer credit notes](../features/developer-credit-notes.md#configuration).

The payout cycle (`[payments] payout_cycle_enabled`, ENV `LUMIO__PAYMENTS__PAYOUT_CYCLE_ENABLED`, default `true`) pays out developer balances once per month and sends pending Stripe and PayPal payouts every 15 minutes. A provider without credentials (`stripe_secret_key`; `paypal_client_id` + `paypal_client_secret`) is skipped, so a local stack sends nothing. Details: [Developer payouts](../features/developer-payouts.md#configuration).

### Rust services - layered TOML

The API and the bots read layered TOML from their own `config/` directory:

```
config/default.toml → config/{env}.toml → config/local.toml → ENV vars
```

Later layers win, so an environment variable always overrides a file. `config/default.toml` is committed and holds every key with a documented default; `config/local.toml` is git-ignored and is where you put local secrets. The `{env}` layer is selected by `APP_ENV` for the API (`development` - the default - `staging`, or `production`), and by `{SERVICE}_RUN_MODE` for the bots (e.g. `TWITCH_BOT_RUN_MODE`).

**List values from the environment are comma-separated.** A list key takes one ENV value whose entries are separated by `,`, for example `LUMIO__TURNSTILE__ID_HOSTNAMES=lumio.id.staging.zaflun.dev` or `LUMIO__TURNSTILE__WEB_HOSTNAMES=a.example,b.example`. A single entry needs no comma. Each entry is trimmed and empty entries are dropped, so `" a.example , b.example ,"` loads as `a.example` and `b.example`. Numeric lists work the same way: `CRAWLER_TWITCH__CRAWLER__OWNED_SHARDS=3` loads as `[3]`, and `=1,2` as `[1, 2]`. The list keys are `cors.allowed_origins`, `youtube.innertube_proxy_urls`, `history.command_prefixes`, `webauthn.origins`, `turnstile.id_hostnames`, `turnstile.web_hostnames` (API) and `crawler.owned_shards` (Twitch crawler). Every other key is read as one value, so a comma inside a URL, token or DSN is kept as it is.

Create `apps/api/config/local.toml` with at least your OAuth login credentials and a token encryption key (see [OAuth Provider Setup](/getting-started/oauth-setup#2-api-server-appsapiconfiglocaltoml)). The database and Redis defaults in `default.toml` already match the dev stack:

| Config key | Default |
|------------|---------|
| `server.port` | `3000` |
| `database.url` | `postgres://lumio:lumio@localhost:5432/lumio` |
| `timescale.url` | `postgres://lumio:lumio@localhost:5433/lumio_tsdb` |
| `extensions.database.url` | `postgres://lumio_ext_api:lumio_ext_api@localhost:5434/lumio_extensions` |
| `extensions.database.ddl_url` | `postgres://lumio_ext:lumio_ext@localhost:5434/lumio_extensions` |
| `redis.url` | `redis://:lumio@127.0.0.1:6379` |
| `web.public_url` | `http://localhost:4000` |
| `admin.public_url` | `http://localhost:4001` |
| `overlay.public_url` | `http://localhost:4000/overlay` |
| `widget.public_url` | `http://localhost:4000/widget` |

The extensions database uses two roles. `extensions.database.url` (`LUMIO__EXTENSIONS__DATABASE__URL`) is the **DML** pool that server functions run on: a login in the `lumio_ext_dml` group that may only read and write rows. `extensions.database.ddl_url` (`LUMIO__EXTENSIONS__DATABASE__DDL_URL`) is the **DDL** pool, at most 2 connections: the schema owner, which runs the extensions migrations, provisioning, the data purges and the storage-quota pass. At startup the API refuses to run if either role is a superuser or has `BYPASSRLS`, or if the DML login has `CREATE` or `TEMPORARY` on the database. Outside `development` it also refuses an empty `ddl_url` or one equal to `url`. In development an empty `ddl_url` falls back to `url`. The dev stack's init script creates both logins; a volume created before it still has `lumio_ext` as its superuser, and the API then refuses to start until the volume is recreated or switched (see the note under the dev-stack table above).

### Required public URLs for hosted API deployments

The API uses `[web] public_url` and `[admin] public_url` to mint OAuth redirect URIs and to validate the admin return target for global bot OAuth. It also uses the web URL for developer-team invite emails (`/invite/dev/{code}`) and the admin URL for developer-application review notifications and emails (`/developers/applications`). `apps/api/config/staging.toml` and `apps/api/config/production.toml` do not pin those sections, so hosted deployments must supply them through environment variables:

| Environment | `LUMIO__WEB__PUBLIC_URL` | `LUMIO__ADMIN__PUBLIC_URL` |
|-------------|--------------------------|----------------------------|
| Production | `https://lumio.vision` | `https://admin.lumio.vision` |
| Production preview | `https://lumio.web.prod.zaflun.dev` | `https://lumio.admin.prod.zaflun.dev` |
| Staging | `https://lumio.web.staging.zaflun.dev` | `https://lumio.admin.staging.zaflun.dev` |

If `LUMIO__WEB__PUBLIC_URL` is missing outside local development, system-sourced channel and bot OAuth flows build provider redirect URIs with the default `http://localhost:4000` host. Twitch, Kick and YouTube reject that redirect URI in hosted environments. If `LUMIO__ADMIN__PUBLIC_URL` is missing, the admin global-bot flow stores `http://localhost:4001/providers` as its return target; the unified callback allowlist then cannot return the browser to the hosted admin app.

> **`DATABASE_URL` is not an API setting:**
> The API reads its connection strings from the TOML layers (or `LUMIO__DATABASE__URL`). The `apps/api` integration-test harness uses `DATABASE_URL` to create an isolated database for each test. Start the [Dev Stack](#dev-stack), set `DATABASE_URL` to its PostgreSQL server using a user that can `CREATE DATABASE`, then run `cargo test -p lumio-api --test <name>`. For a TimescaleDB-gated suite, set `DATABASE_URL` to the Dev Stack's TimescaleDB server and `RUN_TSDB_MIGRATION_TEST=1` before running the same command. Tests that need real Redis can opt in with `TEST_REDIS_URL`; other database tests use the offline Redis fixture.
> 
> Agent runs use a separate host test stack with an injected `DATABASE_URL`. That stack runs on demand: if a test reports connection refused on ports `15432`, `15433`, or `16379`, agents start it with `docker compose -f ~/test-stack/docker-compose.yml up -d`, wait for the services to be healthy, and rerun the test. Agents leave it running; only Raphael stops it. They do not replace the injected URL or switch to the developer stack.

### Mandatory auth secrets

Two `[auth]` keys are **required** on any non-`development` deployment. `default.toml` ships them unset/placeholder so the local inner loop just works, but the API **refuses to boot** (`environment` = `staging` or `production`) if either is empty, the shipped placeholder (`CHANGE_ME` / `change-me-in-production`), or shorter than 16 characters:

| Key | ENV var | Why it must be a real secret |
|-----|---------|------------------------------|
| `auth.token_encryption_key` | `LUMIO__AUTH__TOKEN_ENCRYPTION_KEY` | AES-256-GCM key for every at-rest secret (channel + BYO `app_credentials` OAuth tokens, StreamElements JWTs, OBS passwords, Stripe Connect state). An **empty** value derives `SHA-256("")` - a constant any clone of this repo can reproduce - so all ciphertext becomes readable by anyone who has the code. |
| `auth.jwt_secret` | `LUMIO__AUTH__JWT_SECRET` | HMAC key for session tokens. A placeholder value lets anyone forge a valid session JWT (auth bypass, no DB access needed). |

Generate each with `openssl rand -base64 32`.

In `development` the boot only logs an `error!` and continues, so `just run-api` still works against the empty defaults - but data encrypted under the empty key is readable by anyone, so never expose a dev instance.

> **Rotating `token_encryption_key` is destructive:**
> The ciphertext carries **no key-version tag**, so changing this key makes **every existing row permanently undecryptable** (`aead::Error`) - rows are re-encrypted only on their next write. Set it **once** per deployment and never change it on a live instance. A mid-flight flip between "set" and "unset" is the exact root cause of the ZAF-1196 credential-loss incident. If you must rotate, plan a coordinated re-encrypt of every affected column.

### Next.js apps - `.env.local`

`apps/web`, `apps/admin` and `apps/id` each ship a `.env.example`. Copy it next to the app and fill it in:

```bash
cp apps/web/.env.example apps/web/.env.local
cp apps/admin/.env.example apps/admin/.env.local
cp apps/id/.env.example apps/id/.env.local
```

The variables you will actually touch first:

| Variable | App | Description |
|----------|-----|-------------|
| `LUMIO_API_URL` | web, admin, id | Server-side API base - `http://localhost:3000/v1` |
| `LUMIO_INTERNAL_TOKEN` | web, admin, id, stats | Shared secret for SSR → API calls; must match `rate_limiting.internal_token` in the API config (`dev-internal-token` locally) |
| `LUMIO_AUDIT_INGEST_KEY` | id | System key (`lm_sys_*` carrying the narrow `audit:ingest` grant) that apps/id uses to post user-scope audit events to `POST /v1/internal/audit-ingest`. Leave unset locally - audit emission is then simply skipped and login still works. In staging/production, mint a dedicated key carrying **only** the `audit:ingest` chip from the admin app (**System → System Keys**) and set it here - see [Provisioning the apps/id audit-ingest key](../admin/system-keys.md#provisioning-the-appsid-audit-ingest-key). While it is unset the whole apps/id audit trail is dropped and `GET /api/health` reports `audit_ingest_configured: false` (see [Audit Events → Events that originate outside the API](../developer-guide/audit-events.md#events-that-originate-outside-the-api-appsid-ingest)) |
| `AUTH_SECRET` | id | NextAuth session secret |
| `AUTH_URL` | id | Public base URL of the ID app - `http://localhost:4002`. NextAuth builds its OAuth callbacks from it, and the ID app's own login redirect, `callbackUrl` and absolute share-image URLs use its origin; behind a reverse proxy the request URL carries the container's bind address (`0.0.0.0:4002`), so this must be the public host |
| `AUTH_{PROVIDER}_ID` / `AUTH_{PROVIDER}_SECRET` | id | OAuth login credentials per provider (see [OAuth Provider Setup](/getting-started/oauth-setup)) |
| `LUMIO__AUTH__DISCORD_CLIENT_SECRET` | api | Discord login app secret matching `AUTH_DISCORD_SECRET` in the ID app; needed for rotating login-token refresh |
| `LUMIO__AUTH__DISCORD_BOT_CLIENT_ID` / `LUMIO__AUTH__DISCORD_BOT_CLIENT_SECRET` | api | Global Discord bot application used for verified server invites; separate from the login pair and the static Bot Token |
| `DISCORD_BOT__API__SYSTEM_KEY` | discord-bot | System key created under **Admin → System Keys** in the same environment with `bots:internal`; the API does not provision System keys from config |
| `LUMIO_APP_URL` / `NEXT_PUBLIC_APP_URL` | web, admin | Public URL of the app itself; `LUMIO_APP_URL` is read on the server per request and wins. It is the origin of the login `callbackUrl` and of the OAuth connection-callback redirects. On web it also supplies canonical, language-alternate, share-image and sitemap URLs; only `https://lumio.vision` allows indexing. An unset or invalid value yields no canonical or language alternates and blocks indexing. Behind a reverse proxy the request URL carries the container's bind address (`0.0.0.0:<port>`), and the `Host` / `X-Forwarded-Host` headers are never trusted for it |
| `LUMIO_STATS_URL` | stats | Public origin of the Stats app, read on the server per request. It supplies the canonical, language-alternate and sitemap URLs. Only `https://stats.lumio.vision` allows indexing: every other value, including the prod origin host `lumio.stats.prod.zaflun.dev`, and an unset or invalid one make every response `noindex, nofollow` (meta tag and `X-Robots-Tag`), `robots.txt` `Disallow: /` and the sitemap routes 404. There is no `NEXT_PUBLIC_*` variant and no localhost fallback |
| `LUMIO__PUBLIC_STATS__SITEMAP_PLATFORMS` | api | Comma-separated server-side `[public_stats].sitemap_platforms` allowlist for channel sitemap files. The default is `twitch,kick`; the client cannot expand it. The sitemap includes only allowlisted channels with a login and a stream in the last 12 months. Keep it aligned with the Stats app's indexable channel-platform list. |
| `NEXT_PUBLIC_ID_URL` | web | Public URL of the ID app |
| `NEXT_PUBLIC_OVERLAY_URL` | web | Public overlay host - `http://localhost:4000/overlay` locally |
| `LUMIO_SUPERVISOR_URL` / `LUMIO_EXTENSION_RUNTIME_URL` | web | Extension sandbox hosts - `http://localhost:3200` / `http://localhost:3201` locally. Read on the server per request, so a deployed container takes them from its runtime env. `NEXT_PUBLIC_SUPERVISOR_URL` / `NEXT_PUBLIC_EXTENSION_RUNTIME_URL` are the fallback; they only apply where they were present at `next build` (local checkouts) |
| `LUMIO_EXTENSION_RUNTIME_ORIGIN_TEMPLATE` | web | Per-extension runtime origin, e.g. `https://{label}.lumio.ext.staging.zaflun.dev`; `{label}` becomes the extension id as 32 hex characters and must match the template the Supervisor and Runtime were built with. Unset = every extension shares the runtime URL above, so removing the variable and restarting the container is the rollback. Falls back to `NEXT_PUBLIC_EXTENSION_RUNTIME_ORIGIN_TEMPLATE`. Empty values count as unset |
| `COOKIE_DOMAIN` | web, admin, id | Only needed for cross-subdomain deployments; leave unset locally. Must be identical across the three apps |

### `LUMIO_WEB_URL` / `NEXT_PUBLIC_WEB_URL`

Absolute URL of the `apps/web` app, read by `apps/id`. It is what the ID app redirects to after a successful login (`/dashboard`, `/dashboard/settings/channel/connections`, `/dashboard/settings/channel/subscription`). `LUMIO_WEB_URL` takes precedence; `NEXT_PUBLIC_WEB_URL` is the client-side mirror.

- **Default in code:** `http://localhost:4000`
- **Staging:** `https://lumio.web.staging.zaflun.dev`
- **Production-preview:** `https://lumio.web.prod.zaflun.dev`
- **Production:** `https://lumio.vision`

`apps/web` itself does NOT need this variable - it uses relative paths because it hosts those pages.

### Environment Variable Naming

Every TOML key in `apps/api/config/*.toml` is overridable via an environment variable using the format `LUMIO__<SECTION>__<KEY>` - **double underscore between the prefix and the first segment, and double underscore between every nested segment**. Examples:

| TOML path | ENV var |
|-----------|---------|
| `database.url` | `LUMIO__DATABASE__URL` |
| `auth.token_encryption_key` | `LUMIO__AUTH__TOKEN_ENCRYPTION_KEY` |
| `webhooks.youtube_secret` | `LUMIO__WEBHOOKS__YOUTUBE_SECRET` |
| `webhooks.kick_public_key` (optional pin) | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY` |
| `webhooks.kick_public_key_observer.refresh_interval_secs` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__REFRESH_INTERVAL_SECS` |
| `youtube.innertube_observer.api_key_override` | `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__API_KEY_OVERRIDE` |
| `kick.realtime.enabled` | `LUMIO__KICK__REALTIME__ENABLED` |

The override priority is `default.toml < {env}.toml < local.toml < ENV vars`, so an env-var always wins.

Kick event delivery needs no signing-key setup: the API fetches Kick's public RSA key from `https://api.kick.com/public/v1/public-key` itself and refreshes it (`[webhooks.kick_public_key_observer]`, fail-closed). `webhooks.kick_public_key` is only an optional pin. See [Kick webhook setup](/getting-started/oauth-setup#webhooks-event-delivery) and [Kick Webhook Public Key](/developer-guide/kick-webhook-public-key).

The **Kick chat-moderation listener** (`[kick.realtime]`) needs no setup either: it picks up messages deleted and users unbanned on kick.com from Kick's unofficial public chat socket, with its public key fetched and refreshed at runtime. `LUMIO__KICK__REALTIME__ENABLED=false` turns it off, `LUMIO__KICK__REALTIME__ALERT_WEBHOOK_URL` routes its two alarms (cold boot, Pusher no longer offered) to Discord, and `LUMIO__KICK__REALTIME__APP_KEY_OVERRIDE` + `LUMIO__KICK__REALTIME__CLUSTER_OVERRIDE` are an emergency pin only. All keys: [Kick Chat-Moderation Listener → Configuration](/developer-guide/kick-chat-listener#configuration).

### 7TV event listener

The API listens to the public 7TV EventAPI for changes to the active emote
sets of connected Twitch, Kick and YouTube channels. No 7TV key or inbound
webhook is needed. `[seventv]` in `apps/api/config/default.toml` accepts these
overrides:

| Key | Environment variable | Default |
|-----|----------------------|---------|
| `events_enabled` | `LUMIO__SEVENTV__EVENTS_ENABLED` | `true` |
| `ws_url` | `LUMIO__SEVENTV__WS_URL` | `wss://events.7tv.io/v3` |
| `max_subscriptions_per_connection` | `LUMIO__SEVENTV__MAX_SUBSCRIPTIONS_PER_CONNECTION` | `450` |
| `roster_refresh_secs` | `LUMIO__SEVENTV__ROSTER_REFRESH_SECS` | `600` |

`events_enabled = false` stops 7TV event capture and event-driven emote-cache
refresh; the normal cache TTL still applies. See the [7TV Event Listener](/developer-guide/seventv-event-listener)
for the roster, privacy boundary and cache behaviour.

### Platform Credential Sources

Channel and bot OAuth flows choose their OAuth app source from the API config. The flat `[platform_credentials]` table applies to **channel** connections. The nested `[platform_credentials.bot]` table applies to **bot** connections.

```toml
# Channel-credential source. The flat form is channel.
[platform_credentials]
twitch = "system"
kick = "system"
youtube = "account"
spotify = "account"

# Bot-credential source. Discord invites use the global bot app; its gateway token is static.
[platform_credentials.bot]
twitch = "system"
kick = "system"
youtube = "system"
discord = "system"
```

Allowed values are `"system"` and `"account"` for OAuth channel and bot platforms. `system` means the OAuth app pair comes from the global config keys in `[auth]`; `account` means the pair comes from the encrypted per-account `app_credentials` row. Discord bot accepts only `"system"`; an `"account"` override is ignored, and a missing Discord bot app pair makes server invites fail closed.

ENV overrides use the same nested naming convention:

```text
LUMIO__PLATFORM_CREDENTIALS__TWITCH=system
LUMIO__PLATFORM_CREDENTIALS__YOUTUBE=account
LUMIO__PLATFORM_CREDENTIALS__BOT__TWITCH=system
LUMIO__PLATFORM_CREDENTIALS__BOT__YOUTUBE=system
```

The global system OAuth app pairs live in `[auth]`:

| TOML path | ENV var | Notes |
|-----------|---------|-------|
| `auth.twitch_channel_client_id` | `LUMIO__AUTH__TWITCH_CHANNEL_CLIENT_ID` | Twitch channel/bot system app; falls back to `auth.twitch_client_id` when empty |
| `auth.twitch_channel_client_secret` | `LUMIO__AUTH__TWITCH_CHANNEL_CLIENT_SECRET` | Twitch channel/bot system app secret |
| `auth.kick_channel_client_id` | `LUMIO__AUTH__KICK_CHANNEL_CLIENT_ID` | Kick channel/bot system app; no login fallback |
| `auth.kick_channel_client_secret` | `LUMIO__AUTH__KICK_CHANNEL_CLIENT_SECRET` | Kick channel/bot system app secret |

### YouTube Chat Transport

YouTube chat uses InnerTube as the primary transport (zero quota cost). gRPC and REST fallbacks are available but disabled by default:

| ENV var | Purpose | Default |
|---------|---------|---------|
| `LUMIO__YOUTUBE__GRPC_FALLBACK_ENABLED` | Enable gRPC streamList fallback when InnerTube fails | `false` |
| `LUMIO__YOUTUBE__REST_FALLBACK_ENABLED` | Enable REST polling fallback when InnerTube and gRPC both fail | `false` |

### YouTube InnerTube Settings

The InnerTube chat poller ships with sensible defaults - no configuration is required. For operational overrides, these ENV vars map onto the `[youtube.innertube_observer]` block in `apps/api/config/default.toml`:

The InnerTube API key and client version are resolved at runtime in this order: **override (if set) → Redis cache → fresh `youtube.com` scrape → cold-boot constant**. The scraped values are cached in Redis (keys `lumio:yt:innertube_key` / `lumio:yt:innertube_version`, 24 h TTL) and a shared leader-elected refresher re-scrapes every 6 h by default (`REFRESH_INTERVAL_SECS`), so YouTube's periodic rotations are picked up without a restart. The two `*_OVERRIDE` vars below are an **emergency pin only** - leave them empty so auto-rotation stays in charge; a non-empty value wins over every other source, so it must never carry the ordinary current value. If an override *is* set, the API logs a single `WARN` the first time the credential is resolved - `innertube: rotation disabled by pin (client_version_override=…) - unset to resume auto-rotation` - so a forgotten pin never silently disables rotation (the API key value is redacted in that log line).

The `*_COLD_BOOT` vars are different: they configure the **last-resort** value used only when override, cache, and scrape have *all* come up empty (Stage 4). Because they are consulted last they can never pin the credential or disable auto-rotation - they are a fallback seed, not an override. `default.toml` ships them **set** to the current cold-boot values so a fresh deployment starts from a known-good credential; the daily drift-check keeps them in lockstep with the compiled constants (`DEFAULT_INNERTUBE_API_KEY` / `DEFAULT_CLIENT_VERSION`), which remain the last-ditch fallback if a field is cleared. Clear one (or set an empty ENV var) to fall back to the compiled constant, or set one to a newer value to give a fresh deployment a better cold-start credential without recompiling.

Reaching Stage 4 (cold boot) means Redis was empty **and** the `youtube.com` scrape failed - a fault, not a normal state. Point `COLD_BOOT_ALERT_WEBHOOK_URL` at the **same** Discord channel the InnerTube health CI (`.github/workflows/innertube-health.yml`) already posts to (do not create a second channel) and the refresher fires a **single** alert per incident. `COLD_BOOT_ALERT_AFTER_FAILURES` (default `1` = immediate) debounces it: raise it to require that many consecutive 6 h cycles at cold boot before alerting. Alerting is fail-open - an unset or unreachable webhook only produces a WARN log and never touches the chat path.

| ENV var | Purpose | Default |
|---------|---------|---------|
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__API_KEY_OVERRIDE` | Emergency pin for the InnerTube API key. Empty by default; set only if auto-detection fails after a Google rotation | _(empty)_ |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__CLIENT_VERSION_OVERRIDE` | Emergency pin for the InnerTube client version. Empty by default; set only if auto-detection fails | _(empty)_ |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__API_KEY_COLD_BOOT` | Stage-4 cold-boot API key; used only after override/cache/scrape all miss. Absent/empty → compiled `DEFAULT_INNERTUBE_API_KEY`. Never a pin | _(current key, shipped in `default.toml`)_ |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__CLIENT_VERSION_COLD_BOOT` | Stage-4 cold-boot client version; used only after override/cache/scrape all miss. Absent/empty → compiled `DEFAULT_CLIENT_VERSION`. Never a pin | `2.20260731.00.00` |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__CACHE_TTL_SECONDS` | Member + tier-badge entry TTL in Redis | `1209600` (14 d) |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__REFRESH_INTERVAL_SECS` | How often the shared refresher re-scrapes `youtube.com` and warms Redis | `21600` (6 h) |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__COLD_BOOT_ALERT_WEBHOOK_URL` | Discord webhook for the InnerTube health channel; alert on a Stage-4 cold-boot fall-through. Empty → alerting disabled (still WARN-logged). Reuse the CI channel, not a new one | _(empty)_ |
| `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__COLD_BOOT_ALERT_AFTER_FAILURES` | Consecutive cold-boot refresh cycles before alerting; `1` = immediate. `0` treated as `1` | `1` |

`api_key_override`, `api_key_cold_boot`, and `cold_boot_alert_webhook_url` are all wrapped in a `SensitiveString` and never appear in logs or tracing output.

### WebSocket

`[websocket]` configures the `/ws` endpoint (see [WebSocket API](../api-reference/websocket.md)).

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__WEBSOCKET__HEARTBEAT_INTERVAL` | Seconds between internal heartbeat ticks (credential re-validation and token-expiry checks; the server sends no `Ping`) | `5` |
| `LUMIO__WEBSOCKET__CLIENT_TIMEOUT` | Seconds without an inbound frame before the session is reaped; also bounds every outbound send | `30` |
| `LUMIO__WEBSOCKET__MAX_MESSAGE_SIZE` | Largest accepted inbound text frame, in bytes | `65536` |
| `LUMIO__WEBSOCKET__MAX_CHANNELS_PER_SESSION` | Channels one session may hold at once | `100` |
| `LUMIO__WEBSOCKET__SUBSCRIBE_BURST` | `subscribe`/`unsubscribe` frames a session may send back-to-back before `RATE_LIMITED`. A value below `max_channels_per_session` is raised to it at startup, with a warning | `120` |
| `LUMIO__WEBSOCKET__SUBSCRIBE_REFILL_PER_SECOND` | Sustained `subscribe`/`unsubscribe` frames per second once the burst is spent. `0` is treated as `1` | `5` |

### ECB exchange rates

`[fx]` controls the API's ECB reference-rate loader for Stream History. It fetches the daily file every six hours and imports the historical ZIP when the stored rate history is short. Disabling it leaves amounts in their source currencies and marks conversion unavailable; it does not block history reads. The base `source_url` has `eurofxref-daily.xml` and `eurofxref-hist.zip` appended. Downloads are size-capped (2 MiB for the daily file, 8 MiB for the history ZIP, 32 MiB for the CSV inside it); a larger response is rejected and retried on the next tick.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__FX__ENABLED` | Load ECB reference rates | `true` |
| `LUMIO__FX__SOURCE_URL` | Base URL of the ECB rate files | `https://www.ecb.europa.eu/stats/eurofxref` |
| `LUMIO__FX__REFRESH_INTERVAL_SECS` | Daily-file refresh interval in seconds | `21600` |

### Stream history command prefixes

`[history] command_prefixes` sets the prefixes a chat message must start with to count as a command in the Stream History report's command list. The default is `["!", "#"]`: `!` is the convention of third-party bots (Nightbot, StreamElements, Fossabot), `#` counts hashtag-style commands. After the prefix, the name must start with a letter (`[A-Za-z][A-Za-z0-9_-]{0,31}`). The list **must include the `bot.prefix` of Lumio's chat bots**: the bots read their prefix from their own service config, which the API does not see. A multi-character prefix is allowed; the longest match wins. Changing the list affects sessions finalized afterwards and reports built from the chat log; frozen reports keep their list. See [Stream History → Links and commands](../features/stream-history.md#links-and-commands).

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__HISTORY__COMMAND_PREFIXES` | Comma-separated command prefixes | `!,#` |

### Chat Retention

`chat_retention_days` comes from the account's `account_limits` override when set, otherwise its plan (Free 365 days; Pro 1095 days). A background sweep hard-deletes older chat messages and events in TimescaleDB; a separate sweep deletes chatter profiles, notes and moderation records in PostgreSQL after the same effective window, capped at 1095 days. A downgrade shortens the window on the next daily sweep. The sweeps are gated so dev/test/staging environments keep their history (see [Chat → Retention](../features/chat.md#retention) and [Chatter retention](../features/chat.md#chatter-retention)).

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__CHAT__RETENTION_ENFORCEMENT_ENABLED` | Master on/off switch for the retention sweep. Off in `default.toml`/staging; on in `production.toml` | `false` (dev) · `true` (production) |
| `LUMIO__CHAT__RETENTION_SWEEP_INTERVAL_SECS` | How often the sweep runs. Ignored when enforcement is off; a sweep also runs once on startup | `86400` (24 h) |
| `LUMIO__CHAT__ORPHAN_SWEEP_ENABLED` | Delete the chatter PII (chat, events, `platform_users`, notes, moderation log) of accounts that no longer exist ([Chat → Erasure](../features/chat.md#erasure-gdpr-art-17)). Only correct when the TimescaleDB belongs to this database alone | `false` (dev) · `true` (production) |
| `LUMIO__CHAT__ORPHAN_SWEEP_INTERVAL_SECS` | How often the orphan sweep runs; a sweep also runs once on startup | `86400` (24 h) |
| `LUMIO__CHAT__CHATTER_RETENTION_ENABLED` | Delete chatters and moderation records (moderation-state chatters, notes, moderation log) after the account's plan window, at most 1095 days ([Chat → Chatter retention](../features/chat.md#chatter-retention)) | `false` (dev) · `true` (production) |
| `LUMIO__CHAT__CHATTER_RETENTION_INTERVAL_SECS` | How often the chatter retention sweep runs; a sweep also runs once on startup. 86400 is the maximum, because a row outlives its window by up to one interval: the API refuses to start with a larger value or `0` | `86400` (24 h) |

### Shopify app

The public Lumio Shopify app (`[shopify]`). Setup in the Shopify Dev Dashboard: [OAuth setup → Shopify](./oauth-setup.md#shopify).

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__SHOPIFY__CLIENT_ID` | Client ID of the app | empty (Shopify not configured) |
| `LUMIO__SHOPIFY__CLIENT_SECRET` | Client secret; signs the embedded app's ID tokens, the launch query and every webhook, and authenticates the token exchange. ENV only | empty (Shopify not configured) |
| `LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS` | The previous client secret while a rotation is in progress; verifiers (ID token, launch query, webhooks) try it after the current one (the metric `shopify_client_secret_matches_total{secret="previous"}` shows when it is no longer used; steps in [Shopify → Client-secret rotation](../features/shopify.md#client-secret-rotation)). Must differ from the client secret, or the API refuses to start. ENV only | empty (no rotation) |
| `LUMIO__SHOPIFY__API_VERSION` | GraphQL Admin API version every call pins | `2026-10` |
| `LUMIO__SHOPIFY__SCOPES` | Comma-separated scopes the app needs; the token exchange checks Shopify's scope readback against it (the scopes Shopify grants come from `apps/shopify/shopify.app.<env>.toml`) | `read_orders,read_products,read_legal_policies` |
| `LUMIO__SHOPIFY__APP_STORE_URL` | The App Store listing the connect page links to | empty |

The embedded admin page `apps/shopify` (a Next.js app on its own origin) reads these at request time:

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO_API_URL` | API base including `/v1`; the page's route handlers forward to `/v1/shopify/embedded/*` | `http://localhost:3000/v1` |
| `LUMIO_WEB_URL` | Lumio web app origin for "In Lumio öffnen" (`NEXT_PUBLIC_WEB_URL` as fallback) | `http://localhost:4000` |
| `LUMIO__SHOPIFY__CLIENT_ID` | Same value as the API: the `shopify-api-key` meta tag for App Bridge and the theme editor deep link | empty |
| `LUMIO__SHOPIFY__CLIENT_SECRET` / `LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS` | Same values as the API: verify the `hmac` of Shopify's launch query, which decides `frame-ancestors`. Without them every page answers `frame-ancestors 'none'` and cannot be embedded. ENV only | empty |

The web app (`apps/web`) reads one Shopify value at request time:

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO_SHOPIFY_APP_HANDLE` | The app's `handle` from `apps/shopify/shopify.app.<env>.toml` (`lumio-staging` on staging). The Shopify card's "Open in Shopify" opens `https://admin.shopify.com/store/<store>/apps/<handle>`. Lowercase letters, digits and `-`; anything else reads as the default | `lumio` |

### Abuse report retention

Closed copyright [abuse reports](../admin/abuse-reports.md) (status `resolved` or `rejected`) hold the reporter's name, e-mail address and reason. A daily worker deletes them once the case has been closed for longer than the configured period; the privacy policy promises three years (§ 195 BGB). Open (`pending`) reports are never deleted. The worker is always on (a legal maximum has no off switch) and also runs once on startup.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__ABUSE_REPORTS__RETENTION_YEARS` | Years a closed report is kept after it was closed (`abuse_reports.retention_years`). Values below 1 count as 1 | `3` |

### Chatter List

The [chatter list](../features/chatter-list.md) polls a platform while someone has the panel open (a `chatters:{account_id}` WebSocket subscriber) and — with `live_polling` — while the stream is live for accounts that opened the list in the last 7 days. Cost of live polling: one Twitch Helix list call per 30 s and one Kick web list call per 60 s per live account that used the list in the last 7 days; nothing for accounts that never use it. `[chatters]` holds the global settings; provider tables are `[chatters.twitch]` and `[chatters.kick]`. Kick uses kick.com’s undocumented active-chatters endpoint without an OAuth token or new scope; it lists recent writers, not lurkers. The ordinary chatter group is capped at 100, with the complete role groups and a full platform count.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__CHATTERS__ENABLED` | Global kill-switch for every provider. Off: every platform reports `available = false`, `reason = "disabled"`, and no poller starts | `true` |
| `LUMIO__CHATTERS__INTEREST_TTL_SECS` | Lifetime of the per-account interest key. Renewed every 5 s while a subscriber is connected; once it lapses the poller stops | `90` |
| `LUMIO__CHATTERS__RECENTLY_LEFT_RETENTION_SECS` | How long a chatter who left stays listed as `present = false` (recently left), counted from their `last_seen_at`; then they are dropped | `1800` |
| `LUMIO__CHATTERS__WANTED_MARKER_TTL_SECS` | Lifetime of the per-account `lumio:chatters:wanted:{account_id}` marker, renewed on every subscription | `604800` (7 days) |
| `LUMIO__CHATTERS__LIVE_POLLING` | Poll marked accounts while their stream is live, even with no panel open. `false` = panel-driven only (kill switch) | `true` |
| `LUMIO__CHATTERS__TWITCH__ENABLED` | Twitch provider switch (`reason = "disabled"` when off) | `true` |
| `LUMIO__CHATTERS__TWITCH__POLL_INTERVAL_SECS` | Seconds between two Helix snapshots while the list is polled | `30` |
| `LUMIO__CHATTERS__TWITCH__MAX_CHATTERS` | Chatters fetched per snapshot (1000 per Helix page); larger chats report `truncated` with Twitch's full `total` | `5000` |
| `LUMIO__CHATTERS__KICK__ENABLED` | Kick provider switch; with a Kick channel connection, off reports `reason = "disabled"` | `true` |
| `LUMIO__CHATTERS__KICK__POLL_INTERVAL_SECS` | Seconds between kick.com active-chatters reads; the source caches for 60 s | `60` |
| `LUMIO__CHATTERS__KICK__MAX_CHATTERS` | Lumio’s upper bound per snapshot. Kick itself lists at most 100 ordinary chatters plus its complete role groups, so the platform’s own cap can set `truncated` first | `5000` |

### Automation Worker

The API dispatches extension automation-node handlers to the [Automation Worker](../developer-guide/automation.md#automation-worker) over HTTP. Configured under `[automation_worker]` in `apps/api/config/default.toml`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__AUTOMATION_WORKER__URL` | Base URL of the Automation Worker (`apps/automation-worker`, no trailing slash) | `http://automation-worker:8091` |
| `LUMIO__AUTOMATION_WORKER__SYSTEM_KEY` | System key presented as `Authorization: SystemKey <key>`; must match the worker's `worker.system_key`. Empty (the default) disables extension-node dispatch and fails closed | _(empty)_ |

### Bot Module Worker (server functions)

The API runs extension handler server functions (`query()` / `mutation()` / `action()`, REST `/execute` and GraphQL `extensionExecuteHandler`) on the Bot Module Worker's V8 executor (`POST {url}/v1/server-functions/execute`). Configured under `[bot_module_worker]` in `apps/api/config/default.toml`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__BOT_MODULE_WORKER__URL` | Base URL of the Bot Module Worker (`apps/bot-module-worker`, no trailing slash) | `http://bot-module-worker:8090` |
| `LUMIO__BOT_MODULE_WORKER__SYSTEM_KEY` | System key presented as `Authorization: SystemKey <key>`; must match the worker's `worker.system_key`. Empty (the default) turns handler execution off: `/execute` answers `503 EXECUTOR_UNAVAILABLE` | _(empty)_ |

Give the worker a key of its own. Do not reuse an API System key that carries broader grants (for example `*:*`): the worker runs untrusted extension code, and a key it holds should open nothing on the API beyond what the worker needs.

### Automation triggers

Chat, keyword, command, event and timer triggers of [automations](../features/automations.md#trigger-path) run only when this switch is on. It is **off** in every shipped config (`default.toml`, `staging.toml`, `production.toml`). With it off, automations run only when executed manually. Turning it on for staging or production is a founder decision. Configured under `[automation]` in `apps/api/config/default.toml`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__AUTOMATION__TRIGGERS_ENABLED` | Starts the leader-elected trigger and timer workers (Redis lease `lumio:automation:triggers:leader`; one replica fires) | `false` |
| `LUMIO__AUTOMATION__MAX_CONCURRENT_EXECUTIONS` | Executions of one account that may run at once. A trigger at the cap is dropped and logged | `8` |
| `LUMIO__AUTOMATION__EXECUTION_TIMEOUT_SECS` | Wall-clock limit for one triggered execution. Keep it above the 1-hour Delay cap | `3900` |

### Bot outbound throttle

Every tenant shares the one Twitch bot connection, so the Twitch bot throttles its
outgoing messages with a token bucket and gives each built-in command a per-channel
cooldown. Configured under `[bot]` in `apps/twitch-bot/config/default.toml`. A send
that would have to wait more than 2 s for a token is dropped and logged as
`Outbound rate limit reached`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `TWITCH_BOT__BOT__OUTBOUND_MESSAGES_PER_30S` | Sustained outbound budget in messages per 30 s, across all channels. The default is Twitch's per-30 s limit for an account that is moderator in the channel; raise it only for a Twitch-verified bot account | `100` |
| `TWITCH_BOT__BOT__OUTBOUND_BURST` | Messages that may go out back-to-back before the sustained rate applies | `20` |
| `TWITCH_BOT__BOT__BUILTIN_COOLDOWN_SECS` | Per-channel cooldown of each built-in command (`!song`, `!np`, `!uptime`, `!commands`); `0` turns it off. The Kick and YouTube bots use a fixed 5 s | `5` |

### Handler-execution telemetry (workers)

Both handler-execution workers (`apps/bot-module-worker`, `apps/automation-worker`) optionally record per-execution telemetry into TimescaleDB - one `extension_errors` row on failure and one `extension_install_logs` row on every run (see [Developer Extension Endpoints](../api-reference/rest-api.md#developer-extension-endpoints)). The writer is **fail-open**: it never fails or delays a handler request, and is simply disabled when no TimescaleDB pool is configured. Env vars use each worker's own prefix - `BOT_MODULE_WORKER__…` and `AUTOMATION_WORKER__…`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `…__TIMESCALE__URL` | TimescaleDB connection URL. Omit the whole `[timescale]` section to disable the telemetry writer | _(unset → writer off)_ |
| `…__WORKER__TELEMETRY_SALT` | Per-deployment secret salt used to HMAC-anonymize account/install IDs in `extension_errors`. Set a stable value in production; an empty salt still hashes but is weaker | _(empty)_ |

### Worker registry sync

Each worker (`apps/bot-module-worker`, `apps/automation-worker`) populates its in-memory `InstallRegistry` from the API's internal handler-bundle feed on startup and re-syncs on a poll - see [Bot Modules → Worker sync-loop](../developer-guide/bot-modules.md#redis-channels). Configured under `[sync]`, with the env prefix `BOT_MODULE_WORKER__SYNC__*` and `AUTOMATION_WORKER__SYNC__*` respectively. When the section is not fully configured the worker starts with an empty registry (every request short-circuits) rather than failing.

| Variable (per worker prefix) | Purpose | Default |
| --- | --- | --- |
| `…__SYNC__ENABLED` | Run the registry sync loop | `true` |
| `…__SYNC__API_BASE_URL` | API origin the feed is served from (no trailing slash), e.g. `http://api:8080`. Empty disables the loop | _(empty)_ |
| `…__SYNC__SYSTEM_KEY` | System key presented to the feed as `Authorization: Bearer <key>`. Empty disables the loop | _(empty)_ |
| `…__SYNC__POLL_INTERVAL_SECS` | Full-snapshot re-sync interval. The Bot Module Worker applies install changes and the kill switch live over `[redis]`, so its poll is a safety net; without `[redis]` it polls at most every 30 s | Bot Module Worker `300`, Automation Worker `30` |

### Bot-module secrets key

Bot-module handlers read their extension's secrets with `ctx.secrets.get` (see [Bot Modules → V8 Execution](../developer-guide/bot-modules.md#v8-execution)). The API re-encrypts each value for the Bot Module Worker under a key that only these two services share, so the worker never holds `auth.token_encryption_key`. Set **the same** independent random value (`openssl rand -base64 32`) on both sides:

| Variable | Service | Purpose | Default |
| --- | --- | --- | --- |
| `LUMIO__EXTENSIONS__BOT_MODULE_SECRETS_KEY` | API | Wraps secrets for the worker's internal secrets feed. Empty turns `ctx.secrets` off (the feed answers `503`). A placeholder or a value under 16 characters aborts the boot outside development | _(empty)_ |
| `BOT_MODULE_WORKER__SYNC__SECRETS_KEY` | Bot Module Worker | Opens the wrapped values. Also needs `…__SYNC__API_BASE_URL` and `…__SYNC__SYSTEM_KEY`. Empty turns `ctx.secrets` off (calls throw `ctx.secrets is unavailable`); a placeholder or a value under 16 characters aborts the start | _(empty)_ |

Never reuse `auth.token_encryption_key` here. To rotate, restart the API and every worker with the new value together; expect up to 60 seconds of `ctx.secrets is unavailable`. Nothing stored is re-encrypted.

### Bot Module Worker `ctx.db`

Bot-module handlers read and write their extension's tables through the worker's own pool on the extensions database (the API's `[extensions.database]`, `lumio_extensions`). Each op runs through the same executor as the API's server functions, under the same row-level security; see [Bot Modules](../developer-guide/bot-modules.md). The API applies the extensions-database migrations (`apps/api/migrations/extensions/`) itself at startup, on its DDL pool. The worker only ever gets a DML login (dev stack: `lumio_ext_worker`), never the schema owner. At startup it refuses to run if that login is a superuser, has `BYPASSRLS`, or has `CREATE` or `TEMPORARY` on the database; if the database is unreachable at startup, `ctx.db` stays off until the next restart.

```sh
# dev stack
BOT_MODULE_WORKER__EXTENSIONS__DATABASE__URL=postgres://lumio_ext_worker:lumio_ext_worker@localhost:5434/lumio_extensions
```

| Variable | Purpose | Default |
| --- | --- | --- |
| `BOT_MODULE_WORKER__EXTENSIONS__DATABASE__URL` | Extensions database URL as a DML login of the `lumio_ext_dml` group (its own login, not the API's). Empty turns `ctx.db` off (calls throw `ctx.db is unavailable`) | _(empty)_ |
| `BOT_MODULE_WORKER__EXTENSIONS__DATABASE__MAX_CONNECTIONS` | Connections per worker replica. An op waits at most 100 ms (sync) / 1 s (async) for one, then throws `ctx.db: db busy`. Keep `20 × API replicas + 5 × worker replicas` plus headroom under the extensions Postgres `max_connections` | `5` |

### Bot Module Worker chat triggers

The Bot Module Worker runs extension **keyword** and **pattern** triggers that the bots publish on Redis (`lumio:botmod:msg:*`) and posts each handler's reply back through the bots - see [Bot Modules → Bot Module Worker](../developer-guide/bot-modules.md#bot-module-worker). It needs the same Redis instance as the API and the bots. Without a `[redis]` section the listener does not start and keyword/pattern triggers do nothing; command triggers (HTTP) are unaffected.

| Variable | Purpose | Default |
| --- | --- | --- |
| `BOT_MODULE_WORKER__REDIS__URL` | Redis URL (same instance as the API and the bots). Remove the `[redis]` section to run without chat triggers | `redis://:lumio@127.0.0.1:6379` |
| `BOT_MODULE_WORKER__CHAT_TRIGGERS__ENABLED` | Run the keyword/pattern trigger listener | `true` |
| `BOT_MODULE_WORKER__CHAT_TRIGGERS__MAX_IN_FLIGHT` | Handlers that may run at the same time; a trigger that arrives while all are busy is dropped with a warning | `32` |

### Bot Module Worker event triggers and timers

The Bot Module Worker also runs bot-module **event** handlers for the stream events the API publishes on `lumio:events:*`, and bot-module **timers** - see [Bot Modules → Bot Module Worker](../developer-guide/bot-modules.md#bot-module-worker). Both need `[redis]`; timers also need a configured `[sync]` section, because the timer list comes from the handler feed. Each event and each timer slot is claimed in Redis, so running several worker replicas runs each one once.

| Variable | Purpose | Default |
| --- | --- | --- |
| `BOT_MODULE_WORKER__EVENT_TRIGGERS__ENABLED` | Deliver stream events to bot modules that list them in `triggers.events` | `true` |
| `BOT_MODULE_WORKER__EVENT_TRIGGERS__MAX_IN_FLIGHT` | Event handlers that may run at the same time; a delivery that arrives while all are busy is dropped with a warning | `32` |
| `BOT_MODULE_WORKER__SERVER_FUNCTIONS__MAX_IN_FLIGHT` | Server-function handlers (posted by the API) that may run at the same time on this replica; a call that finds every slot busy is refused with `RATE_LIMITED` | `16` |
| `BOT_MODULE_WORKER__SERVER_FUNCTIONS__MAX_IN_FLIGHT_PER_ACCOUNT` | Of those, the handlers one account may run at the same time | `4` |
| `BOT_MODULE_WORKER__TIMERS__ENABLED` | Run bot-module timers (`triggers.timers` / `triggers.timer`) | `true` |
| `BOT_MODULE_WORKER__TIMERS__MAX_IN_FLIGHT` | Timer handlers that may run at the same time; a firing while all are busy is skipped | `32` |

### Bot-module handler actions

The `actions` a bot-module handler returns are run by the API, not by the worker or the bots: they are posted to the internal `POST /v1/internal/bot-modules/{install_id}/actions` endpoint. The Bot Module Worker posts them with its `[sync] api_base_url` and `system_key` (without both, its actions are dropped with a warning); the bots use their `[api]` settings. The key needs the `bots:internal` grant.

| Variable | Service | Purpose | Default |
| --- | --- | --- | --- |
| `LUMIO__EXTENSIONS__BOT_MODULE_ACTION_RATE_PER_MINUTE` | API | Most actions one bot-module install may run per minute. Over the cap an action is refused and logged once per minute; if Redis cannot count, actions are refused. `0` means the default | `120` |

### GeoIP

The optional GeoIP service resolves client IP addresses to a country/city using the free [MaxMind GeoLite2 City](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) database. It powers the **Location** column of the [Audit Log](../admin/audit-log.md#location-data). It is **disabled by default** - no MaxMind account is needed to run Lumio; leave `enabled = false` and the location fields simply stay empty.

When enabled with a license key, the API downloads the `.mmdb` database on startup if it is missing and, when `auto_update` is on, refreshes it every `update_interval_days`. All GeoIP state lives under `[geoip]` in `apps/api/config/default.toml`; every key is overridable via the `LUMIO__GEOIP__*` env vars below.

| Variable | Purpose | Default |
| --- | --- | --- |
| `LUMIO__GEOIP__ENABLED` | Master on/off switch. When `false`, no database is loaded and location fields stay empty | `false` |
| `LUMIO__GEOIP__DATABASE_PATH` | Path to the GeoLite2 City `.mmdb` file. The default lives under the container `WORKDIR` (`/app`); the runtime-base image pre-creates `/app/data/geoip` owned by uid 1001, so the file is downloadable and refreshable by the non-root user. Mount a persistent volume there to survive restarts | `/app/data/geoip/GeoLite2-City.mmdb` |
| `LUMIO__GEOIP__LICENSE_KEY` | MaxMind license key used to download/update the database. [Get a free key](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data). Without it, an existing database is still read but cannot be auto-downloaded | _(empty)_ |
| `LUMIO__GEOIP__ACCOUNT_ID` | MaxMind numeric account ID. Required (with the license key) for the Privacy Exclusions API | _(empty)_ |
| `LUMIO__GEOIP__AUTO_UPDATE` | Re-download the database on a schedule when it is older than `update_interval_days` | `false` |
| `LUMIO__GEOIP__UPDATE_INTERVAL_DAYS` | Minimum database age before a re-download. MaxMind publishes GeoLite2 weekly | `7` |
| `LUMIO__GEOIP__PRIVACY_EXCLUSIONS_ENABLED` | Honour MaxMind [Privacy Exclusions](https://dev.maxmind.com/geoip/privacy-exclusions-api/) (user geolocation opt-outs). Requires `license_key` + `account_id` | `false` |
| `LUMIO__GEOIP__PRIVACY_EXCLUSIONS_REFRESH_HOURS` | How often the cached exclusions list is refreshed | `24` |
| `LUMIO__GEOIP__PRIVACY_EXCLUSIONS_CACHE_PATH` | Where the exclusions list is cached for persistence across restarts. Lives on the same writable `/app/data/geoip` directory as the database | `/app/data/geoip/geoip-privacy-exclusions.json` |

For a one-off database refresh outside the server, run the `geoip-update` maintenance binary: `cargo run -p lumio-api --bin geoip-update -- --help`.

> **Privacy.** GeoIP derives only a coarse country/city from the IP - no precise coordinates are stored. Enabling `privacy_exclusions_enabled` makes Lumio respect MaxMind's Privacy Exclusions opt-out list so IPs of users who opted out are not resolved.

### Diagnostics file (Rust services)

Every Rust service can write a **selected** subset of its logs to a local rotating file, in addition to stdout. By default the subset is every warning and error of the service (`all_warnings`), plus the `ingest_diag::<platform>` capture lines for event types ingest does not understand yet. Payment-webhook logs are always excluded. The file's selection is independent of `[logging] level` and `RUST_LOG`. Details on the selection, redaction and read-back are in [Logging → Rust services: diagnostics file](../developer-guide/logging.md#rust-services-diagnostics-file).

Each key below is set under `[logging.diagnostics]` in the service's `config/` or through ENV. Replace `<PREFIX>` with `LUMIO` (api), `TWITCH_BOT`, `KICK_BOT`, `YOUTUBE_BOT`, `DISCORD_BOT`, `CRAWLER_TWITCH`, `BOT_MODULE_WORKER` or `AUTOMATION_WORKER`.

| Variable | Purpose | Default |
| --- | --- | --- |
| `<PREFIX>__LOGGING__DIAGNOSTICS__ENABLED` | Master switch. While off, no file and no directory is created. On in `staging.toml` for api, twitch-bot, kick-bot and youtube-bot, and in the api's `production.toml` | `false` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__DIR` | Target directory, relative to the working directory. In containers this is `/app/data/diagnostics`, which the runtime-base image creates (owned by uid 1001). Mount a host volume there | `data/diagnostics` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__ALL_WARNINGS` | Select every `warn` and `error` line of every component (auth, database, billing, routes, workers, ingest). Off: only the platform target sets below | `true` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__TWITCH` | Add the Twitch target set (IRC, Helix, EventSub, IRC tags, twitch-bot) | `true` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__KICK` | Add the Kick target set (API client, `kick*` workers, webhook route and event service, kick-bot) | `true` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__YOUTUBE` | Add the YouTube target set (InnerTube/gRPC client, YouTube and InnerTube-credential workers, webhook route, youtube-bot) | `true` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__FILTER` | Extra `EnvFilter` directives, merged after the platform sets. A directive for a target already in a set replaces it, and a bare level (`error`) replaces the `all_warnings` default. One comma-separated string, e.g. `twitch_irc=off,lo_kick_api=debug` | _(empty)_ |
| `<PREFIX>__LOGGING__DIAGNOSTICS__ROTATION` | `daily` or `hourly`. Boundaries are UTC | `daily` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__MAX_FILES` | Rotated files kept per service. This is the retention bound: 14 means 14 days with daily rotation. Must be at least 1 | `14` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__FORMAT` | `json` (one object per line, `.jsonl`) or `compact` (one text line, `.log`) | `json` |
| `<PREFIX>__LOGGING__DIAGNOSTICS__REDACT_USER_FIELDS` | Replace viewer names and message text with `[redacted]` in the file. Stdout is unaffected | `false` |

Files are named `<dir>/<service>.<YYYY-MM-DD>.jsonl` (`api`, `twitch-bot`, …), so several services can share one directory. A misconfiguration never stops the service: it logs one warning and keeps running on stdout only.

**Hosted deployments.** Mount a persistent host directory at `/app/data/diagnostics`; otherwise the file disappears with the container. Create that directory owned by uid 1001 before the first start (`sudo install -d -o 1001 -g 1001 <host-dir>`). The staging compose files mount `${DIAGNOSTICS_DIR:-./data/diagnostics}` (see `dev-stack/staging/README.md`). On the production host, add the same `volumes:` line to each service that enables the file:

```yaml
    volumes:
      - ${DIAGNOSTICS_DIR:-./data/diagnostics}:/app/data/diagnostics
```

### Error tracking (Rust services)

Every Rust service sends errors and warnings to Sentry through `lo-telemetry` when `[sentry]` is enabled and has a DSN. Each event carries `release = <service>@<version>`, the `service` and `target` tags, and a fingerprint of target plus message template. Viewer names and message text are removed before sending. Details: [Error Tracking → Rust backend](../developer-guide/error-tracking.md#rust-backend-lo-telemetry).

Each key below is set under `[sentry]` in the service's `config/` or through ENV, with the same `<PREFIX>` as above. Only these keys enable Sentry: a bare `SENTRY_DSN` is not read by these services.

| Variable | Purpose | Default |
| --- | --- | --- |
| `<PREFIX>__SENTRY__ENABLED` | Master switch. Needs a DSN as well | `false` |
| `<PREFIX>__SENTRY__DSN` | DSN from the Sentry project settings. An unparseable DSN leaves Sentry off | _(empty)_ |
| `<PREFIX>__SENTRY__ENVIRONMENT` | `environment` of every event | `development` |
| `<PREFIX>__SENTRY__TRACES_SAMPLE_RATE` | Performance trace sample rate, clamped to 0.0–1.0 | `1.0` (`0.1` for crawler-twitch) |
| `<PREFIX>__SENTRY__SAMPLE_RATE` | Event sample rate, clamped to 0.0–1.0 | `1.0` |
| `<PREFIX>__SENTRY__DEBUG` | Sentry SDK debug output | `false` |
| `<PREFIX>__SENTRY__EVENT_LEVEL` | Lowest log level that becomes an event: `warn` or `error`. Lower levels down to `info` become breadcrumbs. Any other value logs a warning and uses `warn` | `warn` |
| `<PREFIX>__SENTRY__MAX_EVENTS_PER_FINGERPRINT` | Volume guard: events with the same fingerprint sent per window. The rest is counted and reported as `suppressed_count` on the next event. `0` switches the guard off | `10` |
| `<PREFIX>__SENTRY__FINGERPRINT_WINDOW_SECS` | Volume guard window in seconds | `60` |

`innertube-proxy` has no TOML config. It enables Sentry from `SENTRY_DSN` and `SENTRY_ENVIRONMENT` (default `production`) and installs the same `lo-telemetry` tracing layers as the other services, so its `warn`/`error` logs become Sentry events. See [InnerTube Proxy → Logging and error tracking](../developer-guide/innertube-proxy.md#logging-and-error-tracking).

### Frontend Environment & Logging

`apps/web`, `apps/admin`, and `apps/id` share two env-vars that drive the [logger](../developer-guide/logging.md) and the [Sentry integration](../developer-guide/error-tracking.md). Set both the server-side and the `NEXT_PUBLIC_*` mirror so the browser bundle picks them up too.

| Variable | Allowed values | Default | Purpose |
|----------|---------------|---------|---------|
| `LUMIO_ENV` / `NEXT_PUBLIC_LUMIO_ENV` | `development` \| `staging` \| `production` | `development` | Logger threshold default + Sentry environment tag |
| `LUMIO_LOG_LEVEL` / `NEXT_PUBLIC_LUMIO_LOG_LEVEL` | `debug` \| `info` \| `warn` \| `error` | per env (debug/info/warn) | Override the auto-threshold |

Sentry env-vars per app (`apps/web`, `apps/admin`, `apps/id`, and `apps/shopify` on the server only) - leave blank locally to disable, fill them in the CI build / deployment environment for staging + production:

| Variable | Where | Purpose |
|----------|-------|---------|
| `LUMIO_PUBLIC_SENTRY_DSN` | Run time (browser + server) | Public DSN. Set this on deployed containers: the root layout hands it to the browser SDK per request (web, ID; after Functional consent) |
| `NEXT_PUBLIC_SENTRY_DSN` | Build time | Local-dev fallback only - frozen at `next build`, no effect on a prebuilt image |
| `SENTRY_DSN` | Server only | Optional override; falls back to `LUMIO_PUBLIC_SENTRY_DSN`, then `NEXT_PUBLIC_SENTRY_DSN`. `apps/admin` and `apps/shopify` run no browser SDK, so only this (or its fallbacks) applies there |
| `SENTRY_ORG` | Build (CI) | Sentry org slug for source-map upload |
| `SENTRY_PROJECT` | Build (CI) | Sentry project slug |
| `SENTRY_AUTH_TOKEN` | Build (CI) | Auth token for source-map upload |

Each app also has a `proxy.ts` (Next.js 16's renamed `middleware.ts`) that prints one structured line per HTTP request to the SSR terminal - including the real client IP (`x-real-ip` / `x-forwarded-for` / `cf-connecting-ip`) with IPv4/IPv6 family classification. See [Logging → Per-request access logging](../developer-guide/logging.md#per-request-access-logging-proxyts) for details.

## Verify Installation

1. `just stack-up` - all six containers report healthy.
2. `just migrate-status` - every migration shows as applied.
3. `just run-api` - the API answers on `http://localhost:3000/v1`. `GET /v1/graphiql` serves the GraphiQL IDE and `GET /v1/schema` the GraphQL SDL (both are on by default in `development` and gated by `[graphql].playground` / `[graphql].schema_sdl`). The REST surface is documented at `/v1/swagger-ui/` with the raw spec at `/v1/openapi.json` (both gated by `[docs].swagger_ui` / `[docs].openapi_json`; production turns the Swagger UI off).
4. `just dev-web` - visit `http://localhost:4000` and log in through the ID app on `http://localhost:4002`.

### Before you push

| Recipe | What it runs |
|--------|--------------|
| `just verify-all` | `cargo fmt --check` + clippy (`-D warnings`) + `cargo check` + ESLint + `tsc` - the fast inner loop |
| `just lint-all` | clippy + ESLint only |
| `just test-all` | `cargo test` (workspace) + the V8 extension tests + Vitest |
| `just verify-release` | `verify-all` **plus** regenerating the OpenAPI/GraphQL schemas and the Bazel vendor tree, failing on drift. Run this after a version bump or a `Cargo.lock` change - `verify-all` does not detect that drift |

## Passkey relying party configuration

The API's `[webauthn]` settings bind passkeys to the web and ID apps. `rp_id` is the shared relying-party domain, `rp_name` is the name shown by an authenticator, and `origins` is the exact list of browser origins allowed to register or use a passkey. The default local values are:

```toml
[webauthn]
rp_id = "localhost"
rp_name = "Lumio"
origins = ["http://localhost:4000", "http://localhost:4002"]
```

Staging uses `rp_id = "staging.zaflun.dev"` with `https://lumio.web.staging.zaflun.dev` and `https://lumio.id.staging.zaflun.dev`. Production uses `rp_id = "lumio.vision"` with `https://lumio.vision` and `https://id.lumio.vision`. The API checks origins exactly: do not include overlay, widget, admin or extension hosts. Environment overrides are `LUMIO__WEBAUTHN__RP_ID` and `LUMIO__WEBAUTHN__ORIGINS` (comma-separated, e.g. `https://lumio.vision,https://id.lumio.vision`); `rp_name` is also a TOML setting. **Never change `rp_id` after the first real passkey exists.** Existing passkeys are bound to that ID and would stop working.

---

## Getting Started / OAuth Provider Setup

Source: https://docs.lumio.vision/getting-started/oauth-setup

# OAuth Provider Setup

## Sign-in

The ID app offers Twitch, Kick, Google, Discord and verified email/password sign-in. Registration uses email and password; an address is usable only after the person clicks **Confirm** on the emailed link. The link does not sign anyone in. A matching email claim from a platform does not automatically link profiles.

If 2FA is enabled, the ID app offers a passkey, authenticator app code or recovery code after the password or platform callback and before the API creates a session or PKCE authorization code. A trusted device can bypass this prompt for 30 days. Native desktop and mobile flows finish on `/login/done`, which offers **Back to the app** if the browser did not open the app automatically. The callback is allowlisted and the app name comes from a fixed list.

Adding a platform login connection from **Security → Sign-in** requires a fresh confirmation on the existing session. Reconnecting the same provider account is exempt. The ID app returns a limited `link_result` value to the dashboard, which displays the outcome and clears the URL parameters.

This guide walks you through creating OAuth applications for each platform. Lumio uses distinct credential sources for login, channel, and bot flows. They are stored in different places and are not interchangeable:

| | Login credentials | System channel credentials | System bot credentials | Account channel/bot credentials |
|---|---|---|---|---|
| **Purpose** | User authentication ("Sign in with Twitch") | Lumio-managed channel OAuth apps | Lumio-managed bot OAuth apps | Per-account platform API access (chat, events, moderation) |
| **Stored in** | `apps/id/.env.local` **and** `apps/api/config/local.toml` | `[auth]` `*_channel_client_id` / `*_channel_client_secret` keys in the API | `[auth]` `*_bot_client_id` / `*_bot_client_secret` keys in the API | The `app_credentials` database table (AES-256-GCM encrypted) |
| **Entered by** | The operator, once, in config files | The operator, once per environment / provider app | The operator, once per environment / provider app | Each account, in **Dashboard → Connections → the platform tab → App** |
| **Scopes** | User-level, defined in `apps/id/src/lib/providers.ts` | Channel scopes, defined in `apps/api/src/platforms.rs` | Bot scopes, defined in `apps/api/src/platforms.rs` | Channel/bot scopes, defined in `apps/api/src/platforms.rs` |
| **Resulting record** | `login_connections` | `channel_connections`, pinned `credential_source = "system"` | `bot_connections`, pinned `credential_source = "system"` | `channel_connections` or `bot_connections`, pinned `credential_source = "account"` |

> **Caution:**
> Login credentials are not channel credentials, and channel credentials are not bot credentials. System channel and bot credentials are the global Lumio OAuth apps used only by connections pinned to `system`; account credentials are used only by connections pinned to `account`. The login scopes in `apps/id/src/lib/providers.ts` are **user-level** - they are not a subset of the channel scopes and must not be stripped on the assumption that they belong on the channel side.

A third surface - **bot connections** - is covered in [Bot Connections](#bot-connections) at the end of this guide.

## Redirect URI Registration Matrix

System-sourced channel connections, account bot connections, and admin global-bot connections use the unified web-host callback:

```text
{web.public_url}/api/connections/oauth/{platform}/callback
```

The callback must be served by the **same web host the user is signed in to**: for channel and account-bot connects the API completes the exchange only for the browser session that started the connect (the web callback forwards that session), so a callback on another host - without the session cookie - fails with `401`. The admin global-bot flow needs no session on the web host.

For production Twitch/Kick system apps, register:

```text
https://lumio.vision/api/connections/oauth/{platform}/callback
```

For staging, register:

```text
https://lumio.web.staging.zaflun.dev/api/connections/oauth/{platform}/callback
```

For local development, register:

```text
http://localhost:4000/api/connections/oauth/{platform}/callback
```

The server dispatches the callback by the OAuth `state` handle's `kind` (`channel`, `bot` or `global_bot`; the [Shopify app](#shopify) uses no OAuth callback) and `return_to`. Account/BYO channel connections and degraded bot flows still use source-specific legacy callback URLs because their authorize path emits the legacy state format.

### Login apps

Login OAuth belongs to the ID app. These apps are separate from system channel/bot apps.

| Platform | Production redirect URI | Staging redirect URI | Local redirect URI | Notes |
|----------|--------------------------|----------------------|--------------------|-------|
| Twitch login | `https://id.lumio.vision/api/auth/callback/twitch` | `https://lumio.id.staging.zaflun.dev/api/auth/callback/twitch` | `http://localhost:4002/api/auth/callback/twitch` | Twitch allows multiple redirect URIs per app, so the login pair can also serve as the Twitch channel fallback when the channel pair is unset and the app also registers the unified web callback. |
| YouTube / Google login | `https://id.lumio.vision/api/auth/callback/google` | `https://lumio.id.staging.zaflun.dev/api/auth/callback/google` | `http://localhost:4002/api/auth/callback/google` | The ID app provider slug is `google`; channel connections use the Lumio platform slug `youtube`. |
| Kick login | `https://id.lumio.vision/api/auth/callback/kick` | `https://lumio.id.staging.zaflun.dev/api/auth/callback/kick` | `http://localhost:4002/api/auth/callback/kick` | Kick accepts up to 10 redirect URIs per app, so one login app can register production, staging and local login callbacks. Keep the login app separate from the system channel/bot apps by design — it lives in the ID-app config with user-level scopes. |

### System channel and bot apps

System OAuth app pairs live in the API `[auth]` config. Channel apps use `*_channel_client_id` / `*_channel_client_secret`; dedicated bot apps use `*_bot_client_id` / `*_bot_client_secret`. The Channel app and Bot app for the same provider register the same callback in a given environment; the encrypted `state` handle selects whether Lumio redeems the code with the channel, account-bot, or admin global-bot secret pair.

| Platform / app | Production redirect URI | Staging redirect URI | Local redirect URI | Notes |
|----------------|--------------------------|----------------------|--------------------|-------|
| Twitch Channel app | `https://lumio.vision/api/connections/oauth/twitch/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/oauth/twitch/callback` | `http://localhost:4000/api/connections/oauth/twitch/callback` | Twitch supports multiple redirect URIs on one app. A single Twitch Channel app can carry production, staging and local callbacks when that matches the operator model. |
| Twitch Bot app | `https://lumio.vision/api/connections/oauth/twitch/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/oauth/twitch/callback` | `http://localhost:4000/api/connections/oauth/twitch/callback` | Dedicated bot keys are preferred. If absent, bot connects fall back to the Twitch channel pair, then to the Twitch login pair. |
| Kick Channel app | `https://lumio.vision/api/connections/oauth/kick/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/oauth/kick/callback` | `http://localhost:4000/api/connections/oauth/kick/callback` | Kick accepts up to 10 redirect URIs per app. A single Kick Channel app can carry production, staging and local callbacks when that matches the operator model. |
| Kick Bot app | `https://lumio.vision/api/connections/oauth/kick/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/oauth/kick/callback` | `http://localhost:4000/api/connections/oauth/kick/callback` | Keep the Bot app on a separate `client_id` from the Channel app for quota/suspension isolation, not because of any redirect-URI limit. Both apps register the same environment callback. |
| YouTube Bot app | `https://lumio.vision/api/connections/oauth/youtube/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/oauth/youtube/callback` | `http://localhost:4000/api/connections/oauth/youtube/callback` | YouTube channel connections remain BYO/account. The system callback is only for an operator-managed YouTube bot app. |

### Account/BYO callbacks

Account-owned credentials are entered per account in **Dashboard → Connections → the platform tab → App** and are stored in the database. These callbacks are legacy/BYO callbacks: register them only for account-managed connections, for local setups intentionally using account credentials, or for platforms that have degraded from `system` to `account` because no system pair is configured.

| Platform / flow | Production redirect URI | Staging redirect URI | Local redirect URI | Notes |
|-----------------|--------------------------|----------------------|--------------------|-------|
| Twitch BYO channel | `https://lumio.vision/api/connections/channel/twitch/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/channel/twitch/callback` | `http://localhost:4000/api/connections/channel/twitch/callback` | Needed only when Twitch channel connects use account credentials. |
| YouTube BYO channel | `https://lumio.vision/api/connections/channel/youtube/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/channel/youtube/callback` | `http://localhost:4000/api/connections/channel/youtube/callback` | YouTube channel connections are BYO/account; the platform slug is `youtube`, not `google`. |
| Kick BYO channel | `https://lumio.vision/api/connections/channel/kick/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/channel/kick/callback` | `http://localhost:4000/api/connections/channel/kick/callback` | Needed only when Kick channel connects use account credentials. |
| Spotify BYO channel | `https://lumio.vision/api/connections/channel/spotify/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/channel/spotify/callback` | `http://127.0.0.1:4000/api/connections/channel/spotify/callback` | Spotify rejects `localhost`; Lumio rewrites `localhost` to `127.0.0.1` only for Spotify local callbacks. |
| Account bot legacy callback | `https://lumio.vision/api/connections/bot/{platform}/callback` | `https://lumio.web.staging.zaflun.dev/api/connections/bot/{platform}/callback` | `http://localhost:4000/api/connections/bot/{platform}/callback` | Used only when an account bot flow degrades to account credentials instead of using a system bot/channel pair. |
| Admin global-bot legacy callback | `https://admin.lumio.vision/api/bot-connections/{platform}/callback` | `https://lumio.admin.staging.zaflun.dev/api/bot-connections/{platform}/callback` | `http://localhost:4001/api/bot-connections/{platform}/callback` | Kept for legacy/in-flight global bot authorizations. Current system global bots return through the web-host unified callback and then redirect back to Admin via `return_to`. |

Production needs four system apps for the Twitch and Kick system-managed paths: one Channel app and one Bot app per platform. Because both Twitch **and** Kick accept multiple redirect URIs per app, those same four apps also cover staging and local — register each environment's callback on the corresponding app. Add apps only if you deliberately want separate `client_id`s per environment for blast-radius isolation.

| Platform | Production system apps | Staging system apps | System callback |
|----------|------------------------|---------------------|-----------------|
| Twitch | 2 apps: Channel + Bot | same 2 apps | `https://lumio.vision/api/connections/oauth/twitch/callback` and `https://lumio.web.staging.zaflun.dev/api/connections/oauth/twitch/callback` |
| Kick | 2 apps: Channel + Bot | same 2 apps | one callback per environment, all registered on the same two apps: `.../api/connections/oauth/kick/callback` |

Kick accepts **up to 10 redirect URIs per OAuth app** (verified in the Kick developer dashboard, 2026-09-23; Kick's public documentation does not state the limit). One Kick app can therefore carry production, staging and local callbacks (three of the ten slots). Its Channel app and Bot app each register the same environment callback, for example `https://lumio.vision/api/connections/oauth/kick/callback`; the `state.kind` value selects whether Lumio uses the channel secret pair or the bot secret pair. Keeping Channel and Bot on separate apps is a quota/suspension-isolation choice, not a redirect-URI requirement. The login app is kept separate by design (it lives in the ID-app config with user-level scopes), but when no dedicated Kick Channel app is configured, Kick channel connects fall back to the login pair (`kick_client_id` / `kick_client_secret`) with a one-time warning (ZAF-1493) — the login app can register the channel callback in one of its ten redirect-URI slots.

YouTube bot credentials have dedicated `[auth]` key slots too (`youtube_bot_client_id` / `youtube_bot_client_secret`), but YouTube channel connections stay BYO/account and there is no YouTube channel system app to fall back to. Without the YouTube bot keys, the YouTube bot flow degrades to `account`.

---

## Twitch

### Developer Console

https://dev.twitch.tv/console

### Login Credentials (ID App)

1. Go to **Applications** → **Register Your Application**
2. Set **Name** to something like `Lumio Login`
3. Set **OAuth Redirect URL** to: `{ID_APP_URL}/api/auth/callback/twitch`
   - Local: `http://localhost:4002/api/auth/callback/twitch`
4. Set **Category** to `Website Integration`
5. Copy **Client ID** and generate a **Client Secret**
6. Add to `apps/id/.env.local`:
   ```env
   AUTH_TWITCH_ID=your_client_id
   AUTH_TWITCH_SECRET=your_client_secret
   ```

**Login Scopes** (requested automatically):

| Scope | Purpose |
|-------|---------|
| `openid` | OpenID Connect authentication |
| `user:read:email` | Read user email |
| `user:read:emotes` | Read user emotes |
| `chat:read` | Read chat messages |
| `chat:edit` | Send chat messages |
| `user:write:chat` | Write chat messages |
| `user:read:subscriptions` | Read user subscriptions |
| `moderator:read:chatters` | Read chatter list |
| `moderator:manage:chat_messages` | Delete chat messages |
| `moderator:manage:banned_users` | Ban/unban users |

**Username resolution.** Twitch's OIDC claim set carries **no** `display_name` — only `preferred_username`, the lowercase login. Right after the OAuth handshake the ID App's Twitch `profile()` therefore calls Helix `GET /users` with the user's fresh access token to recover the real (possibly localized) display name. `name` then carries the display name and `preferred_username` the login, so the login connection stores them in the correct `display_name` / `username` columns and the `users` row gets a distinct `display_name` and `login`. Without this lookup both would be the lowercase login, and every Twitch user's Lumio display name (sidebar, account switcher, profile) would show as their login. If the Helix call fails we fall back to the OIDC login for both.

### Channel Credentials

Twitch channel connections default to `system`. Configure a global Twitch channel app in the API `[auth]` config (`twitch_channel_client_id` / `twitch_channel_client_secret`) and register the unified callback:

```text
{web.public_url}/api/connections/oauth/twitch/callback
```

Twitch allows multiple redirect URIs on one app, so if the channel-specific pair is empty, Lumio may use the Twitch login pair as the system pair. If no global pair is available, new Twitch channel connects degrade to the account-credential path and use the legacy account callback:

```text
{WEB_URL}/api/connections/channel/twitch/callback
```

**Channel Scopes** (33 scopes, requested automatically):

| Scope | Purpose |
|-------|---------|
| `channel:read:subscriptions` | Read subscriber list and events |
| `channel:read:redemptions` | Read channel point redemptions |
| `channel:manage:redemptions` | Manage channel point redemptions |
| `channel:read:hype_train` | Read hype train events |
| `channel:read:polls` | Read poll data |
| `channel:manage:polls` | Create and manage polls |
| `channel:read:predictions` | Read prediction data |
| `channel:manage:predictions` | Create and manage predictions |
| `channel:read:goals` | Read channel goals |
| `bits:read` | Read cheer/bits events |
| `moderator:read:followers` | Read follower list |
| `moderator:read:suspicious_users` | Read suspicious user flags |
| `moderator:manage:suspicious_users` | Update suspicious user treatment |
| `moderator:manage:banned_users` | Ban and unban users |
| `channel:bot` | Send chat messages as the channel bot |
| `user:read:chat` | Read chat messages |
| `channel:read:ads` | Read ad schedule |
| `channel:manage:raids` | Cancel raids (Lumio does not start raids) |
| `channel:moderate` | Moderate chat |
| `moderator:read:blocked_terms` | Read blocked terms |
| `moderator:read:chat_settings` | Read chat settings |
| `moderator:read:unban_requests` | Read unban requests |
| `moderator:read:banned_users` | Read banned users list |
| `moderator:read:chat_messages` | Read chat messages as moderator |
| `moderator:read:warnings` | Read user warnings |
| `moderator:read:moderators` | Read moderator list |
| `moderator:read:vips` | Read VIP list |
| `moderator:read:chatters` | Read the connected chatters (Helix `GET /chat/chatters`) for the [chatter list](../features/chatter-list.md) |
| `moderation:read` | Read the moderator list (Helix Get Moderators) — the chatter list's moderator group |
| `channel:read:vips` | Read the VIP list (Helix Get VIPs) — the chatter list's VIP group |
| `moderator:manage:automod` | Receive held AutoMod messages and decisions |
| `moderator:manage:blocked_terms` | Requested for later blocked-term management; currently unused |
| `moderator:manage:automod_settings` | Requested for later AutoMod-level management; currently unused |

Reconnect an existing Twitch channel once to grant the AutoMod scopes. Lumio requests all three together; held messages need `moderator:manage:automod`, while the two management scopes are not used yet.

### Bot Credentials

Twitch bot connections default to `system`. Configure a separate Twitch bot app in `[auth]` with `twitch_bot_client_id` / `twitch_bot_client_secret` and register the same unified callback as the channel app:

```text
{web.public_url}/api/connections/oauth/twitch/callback
```

If the Twitch bot pair is empty, the bot flow falls back to the Twitch channel pair, then to the Twitch login pair, and logs a one-time warning. If neither bot nor channel/login keys are available, the bot flow degrades to `account`.

---

## YouTube / Google

### Developer Console

https://console.cloud.google.com/apis/credentials

### Prerequisites

1. Create a **Google Cloud project** (or use an existing one)
2. Enable **YouTube Data API v3** under **APIs & Services > Library**
3. Configure **OAuth consent screen** under **APIs & Services > OAuth consent screen**
   - User Type: **External** (or Internal for Google Workspace)
   - Add the scopes listed below
   - Add test users if app is in "Testing" status

### Login Credentials (ID App)

1. Go to **APIs & Services > Credentials** → **Create Credentials** → **OAuth 2.0 Client ID**
2. Application type: **Web application**
3. Set **Authorized redirect URI** to: `{ID_APP_URL}/api/auth/callback/google`
   - Local: `http://localhost:4002/api/auth/callback/google`
4. Copy **Client ID** and **Client Secret**
5. Add to `apps/id/.env.local`:
   ```env
   AUTH_GOOGLE_ID=your_client_id
   AUTH_GOOGLE_SECRET=your_client_secret
   ```

**Login Scopes:**

| Scope | Purpose |
|-------|---------|
| `openid` | OpenID Connect authentication |
| `email` | User email address |
| `profile` | User name and profile picture |
| `youtube.readonly` | Read YouTube channel data - also used at login to fetch `snippet.customUrl` for the username |
| `youtube.force-ssl` | YouTube Data API access (live chat) |

**Username resolution.** Right after the OAuth handshake the ID App calls `youtube/v3/channels?part=snippet&mine=true` with the user's fresh access token and stores `snippet.customUrl` (e.g. `cruex_de`) as the login connection's `username`. Without this lookup Google's OIDC profile only exposes `email` (typically a `…@pages.plusgoogle.com` pseudo-email), which would never match the YouTube display name a viewer actually `@`-mentions in chat. If the YouTube call fails (no channel attached to the Google account, scope revoked) we fall back to `email`. The handle drives both the multichat `@`-mention highlighter and the broadcaster-status fallback that unlocks moderation buttons before the broadcaster's first chat message.

### Channel Credentials

YouTube channel connections are BYO/account. Each account supplies its own Google Cloud OAuth client.

1. Create a **separate** OAuth 2.0 Client ID in the same Google Cloud project
2. Set **Authorized redirect URI** to: `{WEB_URL}/api/connections/channel/youtube/callback`
   - Local: `http://localhost:4000/api/connections/channel/youtube/callback`
   - The channel-connection platform slug is `youtube`, **not** `google` - only the ID App's login callback uses `google`.
3. Users enter their own Client ID + Secret in **Dashboard → Connections → the platform tab → App**

**Channel Scopes** (2 required scopes, 1 optional scope requested on every connection):

| Scope | Purpose |
|-------|---------|
| `youtube.readonly` (required) | Read channel, video, and live chat data |
| `youtube.force-ssl` (required) | Full YouTube Data API access (chat, comments) |
| `yt-analytics-monetary.readonly` (optional) | Read the channel's estimated revenue from YouTube Analytics |

### YouTube Analytics API {#youtube-analytics-api}

To show YouTube Analytics revenue in [Stream History](/user-guide/stream-history), prepare the Google Cloud project that holds the channel connection's OAuth client:

1. Enable **YouTube Analytics API** under **APIs & Services → Library**, alongside **YouTube Data API v3**.
2. On the OAuth consent screen, add `https://www.googleapis.com/auth/yt-analytics-monetary.readonly` under **Data Access**. The App Credentials wizard marks this scope **optional** and provides the full name to copy.
3. If the app is in **Testing**, add the channel owner as a test user. For an external app in production, Google may show an **unverified app** warning until its sensitive scopes are verified. Google's Testing refresh tokens can expire after seven days; publish the app and reconnect to obtain a production grant.
4. Connect or reconnect YouTube in **Manage → Connections**. Leave Google's checkbox for viewing revenue selected. Lumio requests the optional scope on every connect, but Google lets you decline it. The connect dialog explains that members with the **View revenue** permission (`history:revenue-read`) can see the YouTube amounts.

YouTube reports revenue only for channels in the **YouTube Partner Program**. Figures normally arrive **2–3 days after a stream** and may be corrected before they become final; until they arrive, the report shows the Lumio estimate. If the scope was declined, the channel is outside the Partner Program, or the API is disabled, the revenue area explains the next step. The optional scope does not create a general connection warning. The Analytics requests use the quota of **your own Google app**; Lumio makes at most one bundled revenue request per channel per day, usually none.

> **Info:**
> Both login and channel credentials request `access_type=offline` and `prompt=consent` to ensure refresh tokens are always issued.

### Bot Credentials

YouTube bot connections have a `system` credential mode but no channel-system app to fall back to. Configure `youtube_bot_client_id` / `youtube_bot_client_secret` in `[auth]` and register the unified callback when the deployment uses an operator-managed YouTube bot app:

```text
{web.public_url}/api/connections/oauth/youtube/callback
```

If the YouTube bot pair is empty, the YouTube bot flow degrades to `account`.

---

## Discord

### Developer Console

https://discord.com/developers/applications

### Login Credentials

Discord has **no channel connection**. It is a sign-in-only provider for users and a separate server-invite platform for Lumio's global bot. A Discord login cannot be assigned to a channel. The login and bot applications use separate credentials; the bot itself authenticates with a static token saved in Admin → Providers.

1. Go to **Applications** → **New Application**
2. Under **OAuth2**, copy **Client ID** and **Client Secret**
3. Add **Redirect URL**: `{ID_APP_URL}/api/auth/callback/discord`
   - Local: `http://localhost:4002/api/auth/callback/discord`
4. Add to `apps/id/.env.local`:
   ```env
   AUTH_DISCORD_ID=your_client_id
   AUTH_DISCORD_SECRET=your_client_secret
   ```

**Login Scopes:**

| Scope | Purpose |
|-------|---------|
| `identify` | Read user identity |
| `email` | Read user email |

The API needs the same Discord login Client ID and Secret under `[auth].discord_client_id` and `[auth].discord_client_secret` to validate the token audience and refresh login tokens. Discord refresh tokens rotate; keep the secret in the API environment as well as the ID app.

### Discord Bot App

Use a Discord application for the one global Lumio bot. Set `[auth].discord_bot_client_id` and `[auth].discord_bot_client_secret` in the API environment, then save its Bot Token under **Admin → Providers → Discord**. The Application ID and Secret are not entered in the admin form.

Register these bot-app OAuth redirects in the Discord Developer Portal:

```text
https://lumio.vision/api/connections/oauth/discord/callback
https://lumio.web.staging.zaflun.dev/api/connections/oauth/discord/callback
http://localhost:4000/api/connections/oauth/discord/callback
```

Enable **Requires OAuth2 Code Grant** for the bot application and set its **Install Link** to **None**. Lumio builds the invite itself with `bot applications.commands identify`, `integration_type=0`, and permissions `2147576832` (View Channels, Send Messages, Manage Messages, Embed Links, Read Message History, Use Application Commands). Never grant Administrator (`permissions=8`). `identify` makes Discord return a code and the confirmed server in the token response; Lumio revokes that user token after verification. The inviter needs **Manage Server** on the target server.

If connecting a server ends with *Discord did not confirm the server invitation*, the API log names the cause. `Discord rejected the guild invite code exchange` carries Discord's `error`: `invalid_client` means `[auth].discord_bot_client_secret` is not the **Client Secret** of the app in `discord_bot_client_id` (the Bot Token is a different value), and `invalid_grant` means the redirect URL does not match or the code was already used. The bot itself authenticates with its own `DISCORD_BOT__BOT__TOKEN`; a gateway close `4004 Authentication failed` means that token is wrong or was reset in the portal.

Enable the privileged **Server Members Intent** for member events and **Message Content Intent** for message-based features in the Bot settings. Discord requires verification once the bot reaches 100 servers. If either privileged intent is off, the bot reports `DisallowedGatewayIntents` on startup.

```toml
[auth]
discord_bot_client_id = "..."
discord_bot_client_secret = "..."
```

**Issuer:** the Discord provider in `apps/id/src/lib/providers.ts` sets `issuer: "https://discord.com"`. Discord appends the RFC 9207 `iss=https://discord.com` parameter to the OAuth callback, and Auth.js rejects any `iss` that differs from the provider's issuer — without the explicit value it expects its fallback `https://authjs.dev`. The setting triggers no OIDC discovery, because the authorization, token and userinfo endpoints are explicit URLs. Kick sets no `issuer`: it sends no `iss` today.

### Troubleshooting `unexpected "iss"`

If Discord sign-in **and** linking Discord from *Security → Sign-in* both end on `/login?error=Configuration`, and the ID app log shows a `CallbackRouteError` with `unexpected "iss" (issuer) response parameter value` (`expected: https://authjs.dev`), the Discord provider is running without its `issuer`. The callback carries `iss=https://discord.com` and fails before the sign-in or link step runs. Restore `issuer: "https://discord.com"` on the Discord provider in `apps/id/src/lib/providers.ts`; the regression test `apps/id/__tests__/lib/providers.test.ts` fails when it is missing. The Discord Developer Portal has no setting for this.

---

## Kick

Kick runs **OAuth 2.1**. Its `/oauth/authorize` mandates **both PKCE
(`code_challenge` + `code_challenge_method=S256`) and a `state` parameter**, even for
confidential clients that also send a `client_secret`; omitting **either** makes
`id.kick.com` answer with a `404` (not a `400`), which reads like a broken URL rather
than a protocol error. Its `/oauth/token` expects the client credentials as **body
parameters** (`client_secret_post`), not an `Authorization: Basic` header — the same
auth style our Rust token-refresh uses for Kick. This applies to every Kick app you
create below.

Lumio sends `code_challenge` + `code_challenge_method=S256` and `state` on the
authorize URL and the matching `code_verifier` on the token exchange for **all** Kick
flows (login, channel, bot, and the admin global bot). For the API-driven channel/bot
flows PKCE is generated server-side per authorize request; the login flow (`apps/id`,
NextAuth) pins `checks: ["pkce", "state"]` on the Kick provider so no `@auth/core`
default change can silently drop `state`. No extra configuration is required.

### Developer Console

https://kick.com/settings/developer

### Login Credentials (ID App)

1. Create a new application in the Kick Developer settings
2. Set **Redirect URL** to: `{ID_APP_URL}/api/auth/callback/kick`
   - Local: `http://localhost:4002/api/auth/callback/kick`
3. Copy **Client ID** and **Client Secret**
4. Add to `apps/id/.env.local`:
   ```env
   AUTH_KICK_ID=your_client_id
   AUTH_KICK_SECRET=your_client_secret
   ```
5. Set the **same** `client_id` as `kick_client_id` in the API `[auth]` config (see [API Server](#2-api-server-appsapiconfiglocaltoml) below). Kick is a first-class login provider on every token-exchange path (`POST /v1/auth/token`, `POST /v1/auth/authorize`, GraphQL `exchangeToken`, `POST /v1/auth/link`), and each validates the token audience against `kick_client_id`. If it is unset, Kick **login** — not just linking — fails closed (see the mandatory audience-validation note in the [API Server](#2-api-server-appsapiconfiglocaltoml) section).

**Login Scopes:**

| Scope | Purpose |
|-------|---------|
| `user:read` | Read user profile |
| `chat:write` | Send chat messages |
| `moderation:ban` | Ban, time out and unban users in the multichat and on the user info card |
| `moderation:chat_message:manage` | Delete chat messages |

Kick chat moderation (delete, timeout, ban) runs on the acting user's personal **Kick login** token, the same way Twitch moderation runs on the Twitch login token, so the moderation scopes sit on the login app. The API checks the stored login scopes before it calls Kick; a missing scope comes back as `login_scope_missing` and the dashboard shows "log in with Kick again". Kick only grants new scopes on a fresh authorize: a user who logged in with Kick before the moderation scopes were requested must **log in with Kick once more** (or use **Reconnect** on the Kick login connection under **Account → Profile**) to grant them. No migration is needed.

**User profile lookup:** after the token exchange the ID app reads the signed-in
user from Kick's official user route, `GET https://api.kick.com/public/v1/users`
(no `id` query = the token owner). That response is an envelope wrapping an array
— `{ "data": [ { "user_id", "name", "email", "profile_picture" } ], "message" }`
— so the provider unwraps `data[0]` and maps `user_id` → account id (stable,
required), `name` → display name and login name, `email`, and `profile_picture`
→ avatar. The legacy unofficial `https://api.kick.com/api/v1/user` route returns
`404` and must not be used.

### Channel Credentials

Kick channel connections default to `system`. Create a Kick Channel app and register the unified callback for each environment it serves — one app can carry production, staging and local, because Kick accepts up to 10 redirect URIs per app:

```text
{web.public_url}/api/connections/oauth/kick/callback
```

Set `kick_channel_client_id` and `kick_channel_client_secret` in the API `[auth]` config to give Kick channel connects a dedicated `client_id`. When those are unset, Kick channel connects **fall back to the Kick login pair** (`kick_client_id` / `kick_client_secret`), mirroring Twitch — Kick accepts up to 10 redirect URIs per app, so the login app can register the channel callback above alongside the login callback. The fallback logs a one-time warning so you register a dedicated channel app (every provider rate limit and subscription cap is scoped to the `client_id`). Only when **neither** the channel pair nor the login pair is configured do new connects degrade to the account-credential path and use the legacy account callback:

```text
{WEB_URL}/api/connections/channel/kick/callback
```

**Channel Scopes** (6 scopes):

| Scope | Purpose |
|-------|---------|
| `user:read` | Read user profile information |
| `channel:read` | Read channel information |
| `events:read` | Read channel events |
| `events:subscribe` | Subscribe to real-time events |
| `chat:write` | Send chat messages |
| `moderation:chat_message:manage` | Delete chat messages |

### Bot Credentials

Kick bot connections default to `system`. Create a Kick Bot app — kept on a separate `client_id` from the Channel app for quota/suspension isolation, not because of any redirect-URI limit — register the same unified callback as the Kick Channel app, and set `kick_bot_client_id` / `kick_bot_client_secret` in the API `[auth]` config. Both the Channel app and the Bot app register the same callback:

```text
{web.public_url}/api/connections/oauth/kick/callback
```

If the Kick bot pair is empty, the bot flow falls back to the Kick channel pair and logs a one-time warning. If neither pair is available, the bot flow degrades to `account`.

**Bot Scopes** (2 scopes):

| Scope | Purpose |
|-------|---------|
| `user:read` | Read the bot account's own profile — used right after the exchange to resolve the bot's display name via `GET /public/v1/users`. Required: without it the identity lookup returns `403` and the bot saves without a name. |
| `chat:write` | Send chat messages as the bot |

> **Note:**
> Adding `user:read` to the Kick bot scope set (ZAF-1510) **re-consents existing Kick bot connections**: Kick only grants the wider scope on a fresh authorize, so a bot connected before this change keeps its old grant until it is reconnected. No migration is needed — the next bot connect picks up `user:read` automatically.

### Troubleshooting a rejected token exchange

A **`401` at `https://id.kick.com/oauth/token`** with `error: invalid_client` means the `client_id` / `client_secret` pair Lumio presented is **rejected by Kick** — the secret is wrong or was rotated. It is **not** a `redirect_uri`, PKCE, or expired-code problem (those return `400 invalid_grant` / `invalid_request`). The fix is a setup action: regenerate the secret in the Kick Developer console and update the matching `[auth]` key, or confirm you pasted the *right* app's pair when running separate Channel, Bot, and Login apps.

Surrounding whitespace is **not** a cause: Lumio strips leading and trailing whitespace from every configured `client_id` / `client_secret` — the system `[auth]` keys and the per-account BYO `app_credentials` alike — on load, so a copy-pasted trailing newline or stray space can no longer produce this silent `401`. When it trims a system key it emits exactly one startup `warn` naming the config key (never the value), e.g. `OAuth credential carried surrounding whitespace and was trimmed on load, config_key=auth.kick_channel_client_secret`; re-set that key cleanly to silence it.

Lumio surfaces this without leaking secrets. The dashboard shows `Kick rejected the token exchange: invalid_client` (the OAuth code, never the raw upstream body), and the API log emits one `warn` naming which app was used:

```text
platform=kick credential_source=system client_id_hint=...6789
  status=401 Unauthorized oauth_error=invalid_client
  oauth_error_description="Client authentication failed"
```

`credential_source` (`system` / `account`) plus the last-4 `client_id_hint` identify the app **per failing request**, so you never have to grep the boot log for the one-time channel-uses-login-pair fallback warning: a channel connect that fell back to the login pair (see above) is still `system`, but its `client_id_hint` is the login app's id, not the channel app's.

To confirm a pair without waiting for a connect attempt, POST the `client_credentials` grant to the same endpoint with the pair in question:

```sh
curl -s -i -X POST https://id.kick.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=…' --data-urlencode 'client_secret=…'
```

`200` with an `access_token` means the pair is valid; `401 invalid_client` means it is not.
### Webhooks (event delivery)

The Kick **channel** app requests `user:read`, `channel:read`, `events:subscribe`, `chat:write`, `moderation:chat_message:manage`, `kicks:read`, `channel:rewards:read` and `ads:read`. The last three support KICKs, channel-point redemptions and ad-break status respectively. A connection lacking any of these scopes lists them in `missing_scopes` until the owner reconnects; no migration is needed. Ad-break status is polled only while a stream is live and once at finalization, not delivered by webhook. Full list: [Channel Connections & OAuth Scopes](../developer-guide/channel-connections-oauth-scopes.md#kick-8-scopes).

Real-time events (follows, subs, resubs, gift subs, KICKs, channel-points redemptions, bans, livestream status and metadata) reach Lumio via Kick **webhooks**. Lumio subscribes to the events automatically (`POST /public/v1/events/subscriptions`, using the `events:subscribe` channel scope above), but **Kick has no API to set the delivery URL** — it is a manual per-app setting:

1. Open **kick.com/settings/developer → Edit app** for the Kick **Channel** app.
2. Turn on the **"Enable Webhooks"** toggle.
3. Set **"Webhook URL"** to your API's public receiver:
   - Production: `https://api.lumio.vision/v1/webhooks/kick`
   - Otherwise: `{server.public_url}/v1/webhooks/kick` (the exact value is logged once by the Kick worker at API start).
4. **No signing-key setup.** The API fetches Kick's public RSA key itself from `https://api.kick.com/public/v1/public-key` (unauthenticated; the same key for every Kick app), caches it, and refreshes it every 6 h. The API host needs outbound HTTPS to `api.kick.com`. The check is fail-closed: if no key can be fetched and none is cached, every delivery returns `401` and the API logs an `ERROR`. Leave `webhooks.kick_public_key` empty. It is only an optional pin, for example for a host without egress, and when it is set, automatic rotation is off. Leave `webhooks.kick_secret` empty too. Kick does not issue a webhook shared secret, and the legacy HMAC value is not the OAuth Client Secret. Details: [Kick Webhook Public Key](../developer-guide/kick-webhook-public-key.md).

Because the URL is a single per-app field, **one Kick app serves one environment** — a shared receiver for all environments is not possible with a single app. Without this step the OAuth flow still succeeds and subscriptions register, but **no event is ever delivered** (chat still works — the Kick bot reads chat over Kick's Pusher WebSocket, which needs no webhook).

## Spotify

### Developer Console

https://developer.spotify.com/dashboard

### Channel Credentials Only

Spotify is **channel connection only** - there is no Spotify login.

1. Go to **Dashboard** → **Create App**
2. Set **Redirect URI** to: `{WEB_URL}/api/connections/channel/spotify/callback`
   - Local: `http://127.0.0.1:4000/api/connections/channel/spotify/callback`
   - Spotify rejects `localhost` redirect URIs, so Lumio rewrites `localhost` → `127.0.0.1` for Spotify (and only Spotify) when building the callback URL. Register the `127.0.0.1` form.
3. Under **"Which API/SDKs are you planning to use?"**, select both **Web API** and **Web Playback SDK**
4. Users enter their own Client ID + Secret in **Dashboard → Connections → the platform tab → App**

**Channel Scopes** (7 scopes):

| Scope | Purpose |
|-------|---------|
| `user-read-playback-state` | Read current playback state |
| `user-modify-playback-state` | Control playback (play, pause, skip) |
| `user-read-currently-playing` | Read currently playing track |
| `playlist-read-private` | Read private playlists |
| `playlist-read-collaborative` | Read collaborative playlists |
| `playlist-modify-public` | Modify public playlists |
| `playlist-modify-private` | Modify private playlists |

> **Spotify Auth Style:**
> Spotify uses `Authorization: Basic base64(client_id:client_secret)` for token refresh, unlike other platforms which send credentials in the POST body.

## Shopify

Lumio is **one public app in the Shopify App Store**, a system app like the Twitch/Kick channel apps. Its credentials live only in the API config `[shopify]`, never in `app_credentials`, and are never mixed with a login app. There is no Shopify login and no per-account Shopify app. How install and link work end to end: [Shopify](../features/shopify.md#install-and-link).

### Dev Dashboard

https://dev.shopify.com/dashboard — create the app under the zaflun organization with **public** distribution.

- **Embedded, Shopify-managed install.** The app runs inside the Shopify admin (App Bridge ID tokens + token exchange; Shopify: *Authenticate an embedded app without a template*). The app URL (the embedded app `apps/shopify` on its own origin), the redirect URL Shopify requires, the scopes and the webhook subscriptions are declared in `apps/shopify/shopify.app.<env>.toml` and deployed with `shopify app deploy`; Lumio requests no scopes and has no OAuth callback.
- **Scopes:** `read_orders,read_products,read_legal_policies`. The token exchange refuses a token whose scope readback lacks one of `[shopify] scopes`.
- **Protected customer data.** Order webhooks are protected customer data, so request **Level 1** access in the Partner Dashboard (*API access requests → Protected customer data*). Add the **Name** field (Level 2, with a data protection review) only if merchants should be able to show a customer label (`customer_display`); without it Shopify redacts the name and every label is empty. Development stores work without a review once the data and fields are selected.
- **Webhooks** are app-level subscriptions in `shopify.app.<env>.toml` (`{server.public_url}/v1/webhooks/shopify`), signed with the app's client secret; every installed store sends them, and a store that is not linked to a Lumio account is dropped on arrival. See [Webhooks → Shopify](../features/webhooks.md#shopify).
- **Compliance webhooks** are app configuration, not a per-shop subscription. Set them in each environment file, `apps/shopify/shopify.app.staging.toml` and `apps/shopify/shopify.app.production.toml`, before the App Store review:

  ```toml
  [[webhooks.subscriptions]]
  compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
  uri = "https://api.lumio.vision/v1/webhooks/shopify/compliance"
  ```

  The example uses production. Staging uses `https://lumio.api.staging.zaflun.dev/v1/webhooks/shopify/compliance`. Keep the app URL, `client_id`, scopes and all webhook URLs aligned with that environment, then run `shopify app deploy --config staging` or `shopify app deploy --config production` from `apps/shopify`. This releases Shopify's app configuration and extensions; the embedded web app is deployed separately. See [Shopify → Compliance webhooks](../features/shopify.md#compliance-webhooks).

### API config

```toml
[shopify]
client_id = "…"            # LUMIO__SHOPIFY__CLIENT_ID
# client_secret: ENV only  # LUMIO__SHOPIFY__CLIENT_SECRET
# client_secret_previous: ENV only, during a rotation  # LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS
api_version = "2026-10"    # LUMIO__SHOPIFY__API_VERSION
scopes = "read_orders,read_products,read_legal_policies"
app_store_url = ""         # the App Store listing, once published
```

With `client_id` or `client_secret` empty every Shopify surface answers `Shopify is not configured…`, and with `webhooks.require_signatures = true` every Shopify webhook is refused.

To rotate the client secret, set the new one as `client_secret` and the old one as `client_secret_previous` until Shopify no longer signs with the old one. The steps are in [Shopify → Client-secret rotation](../features/shopify.md#client-secret-rotation).

---

## Where to Configure

Login credentials must be set in **two places** - the ID App's `.env.local` and the API's `config/local.toml`. The API needs them for login token refresh and Twitch chat API calls.

### 1. ID App (`apps/id/.env.local`)

Used by NextAuth for the OAuth login flow:

```env
# NextAuth
AUTH_SECRET=generate-a-random-secret-here
AUTH_URL=http://localhost:4002

# Twitch
AUTH_TWITCH_ID=
AUTH_TWITCH_SECRET=

# Discord
AUTH_DISCORD_ID=
AUTH_DISCORD_SECRET=

# Google / YouTube
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=

# Kick
AUTH_KICK_ID=
AUTH_KICK_SECRET=

```

### 2. API Server (`apps/api/config/local.toml`)

`local.toml` is git-ignored and is the last file layer before environment variables (`default.toml → {env}.toml → local.toml → ENV`). The API uses these for login token refresh and Twitch chat operations. **They must match the ID App's credentials:**

```toml
[auth]
# Same credentials as AUTH_TWITCH_ID / AUTH_TWITCH_SECRET in ID App
twitch_client_id = "..."
twitch_client_secret = "..."
# Same credentials as AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET in ID App
google_client_id = "..."
google_client_secret = "..."
# Same credentials as AUTH_DISCORD_ID / AUTH_DISCORD_SECRET in ID App.
discord_client_id = "..."
discord_client_secret = "..."
# Same credentials as AUTH_KICK_ID / AUTH_KICK_SECRET in ID App
kick_client_id = "..."
kick_client_secret = "..."
# Global system Channel apps. Both Twitch and Kick fall back to the login pair
# above when their channel pair is unset (ZAF-1493); Kick accepts up to 10 redirect
# URIs per app, so the login app can also register the channel callback.
twitch_channel_client_id = "..."
twitch_channel_client_secret = "..."
kick_channel_client_id = "..."
kick_channel_client_secret = "..."

# Dedicated global system Bot apps. If one of these pairs is empty, that bot
# flow falls back to the platform's channel pair and logs a warning. If neither
# bot nor channel keys are configured, the bot flow degrades to account/BYO.
twitch_bot_client_id = "..."
twitch_bot_client_secret = "..."
kick_bot_client_id = "..."
kick_bot_client_secret = "..."
youtube_bot_client_id = "..."
youtube_bot_client_secret = "..."
discord_bot_client_id = "..."
discord_bot_client_secret = "..."

# AES-256-GCM key used to encrypt OAuth tokens and credentials at rest.
# MANDATORY outside development — the API refuses to boot in staging/production if
# this is empty/placeholder/< 16 chars, and CHANGING it makes every existing
# ciphertext permanently undecryptable. See installation.md → "Mandatory auth secrets".
# Generate with: openssl rand -base64 32
token_encryption_key = "..."
```

Every one of these keys can also be supplied as an environment variable, which wins over the file: `LUMIO__AUTH__TWITCH_CLIENT_ID`, `LUMIO__AUTH__TWITCH_CHANNEL_CLIENT_ID`, `LUMIO__AUTH__TWITCH_BOT_CLIENT_ID`, `LUMIO__AUTH__DISCORD_CLIENT_ID`, `LUMIO__AUTH__DISCORD_CLIENT_SECRET`, `LUMIO__AUTH__DISCORD_BOT_CLIENT_ID`, `LUMIO__AUTH__DISCORD_BOT_CLIENT_SECRET`, `LUMIO__AUTH__TOKEN_ENCRYPTION_KEY`, and so on.

> **Warning:**
> The credentials in `apps/api/config/local.toml` must be **identical** to those in `apps/id/.env.local`. The API uses them to refresh login tokens - if they don't match, token refresh will fail silently and users will be logged out.

`[auth].discord_client_id` validates the Discord login token audience. The matching `discord_client_secret` lets the API refresh that user's rotating login token. The separate `discord_bot_client_id` / `discord_bot_client_secret` pair signs the verified server invite; neither is an account-owned app credential.

> **Audience validation is mandatory (fail-closed):**
> On every token exchange (`POST /v1/auth/token`, `POST /v1/auth/authorize`, GraphQL `exchangeToken`, `POST /v1/auth/link`) the API validates both the token's **subject** (the claimed user) and its **audience** - the OAuth client the token was minted for. The audience each provider reports must match the configured client id:
> 
> | Provider | Audience source | Subject source | Must match |
> |---|---|---|---|
> | Twitch | `client_id` from `GET /oauth2/validate` | same response | `twitch_client_id` |
> | Google | `aud` from `/tokeninfo` | same response | `google_client_id` |
> | Discord | `application.id` from `/oauth2/@me` | same response | `discord_client_id` |
> | Kick | `client_id` from `POST /public/v1/token/introspect` | `user_id` from `GET /public/v1/users` | `kick_client_id` |
> 
> Kick is the only provider needing **two** requests: no single Kick endpoint carries both the subject and the audience. Its introspect route is flagged deprecated in Kick's OpenAPI but has no announced successor - if Kick removes it, Kick logins fail closed rather than skipping the check.
> 
> This blocks a confused-deputy attack where an attacker registers their own OAuth app, gets a victim to authorize it, and replays the victim-subject token against Lumio (ZAF-1015). The check is **fail-closed**: if a provider's client id is unset, token exchange for that provider **fails** (HTTP 500 / `INTERNAL_SERVER_ERROR`) rather than skipping the check. A foreign-audience token is rejected as an invalid credential (HTTP 401, audited as `user:login_failed`), identically to a subject mismatch. Set all four client ids in any deployment that serves logins for that provider.

#### System app environment variables

| Config key | Environment variable |
|------------|----------------------|
| `twitch_channel_client_id` | `LUMIO__AUTH__TWITCH_CHANNEL_CLIENT_ID` |
| `twitch_channel_client_secret` | `LUMIO__AUTH__TWITCH_CHANNEL_CLIENT_SECRET` |
| `kick_channel_client_id` | `LUMIO__AUTH__KICK_CHANNEL_CLIENT_ID` |
| `kick_channel_client_secret` | `LUMIO__AUTH__KICK_CHANNEL_CLIENT_SECRET` |
| `twitch_bot_client_id` | `LUMIO__AUTH__TWITCH_BOT_CLIENT_ID` |
| `twitch_bot_client_secret` | `LUMIO__AUTH__TWITCH_BOT_CLIENT_SECRET` |
| `kick_bot_client_id` | `LUMIO__AUTH__KICK_BOT_CLIENT_ID` |
| `kick_bot_client_secret` | `LUMIO__AUTH__KICK_BOT_CLIENT_SECRET` |
| `youtube_bot_client_id` | `LUMIO__AUTH__YOUTUBE_BOT_CLIENT_ID` |
| `youtube_bot_client_secret` | `LUMIO__AUTH__YOUTUBE_BOT_CLIENT_SECRET` |

### 3. Account Credentials (Database)

Account channel/bot credentials are **not** configured in files. Each user enters their own Client ID + Secret via **Dashboard → Connections → the platform tab → App**. They are stored AES-256-GCM encrypted in the `app_credentials` table, one row per `(account, platform)`. The resulting access/refresh tokens land in `channel_connections` or `bot_connections`, also encrypted.

---

## Bot Connections

Bot connections let Lumio post to chat with a bot identity instead of the channel identity. Twitch, YouTube, and Kick use OAuth bot tokens; Spotify has no bot connection. Discord uses a static global bot token plus a separate OAuth app for verified server invites.

OAuth bot connections default to the `system` credential source and use dedicated bot app keys from `[auth]`: `twitch_bot_client_id`, `kick_bot_client_id`, or `youtube_bot_client_id` plus the matching secret. Register the unified web-host callback for system bot flows:

```text
{web.public_url}/api/connections/oauth/{platform}/callback
```

The admin global-bot flow starts in Admin → Providers, returns through the web host, and redirects back to the admin Providers page through the state handle's `return_to`. For Discord, save the static global bot token in Admin → Providers and configure the invite app pair under `[auth]` as described above.

When a deployment has no global key pair for a bot platform, the account bot authorize path degrades to the legacy account source and uses:

```text
{WEB_URL}/api/connections/bot/{platform}/callback
```

| Platform | Bot scopes |
|----------|-----------|
| Twitch | `chat:read`, `chat:edit`, `user:write:chat`, `user:bot`, `user:read:chat` |
| YouTube | `youtube.force-ssl` |
| Kick | `chat:write` |
| Discord server invite | `bot`, `applications.commands`, `identify` |

If a Twitch or Kick dedicated bot pair is unset but its channel pair exists, the bot flow uses the channel keys and logs a warning. For those OAuth bots, missing global keys can fall back to `account`, which is the normal local development path. Discord has no per-account bot app: an unset `discord_bot_client_*` pair makes server invites fail closed.

Kick production verification now applies to both production Kick apps. The Bot app is the one whose `chat.message.sent` subscription cap matters for chat sending: unverified apps are capped at 1,000 subscriptions for that event type, verified apps at 10,000.

See [Bot Connections](/features/bot-connections) for the full flow.

## See Also

- [OAuth Credentials Architecture](/developer-guide/oauth-credentials-architecture) - Dual-credential design, encryption, token refresh
- [Channel Connections & Scopes](/developer-guide/channel-connections-oauth-scopes) - Scope details, connection flow, storage
- [Token Refresh](/features/token-refresh) - Automatic token refresh worker

---

## Getting Started / Create Your First Overlay

Source: https://docs.lumio.vision/getting-started/first-overlay

# Create Your First Overlay

Build an overlay in Lumio and add it to OBS as a browser source.

## Create the Overlay

1. Go to **Dashboard → Overlays** (`/dashboard/overlays`).
2. Click **New Overlay**.
3. Give it a name, pick a resolution preset - `1920×1080 (Landscape)`, `1080×1920 (Portrait / TikTok)`, `1280×720 (720p)`, `2560×1440 (1440p)`, or a custom size - and choose a background. Leave the background **Transparent** unless you specifically want an opaque one; OBS composites the overlay over your scene.
4. Click **Create**. The dialog immediately shows the overlay's URL with a **Copy** button.

## Add Layers

Open the overlay's **Editor** (`/dashboard/overlays/{id}/editor`) and add layers - alerts, chat, music, widgets, custom HTML/CSS/JS, or installed extension widgets. Save with `Ctrl/Cmd + S`.

While the editor is open, `/overlay/{key}/preview` mirrors the canvas live, so you can keep a preview window next to the editor and watch changes land as you make them.

## The Overlay URL

An overlay URL has three parts:

```
https://overlay.lumio.vision/<key>?token=lm_overlay_xxxxxxxx
```

- The **host** is the overlay host - `overlay.lumio.vision` in production, `http://localhost:4000/overlay` in local development. It is configured per deployment (`NEXT_PUBLIC_OVERLAY_URL` on the webapp, `LUMIO__OVERLAY__PUBLIC_URL` on the API).
- The **key** is the overlay's own non-enumerable identifier. It never expires.
- The **token** authenticates the request. Loading `/overlay/{key}` **without** `?token=` renders `403 - Access token required`.

> **Copy URL rotates the token:**
> **Copy URL** on an overlay card mints a **fresh** overlay token (`lm_overlay_*`) and immediately invalidates the previous one. Any browser source still holding the old URL stops working. Copy the URL once, paste it into OBS, and only copy again when you intend to revoke the old link.

Three token types authenticate an overlay URL:

| Token | Prefix | Use |
|-------|--------|-----|
| Overlay token | `lm_overlay_` | The overlay's own token, handed out by **Copy URL**. One live token per overlay |
| Shared overlay link | `lm_share_` | A time-limited link for someone else. Choose 1 h, 3 h, 6 h, 12 h or 24 h; up to 20 active links per overlay; revocable at any time. Requires the overlay-sharing feature on your plan |
| Popout token | `lm_pop_` | A permission-scoped token you generate in **Dashboard → Tokens**. Works on overlay pages as well as the popout views |

## Add It to OBS

1. In OBS, add a **Browser Source**.
2. Paste the overlay URL.
3. Set **Width** and **Height** to the overlay's canvas resolution (e.g. `1920` × `1080`) - browser sources do not resample cleanly, so match the numbers exactly.
4. Click **OK**. The overlay renders over your scene and updates in real time over the WebSocket connection - no refresh needed.

If the source is blank, open the same URL in a normal browser tab. A `403 - Access token required` there means the `?token=` part is missing or was rotated away by a later **Copy URL**.

## Permissions

| Action | Permission |
|--------|-----------|
| View the overlay list and open the editor | `overlays:read` |
| Create an overlay | `overlays:create` |
| Edit layers, save, copy the URL, create a shared link | `overlays:edit` |
| Delete an overlay | `overlays:delete` |

Overlays additionally have per-overlay access levels, so a team member can be granted Editor rights on one overlay without holding them account-wide.

## Next Steps

- [Overlays (user guide)](/user-guide/overlays) - the editor, layers, presets and troubleshooting in depth
- [Tokens](/user-guide/tokens) - popout tokens for the overlay and popout pages
- [Connecting Platforms](/getting-started/connecting-platforms) - so your alerts have events to fire on

---

## Getting Started / Connecting Platforms

Source: https://docs.lumio.vision/getting-started/connecting-platforms

# Connecting Platforms

Connect your streaming platforms and services to Lumio from **Settings → Connections** in the dashboard (`/dashboard/settings/channel/connections`).

## What Can Be Connected

Different platforms plug into Lumio in different ways. Only the first group uses a **channel connection** - the OAuth link that lets Lumio read chat and events for your channel.

| Platform | Channel connection | Bot | Login | Other |
|----------|--------------------|-----|-------|-------|
| **Twitch** | Yes - chat, events, moderation, rewards | Yes | Yes | - |
| **YouTube** | Yes - chat, super chats, memberships | Yes | Yes | - |
| **Kick** | Yes - chat, events, moderation | Yes | Yes | - |
| **Spotify** | Yes - playback, playlists | - | - | - |
| **Discord** | - | Global bot invited to servers | Yes, sign-in only | Server integration |
| **Shopify** | - | - | - | Integration |

The **Services** area holds **OBS** (WebSocket), **StreamElements** tokens for tip ingestion, and **Shopify**. Shopify connects through its embedded app in the Shopify admin, then asks you to confirm the link in Lumio; it is not a channel OAuth connection. Streamer.bot is listed as a later service. See [Shopify setup](/user-guide/connections#shopify).

## Before You Connect

YouTube and Spotify channel connections use your account's **own OAuth application**. Twitch and Kick normally use Lumio's app; if its system credentials are unavailable, they can use an account-owned app:

1. Create the OAuth app on the platform's developer console and register Lumio's callback URL - see [OAuth Provider Setup](/getting-started/oauth-setup).
2. In Lumio, open that platform's area and choose **Set up app** in its **App** section. The guide saves the **Client ID** and **Client Secret** encrypted. Spotify's guide has five steps; YouTube's has six.

Until an account-owned app is configured, its platform area asks you to set it up before connecting the channel.

## How to Connect

For Twitch, YouTube, Kick or Spotify channel connections:

1. Open **Settings → Connections** in the dashboard and choose the platform.
2. Click **Connect** in its Channel section.
3. Authorize the requested scopes on the platform's consent screen.
4. You return to the same platform area, which shows the result.

You only enter an own app's credentials once per platform. **Reconnect** re-runs OAuth for the same platform account when a required scope is missing or a grant cannot be refreshed. Spotify also needs reconnecting after its 180-day authorization period; the hub warns you during the last 14 days.

## One Connection Per Platform

Each account holds **at most one channel connection per platform** - the `channel_connections` table is unique on `(account, platform)`. Connecting a second Twitch channel to the same account replaces the first. Use separate Lumio accounts for separate channels.

Your **login** connections are tracked separately, so signing in with Twitch and also connecting a Twitch channel are two independent records.

Discord sign-in cannot be assigned to a channel. Manage its login connection under **Security → Sign-in**. To invite the Lumio bot to a Discord server, open the **Discord** area; this is separate from the personal login connection.

## Permissions

| Action | Permission |
|--------|-----------|
| See a channel connection and its status | `connections:read` |
| Save an own app, start channel OAuth | `connections:create` |
| Disconnect a platform | `connections:delete` |

The hub shows only tabs whose providers, features and read permissions are available to you. OBS and StreamElements each have their own read permission.

## Next Steps

- [Connections (user guide)](/user-guide/connections) - every panel on the page, in detail
- [Bot Connections](/features/bot-connections) - run chat under your own bot identity
- [Create Your First Overlay](/getting-started/first-overlay)

---

## User Guide / Dashboard

Source: https://docs.lumio.vision/user-guide/dashboard

# Dashboard

The dashboard home brings your connected channels, stream metrics, calendar and activity into one view. It adapts when a channel goes live. The sidebar takes you to Chat, Events, History and the other account features.

## Where to find it

- URL: `/dashboard`
- Shown automatically right after you sign in - every sign-in lands here, including your first one.
- The sidebar on the left is always available while you are inside the app.

## First sign-in

The very first time you sign in you do not have an account yet, so the dashboard shows a short **account setup** step instead of the channel cards:

- **Create a Free account** - start on the Free plan right away (paid plans show an "upgrade later" hint; you upgrade from **Settings → Channel → Subscription** once the account exists).
- **Join with an invite code** - if a team owner invited you, paste their code here to join their account as a member instead of creating your own.

Once an account exists, `/dashboard` shows the normal home page described below. You are never sent to the Subscription page before you have an account.

## Quick start

1. Sign in via the **Login** button - pick Twitch, YouTube, Kick, or Discord.
2. If you do not have a streaming platform linked yet, the connection notices at the top show **Connect a streaming platform** - click the platform you want to add.
3. Open **Connections** in the sidebar and connect at least one channel so Lumio can read your chat and events.
4. Back on the dashboard, check the status strip for your channel. While you stream, it becomes a live strip with a link to the broadcast.
5. Use the sidebar to create your first overlay, automation, or command.

## Header controls

The top-right corner of the dashboard header contains two icon buttons:

- **Shield** - Toggles [Streamer Mode](/user-guide/streamer-mode) on/off. Highlighted when active. Masks sensitive data (IDs, tokens, credentials) across the entire dashboard, replacing it with dots - ideal when your dashboard is visible on stream.
- **Bell** - Opens the notification dropdown.

## Layout at a glance

The home page groups its content into a header, status strip, metrics and timeline, a 12-month calendar, and activity. When the body content area is at least about 72 rem wide, activity sits beside the metrics, timeline and calendar. With less room, the page stacks metrics, activity, timeline and calendar in that order. This follows the space available beside the sidebar, so collapsing it can change the arrangement without changing the window size. The status strip above the body follows the window width. Each group needs its own feature and permission. If your role lacks one, that group is omitted and the remaining layout closes the gap. A failed data request stays in its group with a retry action.

### Upgrade banner

If you are the account **owner** on the free plan, a slim upgrade card appears above the status strip. You can dismiss it; that choice is saved.

### Connection notices

Above the page content (on the dashboard and every other non-fullscreen page) a single card collects every connection notice: an expired login, channel or bot connection (red), a login that is not assigned to this channel, missing permissions and the streaming-platform onboarding (amber). It shows one notice at a time - use **‹ ›** (or **←/→**) to page through them, and **✕** to hide one until you reload the page. Your own (user) problems come first, then the channel's. Each notice carries its repair button; channel and bot reconnect buttons appear only if you may reconnect channels (`connections:create`). See [Connections → Connection notices](../features/connections.md#connection-notices).

### Streaming-platform onboarding

If the only login you have is Discord (no streaming platform linked), the connection notices include **Connect a streaming platform** - on every page with notices, the Chat and Events pages and the popouts included. It offers a button each for **Twitch**, **YouTube** and **Kick** (none is preferred). Click one to start the OAuth link flow. After authorizing, you are redirected back and the notice disappears.

### Header and popouts

The page header greets you and shows the date, or how long the channel has been live (“You have been live since 18:00” for the owner, “EL_CAPiTANO1988 has been live since 18:00” for everyone else). **Open chat** opens Chat. **Popouts ▾** offers Chat, Events, Music and Test-Events when their features and permissions allow them. Music also needs a Spotify connection. Each entry can open a window or copy a token-free page URL; the menu never displays a token URL. To use a popout in OBS, create a [popout token](./tokens.md) with the needed permissions.

### Weekly review

Sentences about streaming, going live and gaining followers belong to the channel account. The account's owner reads them addressed to themselves (“Quiet week. Your last stream was 21 days ago.”). Everyone else — for example a moderator, who does not stream on that channel — reads the name of the active account as shown in the account switcher (“Quiet week. EL_CAPiTANO1988’s last stream was 21 days ago.”); if the account has no name, the sentence says “the channel”. The same applies to the live line in the header, the live switch announced to screen readers and the Music entry in **Popouts ▾**. The greeting and your role always address you.

While the channel is offline, with `feature:stream_history` and `history:read`, the header becomes a weekly review card. The greeting and date appear at its top, beside the header buttons when the card is at least about 42 rem wide; in a narrower card, the buttons sit below them. Below is a verdict, one sentence and a bar chart of hours streamed per day: this week next to the same weekday of the week before. The bars sit beside **History** and **Watch last stream** when the card has that width, and above those links when it does not. The links sit beside each other when the card is at least about 24 rem wide; in a narrower card, they stack. **History** opens the stream history and **Watch last stream** opens the report of the channel’s most recent finished stream.

The review always covers the last 7 days on every platform. The range and platform filter of the metrics strip do not change it. The verdict follows these rules, comparing this week with the 7 days before:

| Verdict | When |
| --- | --- |
| **Quiet week.** | No stream this week. The sentence says how many days ago the account’s last stream was. |
| **Good week.** | The account streamed this week but not the week before. The sentence shows days and hours, without a comparison. |
| **Strong week.** | Stream time **or** new followers rose by at least 10 %, and neither fell by 10 % or more. |
| **Calmer week.** | Stream time **and** new followers both fell by at least 10 %. |
| **Solid week.** | Every other case. |

A number the week before was zero for (for example no new followers) gives no percentage, so it counts as neither up nor down. An account that has never streamed sees only the greeting. While the channel is live, the review and the **Up next** card disappear and the header shows how long the channel has been live. When the stream ends, both reload once. Without `history:read` the header stays a plain greeting.

### Up next

With `feature:connections` and `connections:read`, **Up next** shows the channel’s next planned stream within the next 7 days, from any platform's stream plan (YouTube scheduled broadcasts, the Twitch schedule and the Kick schedule): platform, title, day and time, a **Scheduled** badge and a link to the livestream page. The card sits beside the weekly review when the header content area is at least about 72 rem wide; with less space, it spans the full width below the review. In that full-width card, the stream title stays on the left and the countdown or start time sits on the right when the card is at least about 36 rem wide. In a narrower card, they stack. The livestream link stays below. Under 24 hours it counts down to the start; further ahead it shows the date and time. Screen readers hear one announcement when the start is less than an hour away, not every minute. Without a planned stream in the next 7 days there is no card and the weekly review takes the full width. The planned streams for the next 30 days also appear in the timeline (see [Planned streams in the timeline](#planned-streams-in-the-timeline)), and the status strip keeps its link to the scheduled broadcast. These layouts follow the space beside the sidebar, so collapsing it can change the arrangement without changing the window size.

### Status and readiness

With `feature:connections` and `connections:read`, the offline strip shows each connected channel, its last live time, follower count (approximately rounded subscribers on YouTube), and a link to the channel. With `history:read` as well, a second line under the followers shows the channel's current paid subs ("412 subs") on Twitch and Kick; Twitch counts gifted subs too and needs the channel permission to read subscriptions, so an older connection may need a reconnect before the line appears. YouTube shows no such line, because channel memberships cannot be read. When a count is not available the line is left out rather than shown as a dash. The strip shows this line only while you are offline. A scheduled YouTube broadcast links directly to its watch page. Without a connected channel, the page points you to **Connections**.

While live, the strip shows each live platform's title, category, viewers and direct broadcast link; YouTube also shows likes and views when available. Platforms sharing a title are grouped into small platform cards. With only one live platform, its viewer count sits next to the platform and the other channels keep their scheduled or offline status beside it. When several platforms are live, wide screens show the total viewers with platform shares on the right side; on narrower screens the total sits below the stream list. The strip updates without reloading.

The **Readiness** ring gives a text count such as “4 of 5 ready”. It has one segment per check, ready ones first clockwise from the top, with an even gap between segments; a single check is a closed ring. Its segments appear only when you have the feature and read permission: connections (`connections:read`), bots (`bot-connections:read`), OBS (`obs:read`), overlays (`overlays:read`) and Music (`spotify:read`, with Spotify connected). **Open notice** selects the matching connection notice in the AlertDeck above the page, even if you dismissed that notice during this visit. Other segments link to their feature pages.

### Metrics and timeline

With `feature:stream_history` and `history:read`, the offline metrics strip shows average viewers, stream time, new followers, chat messages, and Subs & Members. Choose **Today**, **7 days** (default) or **30 days** to compare each metric with the preceding period and see a small trend. Each trend line covers the whole selected range, the same window as the number above it. Only days with a stream are points: a day without a stream is skipped (the line bridges it), not drawn as zero, so all five lines share the same days. With fewer than two stream days in the range, for example **Today**, no line is shown. An account without streams shows an empty state rather than an infinite percentage.

The five metric tiles share one card: they sit in one row when the main column is at least about 42 rem wide, or in rows of three and two when it is narrower. On a phone, the tiles scroll sideways. Inside a stream card, the viewer curve sits beside the figures when the card is at least about 42 rem wide and above them otherwise. Live figures use four cells across when their row is at least about 36 rem wide, or two rows of two below that width. Compact stream rows show record badges from about 36 rem of row width and the viewer trend from about 48 rem; narrower rows keep the stream details without those extras.

The selected range applies to the metrics **and** the timeline's past: both always show the same window. The timeline shows your planned streams at the top (below), then **Today** with today's planned streams from every platform, then the finished streams that started in the range, grouped day by day in your time zone (a stream that runs past midnight belongs to the day it started). The newest stream gets the large card with its viewer curve and figures; the others are compact rows. The curve shows each platform as its own line at its real viewer count — lines are never stacked on top of each other. With two or more platforms, a filled **Total** curve sits behind them: the combined viewers of the selected platforms, counted minute by minute, so it can be lower than the platforms' peaks added up. Hover or tap the curve for the time, **Total** first and then each shown platform. The timeline shows at most 12 streams; if the range holds more, **{n} more streams in this range** below the last day opens [Stream History](./stream-history.md) filtered to that range, and so does **View full history**. A range without streams says so (“No stream today yet”, “No streams in the last 7 days” or “… 30 days”). While you are live the metrics strip is hidden; the timeline then shows **Now** and, below it, the streams of the range you last selected. While a new range loads, the current streams stay in place, dimmed. Milestones include viewer and Sub/Member records, the biggest raid, and follower marks. A first stream or first raid does not yet beat a previous record; equal values are not records. Records cover your whole stream history, including streams from before milestones were introduced. Follower marks start with your second stream after the update, because older streams have no saved follower count.

While live, the metrics strip gives way to the **Now** card: a viewer line per platform with the **Total** curve behind them (as in the stream card), Community totals (new followers, paid Subs & Members with the gifted Subs as a "+ N gifted" line below, chat messages per minute, and peak viewers; the paid figure is the one the stream's history row and report show), and separate Support figures for Twitch Bits, Kick KICKs, YouTube Super Chats and Stickers, and StreamElements tips. Figures and their sublines update on the history sampler's roughly 60-second rhythm without reloading the page. The follower rate appears after 15 minutes; the platform subline labels Kick and Twitch counts, while YouTube subscribers say **after the stream**. The gifted Subs line, message total, Super Chat and Sticker counts, tip count and sample time update with their headline figures. Chat messages can trail the newest chat by up to another 30 seconds. The card shows only applicable platforms and figures; it does not infer an active-chatter count from chat messages.

During a Twitch Shared Chat, the **This stream** card has a **My channel** /
**Whole session** switch. My channel is the default and keeps your own viewer
curve, messages and Chat/min. Whole session shows a **Sum of all channels**
area and one line per channel in host → own → partner order, with a legend.
A partner who leaves keeps the earlier part of their line; an unknown count
is a gap, not zero. The chat cell leads with session messages and shows your
own count beneath. Its Chat/min headline uses the whole session's rate and
shows **—** until two samples exist; My channel uses your own rate. Support
and revenue always come only from your channel. A Shared Chat start, join,
leave or end refreshes the card without reloading the page.

#### Planned streams in the timeline

With `connections:read` as well, the timeline starts with your stream plan for the next 30 days, so it reads top to bottom as one time line: the latest planned stream at the top, the next one directly above **Today**, then the past days with the newest first. The plan comes from each platform:

- **YouTube**: scheduled broadcasts and premieres of your channel.
- **Twitch**: your channel's stream schedule (cancelled slots and vacations are left out).
- **Kick**: the **Schedule** tab of your Kick channel. Kick has no official API for it, so Lumio reads the same data the kick.com page shows; if Kick changes it, the Kick plan stays empty until Lumio is updated.

Planned streams are grouped by day in your time zone (**Tomorrow**, **Sat, Oct 11**, …). Each entry shows the platform logo, the title (or “Untitled stream”), **Scheduled on Twitch · 20:30** — or **20:30–23:00** when the platform has an end time — and the category. A recurring slot carries a small repeat icon; hover or focus it for **Recurring slot**. On the same day, a badge counts down to the start (“in 15 min”). **Livestream page ↗** (YouTube) or **Channel ↗** (Twitch, Kick) opens the stream on the platform. A simulcast on two platforms at the same time shows as two entries, one below the other.

When a planned-stream card is narrower than about 32 rem, the countdown and livestream link wrap below the title; both remain available.

The timeline shows at most 5 planned streams, the nearest ones. If the next 30 days hold more, **+ {n} more scheduled** above them opens the plan on the platform of the next hidden entry: the Twitch schedule, the Kick channel page, or YouTube Studio. Today's planned streams sit under **Today** instead and do not count towards the 5. A planned stream stays listed until its end time passes, or, without an end time, for 30 minutes after its start.

The platform filter applies to the plan as well. The range (**Today / 7 days / 30 days**) does not: the plan always looks 30 days ahead. While you are live, **Now** replaces **Today**, the slot you are streaming in disappears, and only planned streams that start after now stay above **Now**. The plan reloads when you open the page and whenever a channel goes online or offline — never on a timer. Without planned streams there is no plan section. If the plan cannot be loaded, the timeline shows a notice with a retry action instead of an empty plan.

#### Platform filter

When your account has two or more streaming platforms (connected, or with streams in your history), platform chips with logo and name sit next to **Today / 7 days / 30 days**. On a phone they sit below the range and show only the logo. All platforms are on by default. Select a chip to switch that platform off or back on. At least one platform always stays on: the last active chip cannot be switched off, and its tooltip says so. Your choice lasts until you reload the page, like the range.

The filter applies to the whole page below it:

- **Metrics and trend lines** count only the selected platforms' share of each stream. For a simulcast with only YouTube selected, for example, stream time is YouTube's live time, and followers, chat messages and Subs & Members are YouTube's. Average and peak viewers use YouTube's audience only.
- **Timeline** lists only streams that ran on a selected platform, and only planned streams of a selected platform. In each stream card, the viewer curve, the figures and the compact row's peak show only the selected platforms. A platform you switched off stays in the card's legend, greyed out.
- **Stream calendar** days and their tooltip values count the same share. Follower marks show only for selected platforms; viewer, Sub/Member and raid records always show.
- **View full history** and **{n} more streams in this range** open [Stream History](./stream-history.md) filtered to that platform when exactly one is selected. With two or more selected, they open the unfiltered list, because the history list filters by one platform at a time.

The legend chips in the stream cards switch the same filter: switching off Twitch in a card switches it off in the header and everywhere else. A change loads the metrics, timeline and calendar together in one update; until it arrives, the current values stay in place, dimmed.

While you are live, the metrics strip and with it the platform filter are hidden, and the page shows all platforms. The legend in the **Now** card then switches only that card's platform lines; the **Total** curve keeps counting every live platform. Your filter choice applies again when the stream ends.

### Calendar and activity

The calendar fills the main content column and spans 12 months in your timezone. Hover, focus or tap a day to see its stream count and duration, each stream's platforms, title, time, peak and new followers, plus milestones. **Open day in History** filters the history list to that day. Keyboard users can move through days with arrow keys and open one with Enter. A day without a stream says so in the tooltip.

With `feature:events` and `events:read`, the activity column mixes follows, subscriptions, resubs and memberships, sub upgrades (Prime and gifted to paid), gifts and paid-forward gifts, Bits, KICKs, Super Chats and Stickers, tips, and raids across platforms. Twitch reports a resub only when the viewer shares the resub message in chat; a resub that is not shared never reaches Lumio. New entries arrive at the top; **All** opens the [Events page](./events.md). The emotes in an event's message, such as the sub emotes in a resub message or the cheermotes in a cheer, render as images, as on the Events page. With `events:userinfo`, a click on a name opens the same user info card as on the Events page; without it, names are plain text. A thin line separates every two rows. Highlighted events such as Super Stickers or Bits keep their tinted background, and every row's background (highlight, hover, test border) keeps a little space to the lines. A name you can click turns to the accent colour on hover. A test event has a **TEST** badge and dashed border here, but disappears after a reload. Its name does not open a user info card. The Events page and Events popout do not show tests.

At about 72 rem of body width or more, activity sits beside the main content and shows up to 14 of the newest rows. Below that width it sits under the metrics and above the timeline, showing the five newest rows. **All** opens the full feed in either layout.

### Test events

With `feature:events` and `events:create`, **Test event** in the header opens a side sheet (full screen on a phone). Search the catalog, switch between platform tabs and **More**, send a row with default values, or expand it to edit values and choose random values. The sheet opens on the tab you used last in this session while that platform is still offered, otherwise on the first offered platform; until your connections have loaded, the tab row and the rows show placeholders.

The catalog offers only events you could actually receive. An event source appears in the tabs, **More**, the search and **Just sent** only when all of these hold:

| Source | Connection | Features | Permission |
|--------|------------|----------|------------|
| Twitch, YouTube, Kick | A channel connection for the platform (also one that needs a reconnect) | `platform:twitch` / `platform:youtube` / `platform:kick` | — |
| Spotify | A Spotify connection | `platform:spotify` and `feature:music` | — |
| StreamElements | A stored StreamElements token | `feature:streamelements` | — |
| Discord | — | `platform:discord` | — |
| Shopify | — | `integration:shopify` | — |
| Copyright | — | `feature:copyright_detection` | `copyright:read` |
| 7TV | At least one Twitch, YouTube or Kick channel connection | `feature:events` | — |

Your connected stream platforms get their own tabs and every other offered source sits under **More**; with no stream platform offered, the first other sources take the tab slots. If the connections or the StreamElements token cannot be read (for example without `connections:read` or `se-tokens:read`), those sources stay listed rather than hidden. If nothing is offered, the sheet says so and links to **Connect a channel**. Entries in **Just sent** for a source that is no longer offered are hidden, not deleted. The sheet stays open after sending; **Just sent** keeps this session's tests with **Again** actions. The confirmation also offers **Again**.

Tests broadcast to the account's overlays and dashboard activity. They are not stored, so they do not enter history, metrics, milestones, the Events page or the Events popout. The separate [Test-Events popout](./tokens.md#where-popout-tokens-work) uses the same catalog and can run as a narrow OBS dock. Its popout token must explicitly include `events:create`; without that right it shows a missing-permission notice instead of the catalog. The popout applies the same filter with the token's own rights, so Copyright appears there only when the token also includes `copyright:read`. In the popout, **Connect a channel** opens a new window; inside OBS it also offers **Copy link**, because a browser source blocks new windows. While it loads, the window shows placeholder rows in the catalog's layout.

### Streamer Mode and loading

Streamer Mode masks money, Bits and KICKs in activity and the **Now** card, including test rows, as well as the current paid subs in the status strip; use the eye control to reveal a value. The same masking applies in the Events feed and Events popout, and to the money amounts on event lines in the chat (Super Chats, tips, Shopify order totals and item prices). Each home group loads in a matching skeleton, including on mobile; with Twitch or YouTube connected, the timeline skeleton includes a planned-stream row. Live state changes are announced once to assistive technology; rapidly changing count ticks are not.

## Sidebar sections

Below the account switcher, the sidebar groups features into collapsible sections. Entries are filtered automatically based on your role permissions and the features enabled for your plan - you may not see every item listed below, and a section disappears entirely when none of its entries are visible to you. Clicking a section header collapses or expands it, and your choice is remembered in that browser.

The **Dashboard** entry sits on its own above the first section. You can collapse the whole sidebar down to icons with the round arrow handle on the sidebar's right edge, level with the account switcher. The same handle expands it again, and the choice is remembered in that browser.

### Stream

- **Overlays** - Browse, create, rename, organise into folders, and delete overlay configurations. Each overlay has its own URL for browser sources. See the [Overlays guide](./overlays.md).
- **Chat** - Full-page multichat across every connected platform. See the [Chat guide](./chat.md).
- **Events** - Full-page live event feed. See the [Events guide](./events.md).
- **Music** - Spotify now-playing state and playback controls. See the [Music guide](./music.md).
- **Rewards** - Twitch channel-point redemption configuration. See [Rewards](../features/rewards.md).
- **OBS** - OBS WebSocket remote control. See [OBS](../features/obs.md).
- **History** - Past stream sessions with metrics, charts, and reports. See [Stream History](./stream-history.md).

### Widgets

- **Widgets** - Widget instances you place into overlays, each with its own designer. Extension widgets belong to an extension installed on the active account. Widget access settings also control the list: a widget assigned `none` is hidden, while widgets with no access entry or with `viewer` or `editor` access are visible. Copying a widget requires Editor access to the original and permission to create widgets. Members allowed to view all widget access entries can see every widget; the ability to grant widget access also bypasses the Editor check when copying.

### Hub

- **Ideas** - The cross-account [Ideas Hub](./ideas-hub.md) for feature requests and voting.

### Store

- **Browse Store** - The [extension store](../features/extensions.md).
- **Installed** - Extensions installed on this account.

### Tools

- **Automations** - Visual flow builder that reacts to events (follow, raid, superchat) and triggers actions (play sound, change scene, send chat, fire webhook). See [Automation Templates](./automation-templates.md).
- **Bot Modules** - Link protection, spam protection, word filter, and timed messages. See the [Bot Modules guide](./bot-modules.md).
- **Bot Control** - Pause, resume, or reconnect your chat bots per platform. See [Bot Control](../features/bot-control.md).
- **Commands** - Chat commands with templates, platform overrides, and Discord slash-command registration. See [Bot Commands](../features/bot-commands.md).
- **Copyright** - Copyright-strike detection on your VODs. See [Copyright](../features/copyright.md).

### Manage

- **Connections** - Platform OAuth connections, integrations, StreamElements tokens, and bot connections. See the [Connections guide](./connections.md).
- **Channel settings** - Settings for the whole channel: revenue assumptions and the danger zone. Shown as soon as you may open one of its tabs. See [Channel settings](./channel-settings.md).
- **Members** - Team members and invitations. See the [Members guide](./members.md).
- **Roles** - Define roles with granular permissions. See [Roles and permissions](./roles-and-permissions.md).
- **Audit Log** - Account-wide role, member, connection, API-key, and erasure audit rows. Requires `audit-log:read`; see [Audit Log](./audit-log.md).
- **Uploads** - Sound and image assets used by overlays and automations. See [Uploads](../features/uploads.md).
- **Tokens** - Popout tokens for OBS browser-source docks. See the [Tokens guide](./tokens.md).

### Extensions

Only shown to approved extension developers, and only while no account is selected in the account switcher: **My Extensions**, **New Extension**, **Team**, **Team Members**, **Verification**, and **Payouts**.

Opening an extension from **My Extensions** (or from a developer e-mail or notification) leads to its overview page at `/dashboard/extensions/<slug>`. The top card shows the icon, name, review status, slug, description, latest version, category, rating, installs and whether it is a personal or a team extension. Below it, one entry per tool, grouped as:

| Group | Entries | Shown with |
|-------|---------|------------|
| **Build** | Editor · Testing Phase · Secrets | Editor: `extension-dev:edit`; the rest: `extension-dev:read` |
| **Publish** | Submit for review · Submission history · Access Management | Submit for review: `extension-dev:publish`; the rest: `extension-dev:read` |
| **Monitor** | Analytics · Metrics · Errors · Logs | Analytics: `extension-dev:analytics`; the rest: `extension-dev:read` |

An entry you lack the permission for is hidden, and a group without entries is left out. Secrets of a team extension additionally need the team permission `team-secrets:read`; without it the Secrets page itself reports the missing access. Every tool page except the editor has a back link to the overview. An unknown slug shows the not-found page.

### Account

- **Settings** - Your profile, appearance ([Region & Language](./preferences.md), [seasonal look](./preferences.md#seasonal-look), Streamer Mode), notifications, data & privacy, and your channel memberships. See [Settings](./settings.md).
- **Security** - Sign-in methods, authenticator apps and passkeys for 2FA, sessions and your activity. See [Account security](./account-security.md).
- **Developer** - The developer application and developer profile. Only shown while no account is selected in the account switcher.
- **Subscription** (owner only) - Plan, renewal, payment method and invoices, as the two tabs **Subscription** and **Invoices**. The entry stays highlighted on both tabs.

## Common scenarios

### First-time setup

1. Sign in with your main streaming identity.
2. Go to **Connections** and connect every platform you stream on.
3. Go to **Roles** and review the three defaults (Owner, Administrator, Moderator).
4. Go to **Members** and invite your moderators with the **Moderator** role.
5. Go to **Overlays** and create your first overlay.
6. Open the overlay URL as a browser source in OBS.
7. Open **Test event** in the dashboard header and send a sample event to confirm your overlays receive it.

### Adding a moderator quickly

1. From the sidebar, open **Members**.
2. Click **Invite**, choose **Invite Link**, select the **Moderator** role, pick a validity, and click **Create Invite**.
3. Copy the link and send it to your moderator.

### Account switching

The account picker at the top of the sidebar lets you switch between your **personal profile** and any channel account you own or belong to. It appears as soon as you have at least one channel account - including on the free plan, where you own a single channel - so you can always move back and forth between that channel and your personal profile. Switching to a channel reloads all data for the new account, including events, overlays, and permissions.

What happens to the page you are on:

- **Most pages reload** with the new account's data.
- **A page that shows one item of the old account** - a history report, an overlay or automation editor, a widget designer, a bot module's details, logs or errors - cannot show that item for the new account. Lumio opens the matching list instead: a history report goes to **History**, an overlay editor to **Overlays**, and so on.
- **Switching to your personal profile** always opens the dashboard home.
- **Other open dashboard tabs follow.** The active account applies to your whole sign-in session, so every other dashboard tab in the same browser moves to the new account the same way.

While your **personal profile** is selected there is no channel to manage, so the dashboard home shows the getting-started view instead: the plan cards for creating a new channel account and a **Join with an invite code** field for joining a team you were invited to.

## Permissions

Most sidebar entries are gated by a `resource:action` permission **and** by a feature being enabled for your plan - both must be satisfied for the entry to appear. The account **Owner** role holds every permission.

| Sidebar entry              | Required permission       |
| -------------------------- | ------------------------- |
| Dashboard                  | (implicit - any member)   |
| Overlays                   | `overlays:read`           |
| Chat                       | `chat:read`               |
| Events                     | `events:read`             |
| Music                      | `spotify:read`            |
| Rewards                    | `rewards:read`            |
| OBS                        | `obs:read`                |
| History                    | `history:read`            |
| Widgets                    | `widgets:read`            |
| Ideas                      | (no permission - feature only) |
| Browse Store / Installed   | `extension-store:read`    |
| Automations                | `automations:read`        |
| Bot Modules                | `bot-modules:read`        |
| Bot Control                | `bot-connections:read`    |
| Commands                   | `bot-commands:read`       |
| Copyright                  | `copyright:read`          |
| Connections                | `connections:read`        |
| Members                    | `members:read`            |
| Roles                      | `roles:read`              |
| Audit Log                  | `audit-log:read`          |
| Uploads                    | `uploads:read`            |
| Tokens                     | `tokens:read`             |
| API Keys                   | `apikeys:read` + `feature:apikeys` |
| Subscription               | Owner only                |

If an entry is missing from your sidebar, either your role does not grant the corresponding `:read` permission or the feature is not part of your plan. Ask your account owner to adjust your role, or open **Roles** yourself if you have `roles:edit`.

## Tips and best practices

- **Pin the Chat and Events pages** as browser tabs while you stream - they are the fastest way to react to your audience.
- **Send a test event** before every stream to confirm your overlays respond after a config change.
- Dashboard data is loaded server-side on first render (SSR) and then kept live via WebSocket. If you suddenly see a static view, it usually means the WebSocket dropped - refresh the page.
- Dismissing the upgrade card is saved for your account.
- If you manage multiple brands, create a separate Lumio account per brand and use account switching - do **not** try to multiplex channels into one account.

## Troubleshooting

**The dashboard is stuck on "Connect a streaming platform" even though I added Twitch.**
The onboarding notice only disappears once you finish the OAuth linking flow. If you closed the tab mid-flow, click a platform button again - it will not create a duplicate.

**I see "No events yet" on the Events page but I know events are coming in.**
Three things to check: (1) your plan actually includes the Events feature, (2) the active account is the correct one (account picker in the sidebar), and (3) the channel connection is healthy - open **Connections** and look for an expired-token warning.

**My status strip does not show LIVE but my stream is live.**
Live status polling depends on the platform's own API. Twitch usually refreshes within 1 minute, YouTube within 2 minutes. If it stays offline, reconnect the channel in **Connections**.

**Sidebar entries are missing.**
Your role does not include the `:read` permission for that section. Go to **Roles** (if you can see it) or ask your account owner.

**Real-time updates stop after my laptop wakes from sleep.**
Lumio reconnects automatically with exponential backoff, up to a 30 s ceiling. If updates do not resume within 30–60 s, refresh the page.

## Related

- [Connections](./connections.md) - link streaming platforms and integrations.
- [Members](./members.md) - invite team members and manage invitations.
- [Audit Log](./audit-log.md) - review personal and account audit events.
- [Roles and permissions](../features/roles.md) - fine-tune what each role can see and do.
- [Overlays](../features/overlays.md) - design and publish overlays.

---

## User Guide / Settings

Source: https://docs.lumio.vision/user-guide/settings

# Settings

Open **Settings** at the bottom of the dashboard sidebar, or press **Ctrl + ,** (**⌘ + ,** on a Mac). The settings window opens over your current page. Use the selector at its top left to choose **You** or one of your channels; the list below it shows the areas for that choice. Your personal settings apply across all your channels. Channel settings apply to the selected channel and its members.

Choose an area from the list or search for a setting with **/** while the window is open. Use ↑ and ↓ to select a result and Enter to open it. A result in the other side of the selector switches sides for you. The window highlights the matching control. Close the window with ×, Escape, or a click outside it. On a phone or narrow window, the area list fills the screen; tap an area to open it and use the back arrow beside **Settings** to return to the list.

Each area has a shareable address on the page you were using, such as `/dashboard#settings/appearance`. The short links in the table open the same area over the dashboard home and survive a sign-in round trip. **Settings** without an area opens the personal overview; **Channel** in the selector opens the channel overview.

| Area | Short link | What you can do |
|---|---|---|
| **Profile** | `/dashboard/settings/profile` | Choose your displayed name and image source, inspect your profile email and channels, and copy your Lumio ID. |
| **Appearance** | `/dashboard/settings/appearance` | Choose the color scheme, Streamer Mode, language and region, [motion](/user-guide/preferences#animations-in-lumio), and [seasonal look](/user-guide/preferences#seasonal-look). |
| **Notifications** | `/dashboard/settings/notifications` | Choose in-app and email delivery for each configurable notice. |
| **Data & privacy** | `/dashboard/settings/privacy` | Request and download your data, read the export log, and review privacy controls. |
| **Account & channels** | `/dashboard/settings/account` | See your channel memberships, leave a channel, open the danger zone of a channel you own, or request profile deletion. |

The same window also contains [Security](/user-guide/account-security) and [Developer limits](/user-guide/developer-limits) on the **You** side. The **Channel** side contains [Channel settings](/user-guide/channel-settings), [Connections](/user-guide/connections), [API keys](/user-guide/api-keys), [Popout tokens](/user-guide/tokens), and [Subscription and invoices](/user-guide/billing). The channel selector changes the active channel in the dashboard; settings for a different channel load for that channel. Areas that your role or plan does not allow are absent from the list, and a direct link still runs the same access check.

The personal overview shows your avatar, display name, Lumio ID, and support code, each with its label on the left. The copy button next to a value turns into a green check for a moment once the value is copied. In Streamer Mode the ID and code are covered with dots in their own shape and a line says that copying still works; the eye reveals a value. On narrow screens the ID block moves onto its own line below the status chips, and a long ID is shortened in the middle (`57755ce9…c51e39123`); copying always copies the full ID. On phones the overview head shows only the title and the 2FA and Streamer Mode chips. The support code rotates hourly; **new in … min** next to it shows when the next one comes. When the server cannot issue support codes, the row says **Not available right now** instead. Give it to Lumio support only when you contact them; it does not sign anyone in. The overview also links to your [sign-in methods and sessions](/user-guide/account-security). The 2FA chip summarizes whether your profile has an authenticator app or passkey; manage the methods under **Security → Sign-in**.

Your displayed name and picture come either from one of your platform sign-ins or from **your own details**. Choose under **Name & picture from**; every sign-in is listed with its platform icon (for example *Twitch · cruex*), and **Own details** sits below a divider. The head of the Profile area shows *@login · Member since March 2026*, or *Own details · Member since …*. With a platform sign-in as the source, Lumio copies its name and picture again at every sign-in. When you switch to your own details, your current name and picture stay as the starting point. You can then:

- change the name: 2 to 32 characters, leading and trailing spaces are removed, invisible characters are not allowed;
- upload a picture: PNG, JPEG or WebP up to 5 MB and 16 megapixels. Drop it into the dialog or choose it, then move it with the mouse, a finger or the arrow keys, zoom with the slider or **+** / **−**, and **Rotate** in 90° steps; three previews show the round result. Lumio uploads the visible square, crops it to a square again, stores it at 512 × 512 and 128 × 128 pixels, and removes all embedded metadata such as location data. You can upload up to 10 pictures per hour;
- remove the picture, so your initials are shown instead.

Signing in through a platform no longer changes your own details. Switching back to a platform sign-in asks first, then shows its name and picture again right away and deletes the picture you uploaded. An uploaded picture is part of your [data export](/user-guide/privacy-and-export) and is deleted together with your profile. E-mail-only profiles always use their own details.

Your profile email is set in one place only: **Security → Sign-in → Email & password**. With an email sign-in, your profile email is always its confirmed address, and it follows when you change that address. Without one, a platform can fill an empty profile email when you sign in with it. When you remove the email sign-in, the platform address it replaced comes back; if there was none, you have no profile email. The **Email** row only shows the address: where it came from (a shield and "confirmed on …" in the accent color for your email sign-in, the platform's logo and "not confirmed" for a platform address) and a link to **Security → Sign-in → Email & password** — **Change** with an email sign-in, **Set with email & password** without one. An address taken from a platform also has **Remove**, which asks first; the address of your email sign-in is changed or removed with the email sign-in. Without any address the row says **No email address**. In Streamer Mode the address is covered.

Old `/account/profile`, `/account/sessions`, `/account/activity`, and `/account/accounts/*` addresses redirect to the matching settings areas. Use the short links above when sharing an area outside the dashboard.

Settings for the whole channel (its name and picture, revenue assumptions, dissolving the channel) are in [Channel settings](/user-guide/channel-settings). In **Settings → You → Account**, the link **Channel settings › Danger zone** next to a channel you own opens its danger zone there and switches to that channel first if it is not the active one. **My channels** on the Profile area lists each channel with its picture, the icons of its connected platforms and your role; when the channel's name and picture come from a platform, its icon sits as a badge on the picture.

See [Preferences](/user-guide/preferences), [Notifications](/user-guide/notifications), and [Data & privacy](/user-guide/privacy-and-export) for the controls in each area.

---

## User Guide / Preferences

Source: https://docs.lumio.vision/user-guide/preferences

# Preferences

Preferences control how Lumio renders language, time zones, date/time values, currency, and motion for your own user profile. They are personal settings: they follow you across devices, browsers, and every channel account you can access. They do not belong to the selected account, so changing them in one account changes the same values everywhere you sign in.

## Where to find them

Open **Settings → You → Appearance** (`/dashboard/settings/appearance`) and use the **Region & Language** section.

The section is available in the dashboard account context and in your personal profile context. No account role or RBAC permission is required because the values are stored on your user, alongside personal settings such as Streamer Mode and notification preferences.

Settings that belong to a channel rather than to you, such as the revenue assumptions or dissolving a channel, are in [Channel settings](./channel-settings.md).

### A second entry point in the Multichat, Events and Music settings

The language, timezone, date and time controls also appear as a **Region & language** block in the settings panel of the Multichat, Events and Music views (open the settings gear, on the **General** tab). It is the same global preference, not a second value: changing it there writes your user profile exactly like the settings page, so both entry points always agree. The block carries a hint that it applies everywhere you sign in, because every other setting in those panels is stored per channel account.

In an **OBS popout that authenticates with a popout token** the block is **read-only** — it shows your current language, time zone and date/time examples and points you to the dashboard settings page — because a token-authenticated popout has no signed-in user to write the profile to. A popout you open while signed in with your normal session shows the editable controls.

## Language

The **Language** control offers:

| Value | Meaning |
|---|---|
| Automatic | Use the request-time fallback for the app language. |
| English | Render the web app in English. |
| Deutsch | Render the web app in German. |

Choosing English or German saves the value to your user profile and mirrors it into the `locale` preference cookie so the next server render uses the same language. Choosing **Automatic** clears that cookie mirror, so Lumio falls back to the default language when no other valid language cookie is present.

The language switcher in the sidebar writes the same user setting. It is just the quick-access control for the same preference, so switching language there also follows you to other devices after you sign in.

You can also open a Lumio web or sign-in link with `?lang=de` or `?lang=en`, for example `https://lumio.vision/features?lang=de`. The page renders in that language for this request without redirecting. A valid link language takes precedence over the language cookie for that request. If your browser has no `locale` cookie yet, Lumio stores the link language in one; if a cookie already exists, the link leaves it alone. On a later visit without `?lang=`, your saved language cookie applies again. Other `lang` values are ignored.

## Timezone

The **Timezone** control lets you choose **Automatic** or any specific IANA timezone such as `Europe/Berlin`. Every IANA zone your browser knows is selectable — plus `UTC` — so there is no short list to fall off the end of.

The control is a searchable dropdown: open it and type to filter. The search box stays pinned at the top of the open list while you scroll, and filtering hides whole groups — a country header only appears while at least one of its zones still matches, so you never have to scroll past empty headings to reach a result. Zones are grouped **by country** — each group header is the country name in your interface language — and every entry shows its current UTC offset (for example `UTC+02:00`). The offset is the value in effect right now, so a zone that observes daylight saving time reads `UTC+02:00` in summer and `UTC+01:00` in winter. The search matches the city name (`New York`), the raw IANA id (`America/New_York`), the country name and code (`Germany` / `DE`), the offset (`+02` / `UTC+02` / `GMT+2`), and the zone's abbreviations and full names — in both your interface language and their international forms, for both daylight-saving phases. Typing `MEZ` or `MESZ`, `CET` or `CEST` finds `Europe/Berlin`; `EST` or `EDT` finds `America/New_York`; `GMT+2` finds every zone currently two hours ahead of UTC. Because both phases are indexed, a summer abbreviation still finds its zone in winter and vice versa. If you already have a timezone saved that your current browser does not list — the same zone can carry different alias names across browsers — it still appears under **Other** so the dropdown reflects what is stored. Search terms that are not spelled out in an entry's label — the raw id, the country code, the unpadded offset, the abbreviations from other languages — are matched but never displayed: once a zone is selected the closed control reads it back as its country, city and, when the zone has a named abbreviation in your interface language, that abbreviation before the current offset (`Germany, Berlin — CEST · UTC+02:00`; `United Kingdom, London — UTC+01:00` when the language has no distinct abbreviation for it); a fixed-offset entry reads back as its offset (`UTC+05:00`). Where the control is too narrow — on a phone, for example — it wraps onto a second line between place and zone instead of cutting the text off. The country groups, the offsets and the abbreviations appear once the page has loaded in your browser; until then the control shows the plain IANA id (`Europe/Berlin`).

Below the country groups there is a **Fixed offset** group: `UTC` and the whole `UTC−12:00` … `UTC+14:00` range. These entries are pure offsets that never shift for daylight saving time, which is why the country groups come first — pick a country zone if you want your local time to follow its seasonal changes.

| Value | Meaning |
|---|---|
| Automatic | Detect the browser's timezone on the client — shown with its country, city and abbreviation (`Automatic — Germany, Berlin · CEST`), or the offset where your interface language has no named abbreviation — and mirror it into `lumio-tz` for server-rendered pages. |
| IANA timezone | Use the selected timezone everywhere Lumio formats your times. |

The **Automatic** entry always describes the zone your browser reports right now, not the zone you currently have saved — so you can see what picking it would give you before you pick it. With `America/New_York` saved on a machine in Germany, the entry still reads `Automatic — Germany, Berlin · CEST`.

The live preview in the setting shows the effective zone — the one Lumio is formatting your times in today, which is your saved zone while a specific one is selected. Automatic detection and the per-entry offsets are computed after the page mounts, so the browser's timezone is never read during server render; until the page has mounted the entry reads plainly as **Automatic**, without a detected zone.

## Date Format

Date and time format share one row, **Date & time format**, with a preview of today's date and time in the chosen formats and timezone. The **Date format** control changes numeric dates. The setting affects field order and separators only; month names and other text always follow the language setting.

| Value | Example |
|---|---|
| Automatic | Uses the language locale's normal numeric date format. |
| `dmy_dot` | `31.12.2026` |
| `dmy_slash` | `31/12/2026` |
| `mdy_slash` | `12/31/2026` |
| `ymd_dash` | `2026-12-31` |

## Time Format

The **Time format** control changes numeric times.

| Value | Example |
|---|---|
| Automatic | Uses the selected numeric format locale's default hour cycle. |
| `h24` | `23:30` |
| `h12` | `11:30 PM` |

## Display Currency

Under **Region & Language → Currency**, choose **Automatic** or an ECB reference currency. Automatic resolves to EUR for German and USD for other languages. Your choice follows your user profile across devices. Stream History uses it for estimated revenue, converted donations and Super Chats, and report exports; the report also offers a temporary quick switch. Historical conversions use the ECB rate from the stream date, and amounts without a recent rate stay in their original currency. See [Stream History](./stream-history.md#estimated-revenue-and-ads).

## How the Values Are Applied

These values are saved on your user profile through `PATCH /api/users/me`, then the dashboard refreshes so server-rendered pages and client components resolve the same settings.

Only language and timezone need cookies for server-rendered pages:

| Cookie | Purpose |
|---|---|
| `locale` | Mirrors an explicit language choice. |
| `lumio-tz` | Mirrors the resolved timezone. |

Date and time format presets are read from your user profile by the dashboard shell and provided to client components. Numeric date/time output uses the format preset, while textual output such as month names, weekday names, and relative time remains in the language locale.

## Animations in Lumio

Under **Settings → You → Appearance**, **Animations in Lumio** controls motion across the signed-in dashboard, Chat, Events, Music and their popouts (including OBS). It is saved on your user profile and follows you across devices and accounts.

| Choice | Result |
|---|---|
| **System** (default) | Normal animation, or Reduced when your operating system requests reduced motion. |
| **Reduced** | No movement, scaling or repeating decoration. Short fades remain. |
| **Off** | App animations and transitions happen instantly. Loading still has a visible signal. |

Your operating system's reduced-motion request always applies; neither the global choice nor a per-view choice can turn it back on. Animated emotes and GIFs in Chat keep playing because they are viewer content.

Chat, Events and Music each have their own **Animations** row in the settings gear: **As global**, **Reduced**, or **Off**. This choice applies only to that view, is stored per browser and per user/account pair, and works on its dashboard page and popout. It can only be stricter than the effective global value; when global motion is Off, Reduced is unavailable. An OBS dock can set it in the view or use `?motion=reduced` or `?motion=off` on its popout URL. The URL choice affects that popout only and is not saved. A popout can read your global preference but cannot change it; use dashboard Settings for that.

The **Seasonal animations: Automatic / Off** row below is separate: it controls seasonal decoration only. The stricter of your system, **Animations in Lumio**, and the seasonal row wins for that decoration. At global Reduced or Off, seasonal decoration stands still; at global Off, the seasonal row is disabled with an explanation. The seasonal row cannot make other app animations move.

## Seasonal Look

During certain weeks of the year the dashboard can wear a seasonal look. The available looks are **Halloween, 1–31 October**, and **St. Nicholas, 4–8 December**. St. Nicholas takes precedence during its window even when the Christmas calendar window overlaps it; Christmas itself has no look yet. Season windows are counted in your effective timezone (the [Timezone](#timezone) preference, or your browser's zone on **Automatic**), so a season starts and ends at your local midnight. Outside a season nothing changes.

Configure it under **Settings → You → Appearance** (`/dashboard/settings/appearance/seasonal-look`):

| Control | Default | Options |
|---|---|---|
| **Show seasonal look** | On | On / Off. It starts automatically during the season. One switch for every season — switched off, you get no seasonal look at any time of the year. |
| **Strength** | Full | **Subtle** — seasonal colours, the seasonal logo and the seasonal icon on the Chat emote button (see **Halloween emote button** below). **Full** — Subtle plus a dismissible banner, the season's header scenery, footer and input-bar strips, seasonal loading indicator, saved-message accent and seasonal empty states in Events and Chat. |
| **Seasonal animations** | Automatic | **Automatic** — the decorations move unless your operating system or browser asks for reduced motion. **Off** — the decorations stay but never move (the seasonal loading indicator fades in and out instead, so you can still tell something is loading). There is no "always on": Lumio never overrides a reduced-motion setting. Only available at Full (Subtle has no animations). |
| **Creatures** | Per animal (see below) | One row names a few animals and how many are on (for example *7 of 8 on*); it opens the animals of every season, grouped by season. The switches are available when the look is on and Strength is Full. |

The seasonal look sits on top of your light or dark theme and works with both. Chart and platform colours never change. Decorative motion follows your animation settings. Halloween logo blinks are limited to 2.5 times a second; St. Nicholas stars twinkle without flashing.

**St. Nicholas look.** From 4 to 8 December, the Subtle look uses cream and cocoa tones, carmine and gold, a still boot-shaped Lumio logo, and a Nicholas-head emote icon. At Full, the banner, golden-star loader, boot empty states and chocolate-coin saved-message accent appear too. The page-header scenery shows snow, stars, an arched window, a boot and a robin. The window sits below the top edge of the scenery; on wider screens it stays to the left of the header buttons and above the first card row. The boot can react to a shooting star and the robin can fly before returning to its perch. The footer and the Chat, Events and Music bars show snowy roofs on five complete houses per tile, with filled snow caps and lit windows; a small Nicholas figure occasionally peeks from behind a roof. Individual roof windows occasionally go dark and light up again. With motion Off or Reduced, every roof window stays lit and the other decorations stand still while the loading stars continue to pulse. Scheduled motion pauses while the browser tab is hidden.

On the full-height Chat and Events pages and in popouts, the compact header shows a star garland and a hanging boot. The robin may fly across the header, passing behind its buttons and tab text. The artwork remains behind the controls and never blocks a click. The **Robin** switch controls the bird in both header sizes. The banner can be dismissed for the current St. Nicholas season; **Switch off** disables every seasonal look.

**Halloween scenery.** At Full, the top of every dashboard page shows a scenery behind the content: a crescent moon with a soft, warm halo in the top-right corner, a spider web in the corner and three bats beside the page title. In the dark theme the moon is pale yellow with a faint glow and the bats are pale; in the light theme the moon is golden with a golden glow and the bats are dark violet, so they stand out against the light background. The bats appear on screens from tablet width upwards. The Chat and Events pages fill the whole window, so they show the smaller popout scenery behind their tab bar instead: the corner spider web (with its spider if **Spiders** is on), two bats and, about every one to two minutes, a small bat flying across the tab bar — without the moon.

| Situation | Scenery |
|---|---|
| Idle | The bats glide slowly on the spot. Now and then — every 4–10 seconds, each bat on its own timer, so they never move together — a bat beats its wings two or three times, then glides again. |
| About every one to two minutes | One bat flies across the top of the page: it comes in from one side, flies a gentle arc and leaves on the other side within a few seconds, flapping as it goes. Never more than one at a time. It stays behind the page content and dialogs and never blocks a click. |
| **Animations: Off**, or reduced motion requested by your system | The moon, web and bats stay where they are and nothing moves: no gliding, no wing beats, no fly-by. |
| Browser tab in the background | Wing beats and fly-bys pause; nothing is caught up when you come back. |

**Halloween loading indicator.** At Full, wherever the dashboard shows a loading indicator for a page, a section, a panel, a list or a dialog — for example the Events list — three small ghosts take the place of the spinning circle. They bob up one after another, like typing dots. With **Animations: Off**, or reduced motion requested by your system, they stay in place and fade in and out one after another instead, so the dashboard still shows that it is loading. Small spinners inside buttons and fields (such as "Saving…") stay the regular spinner. Screen readers announce "Loading…".

**Creatures.** Some people are afraid of certain animals, so you can switch them off before their season starts. The settings list the animals of every season that has them, all year round. Each group shows the season's name and window. The season running now appears first with a **Running now** label; the others follow in order of their next start date. Each switch shows its default. The switches stay visible but are unavailable at Subtle strength or when the seasonal look is off. Like the rest of **Appearance**, your choices are saved on your profile. If an animal appears in more than one season, its switch controls that animal in every season.

**Halloween · 1–31 October**

| Animal | Default | What it covers |
|---|---|---|
| **Bats** | On | Every bat in the look: the gliding bats with their wing beats, the bat flying across the page and the bats on the "saved" message. Off — no bat anywhere. |
| **Spiders** | Off | A small spider in the corner web. Off — the web stays empty. |

**St. Nicholas · 4–8 December**

| Animal | Default | What it covers |
|---|---|---|
| **Robin** | On | The robin beside the boot in the page-header window and on the compact garland, including its flights. Off — no robin is shown. |

When **Spiders** is on, the spider sits on a strand of the corner web most of the time. Every 20–40 seconds it either crawls a short way along the strand and stops there, or — less often — lets itself down a little on a thread, hangs for a moment and climbs back up. It moves its legs as it walks, stays behind the page content and dialogs, and never blocks a click. With **Animations: Off**, with reduced motion requested by your system, or while the browser tab is in the background, it sits still in the web.

**Halloween logo.** At Subtle, the Lumio logo becomes a still carved pumpkin. At Full, the logo is a lit pumpkin in the expanded and the collapsed desktop sidebar, in the mobile header and in the page footer: the L and the triangle are cut out of it, a warm candle light shines in both cut-outs, and a soft glow ring surrounds it. What it does:

| Situation | Logo |
|---|---|
| Idle | Every 6–15 seconds the candle flickers in a short burst of 3–6 blinks. Each blink puts out the light behind the L or the triangle, picked at random, for about a fifth of a second, so you look through the hole at the page behind it. About every third blink also tips that cut-out slightly before it settles back. |
| Mouse over the logo | Blinking stops at once, both cut-outs light up brighter and the pumpkin wobbles once. In the expanded sidebar, the dot of the "i" in "Lumio" also turns into a witch on a broom and flies off to the right in a flat arc over the top of the page, fading out before it reaches the edge of the window; it never blocks a click. The collapsed sidebar, the mobile header and the footer have no witch. When you move the mouse away, the dot comes back and the idle blinking resumes. |
| Touch screens | A tap is not a hover: no wobble and no witch. The idle blinking still runs. |
| **Animations: Off**, or reduced motion requested by your system | The pumpkin glows and both cut-outs stay lit, but nothing blinks, tips, wobbles or flies. Hovering only makes the light brighter. |
| Browser tab in the background | Blinking pauses, and no blinks are caught up when you come back. |

Screen readers always read the logo as "Lumio".

**Halloween footer.** At Full, a small graveyard stands on the top edge of the footer at the bottom of every dashboard page: tombstones, a cross, a crooked stone, a little fence, a bare tree and small pumpkins. It is a faint silhouette — pale in the dark theme, violet-grey in the light theme — with the pumpkins in orange. It sits above the footer card, never covers the links or the version line, and never blocks a click. The footer logo is the lit pumpkin described above (no witch). The footer links — Privacy, Terms, Imprint, Cookies — never move or change.

| Situation | Footer |
|---|---|
| Footer visible on screen | About once a minute (every 45–75 seconds) a small ghost rises from behind one of the visible tombstones, the cross, the fence or the tree, looks around for about a second and sinks back — about two and a half seconds in all. Each time it picks a spot at random, never the same one twice in a row. |
| Footer scrolled out of view, or browser tab in the background | No ghost, and nothing is caught up when the footer comes back into view. A ghost that is peeking when the footer leaves the screen disappears. |
| **Animations: Off**, or reduced motion requested by your system | The graveyard stays, the ghost never appears and the logo stands still. |
| Subtle | Only the seasonal colours: no graveyard, no ghost. |

**Halloween search and input bars.** At Full, the same graveyard also stands on the top edge of the **search bar at the bottom of Events** and of the **message input bar in Chat**, on the dashboard pages and in the chat and events popouts, and of the **search bar of the Music popout**, including popouts inside OBS. Here it is a narrow band, about 16 pixels high, that belongs to the bar itself: the tombstones stand on the bar's dividing line, just like on the footer, and the graveyard runs the full width of the bar, from edge to edge. The bar grows by that much, so the band never covers the last message or event row above it. While you reply to a message in Chat, the graveyard and its line sit on top of the **Replying to** box, which is part of the input bar, so nothing comes between the reply box and the message field. Without the graveyard (Subtle, season off) the line is the top edge of the bar, as usual. An open reply box does not keep the ghost away. It also never covers the search or message field, its placeholder, the platform toggles, the emote button, the send button, the clear-search button or the popout settings. The mention list and the emote library open above the bar, on top of the band (in windows up to 480 pixels wide the emote library's bottom sheet ends right at the band's top edge, so the graveyard stays visible), and the band never blocks a click.

| Situation | Search bar / input bar |
|---|---|
| Bar visible and idle: the field is empty, nothing was typed for 4 seconds, and the emote library and the popout settings are closed (the field may still have focus, for example right after sending a message) | Every 15–30 seconds a ghost rises out of the ground at one of the tombstones, the cross, the fence or the tree until it is fully visible inside the band, looks left, looks right and sinks back — about three and a half seconds in all. In about one peek in three it glides instead to another stone 40–80 pixels along the bar before it sinks. |
| Field contains text, you typed in the last 4 seconds, the mention list or the emote library is open, or the popout settings are open | No ghost. A ghost that is peeking when you start typing sinks back right away. |
| Bar scrolled out of view, or browser tab in the background | No ghost. |
| **Animations: Off**, or reduced motion requested by your system | The graveyard stays and the ghost never appears. |
| Subtle, or the seasonal look switched off | No band at all, and the bar has its regular height. |

Never more than one ghost is on screen at a time on a page, however many places show a graveyard. The footer, the Events search bar and the Chat input bar share one ghost. It picks a random spot among all graveyards that may show it right now, never the same spot twice in a row — every 15–30 seconds while a search or input bar may show it, otherwise (only the footer) every 45–75 seconds. On the Chat page, for example, it sometimes peeks at the footer and sometimes at the input bar, but never at both at once. The [URL parameters for popouts](#popouts-and-obs) apply to the band as well: `seasonStrength=subtle` removes it and `seasonMotion=off` keeps the ghost away.

**Halloween emote button.** In the Chat message input bar — on the dashboard Chat page and in the chat popout, including inside OBS — the emote button shows a small ghost instead of the smiley face, at the same size and in the same colour as the button's other icons. The button works exactly as before: one click opens or closes the emote library. Screen readers announce it as "Emote picker".

| Situation | What the emote-button ghost does |
|---|---|
| Full, **Animations: Automatic**, browser tab in front | When you point at the button or move keyboard focus to it, the ghost looks left, looks right and turns back — about two seconds. Now and then it also does this on its own while the input bar is idle (the same rule as the graveyard ghost: empty field, nothing typed for 4 seconds, emote library and popout settings closed). |
| A graveyard ghost is peeking somewhere on the page | The emote-button ghost stays still, also when you point at the button. It counts as the page's one moving ghost, so the graveyard ghost waits while it glances. |
| The emote library is open (Full, **Animations: Automatic**, browser tab in front) | The ghost sways calmly left and right, over and over, until you close the library. Then it eases back to its resting position. While it sways it is the page's one moving ghost: a graveyard ghost that is peeking sinks away, and no other ghost appears until the library is closed. |
| The popout settings are open | The ghost stays still. |
| Subtle, **Animations: Off**, or reduced motion requested by your system | The ghost is shown but never moves. |
| Outside the season, or the seasonal look switched off | The regular smiley face. |

**Follows your account.** Like the other settings on this page, **Appearance** is saved on your user profile, so it applies on every device and in every browser you sign in with. A change takes effect immediately in the tab you made it in and in your other open tabs of the same browser; another device picks it up the next time it loads the dashboard or comes back to the foreground (at most every five minutes). To paint the right look before the page has loaded, the browser keeps a copy in the `lumio-season` preference cookie (see [Cookie Preferences](/user-guide/cookie-preferences)); clearing it is harmless — the next dashboard load restores it from your profile. Settings you chose in a browser before they moved to the profile are carried over once, the first time that browser opens the dashboard, provided you have not chosen anything on your profile yet.

**Banner.** At Full, a short banner sits at the top of every dashboard page while a season runs. The Chat and Events pages show it as a full-width strip directly under their tab bar, above any connection notices; it shortens the message or event list, and the chat input and the events search stay in view. The fullscreen overlay and widget editors never show it. It has two buttons:

| Button | What it does |
|---|---|
| **×** | Hides the banner for the rest of that season — on the dashboard, in every popout and on all your devices. The seasonal look itself stays. The next season (or the same season next year) shows its banner again. |
| **Switch off** | Switches the seasonal look off right away — the same **Seasonal look** switch as above, so it is off for every season, not just the current one — and hides the banner. It takes effect at once in this tab and in your other open tabs and popouts of this browser; another device picks it up the next time it syncs. A message confirms it and links to **Settings**, where you can switch it back on; it also offers **Undo** for a few seconds. If saving fails, the look comes back and an error message says so. |

**Preview for admins.** Lumio staff who can sign in to the admin app and hold the `devtools:read` permission see a small wrench icon directly left of **Logout** at the bottom of the sidebar (expanded and collapsed sidebar, and the mobile menu), and can also open it with **Ctrl + Alt + Shift + D** (Mac: **⌘ + ⌥ + ⇧ + D**; ignored while typing in a text field). It opens the **Dev & Admin** menu, whose **Season preview** has three modes, one at a time:

| Mode | What you see |
|---|---|
| **Automatic** (default) | The calendar decides, exactly as every other user sees it. |
| **Force season** | Pick Halloween, Christmas, St. Nicholas, New Year's Eve, Easter or **None**. Seasons marked **No look yet** have no look, so nothing seasonal is shown for them. |
| **Simulate date** | Pick a day; the calendar decides which season would run then (including overlaps such as St. Nicholas inside Christmas, and the movable Advent and Easter dates). The menu names the season for that day. |

The preview shows the look even if you switched **Seasonal look** off above. It applies only to you, only in this browser: it is kept in the browser's local storage, never saved to your profile, and nobody else sees it. While it is active, a small **Preview: … · only you** badge stays at the bottom of the screen; **End** returns to the calendar. Users without the permission see no icon, and the shortcut does nothing for them.

The preview also applies to the chat, events, music and test-events popouts you open **in the same browser** — whether you are signed in there directly or the popout uses a [popout token](/user-guide/tokens), as long as you are signed in to Lumio in that browser with the permission. A small **Preview: … · only you** strip under the popout header shows it, with **End** to end the preview for the whole browser, dashboard included. Starting, changing or ending the preview updates open popouts and dashboard tabs right away, without a reload. A popout URL with `?season=off` shows no seasonal look even during a preview. An OBS dock or browser source has its own browser and never shows your preview.

### Popouts and OBS

The seasonal look also appears in the five popouts — `/popout/chat`, `/popout/events`, `/popout/music`, `/popout/test-events` and `/popout/obs` — wherever you open them: in a browser window, as an OBS custom browser dock, or as an OBS browser source. A popout follows the **Appearance** settings of the user it shows: your own when you are signed in, or those of the member a [popout token](/user-guide/tokens) is bound to. Without a session it uses the defaults (on, Full, Animations Automatic, bats and robin on, spiders off). A popout only reads these settings; the only things it can change are the two banner buttons below, and it can only switch the look **off**, never on.

Because a popout is narrow, it shows seasonal colours, loading and empty states, the saved-message accent, the season's Chat emote icon, and at Full a strip along the Chat input, Events search or Music search bar. The header uses compact scenery: Halloween has a corner web and bats without the moon; St. Nicholas has a star garland, hanging boot and robin. The St. Nicholas robin may fly behind the header buttons and tab text. Both looks stay behind content and controls and never block a click. **Animations: Off** and your system's reduced-motion setting work as on the dashboard.

**Banner in popouts.** At Full, the chat, events, music and test-events popouts show a compact version of the [banner](#seasonal-look) — one thin strip directly under the popout header (at the top of the music popout) with the same information in short form, for example "Happy Halloween! Halloween look until 31 Oct. Overlays unchanged." It sits above the messages, events, test catalog or player and moves them down; it never covers them. In a narrow popout it wraps onto two or three lines rather than cutting text off. It has the same two buttons as on the dashboard:

- **×** hides the banner for this season everywhere — in every popout, on the dashboard and on all your devices.
- **Switch off** switches the seasonal look off for every season, just like the setting. A message names **Settings** as the place to switch it back on; a popout has no **Undo**, because a popout can only switch the look off.

This also applies inside OBS: a chat, events or music popout added as an OBS browser source shows the banner on stream until someone closes it. Close it once (in any popout or on the dashboard) or add `season=off` to that URL (see below). The OBS control popout (`/popout/obs`) has no banner. Subtle and `season=off` hide it, exactly as on the dashboard.

To change the look of one popout without touching your settings — for example a dock inside OBS, where you cannot open the settings page — add a URL parameter. It applies to that URL only and is never saved:

| Parameter | Effect |
|---|---|
| `season=off` | No seasonal look on this popout. |
| `season=on` | Seasonal look on this popout even when **Seasonal look** is off in your settings. |
| `seasonStrength=subtle` | Colours only (no decoration, regular loading indicator). |
| `seasonStrength=full` | Full, even when your setting is Subtle. |
| `seasonMotion=off` | The decoration stays still (the seasonal loading indicator fades instead of moving). |
| `seasonMotion=auto` | Use the seasonal **Automatic** setting; global motion and the OS can still keep decoration still. |
| `motion=reduced` | Reduce app animation in this popout only, if its global value is less strict. |
| `motion=off` | Turn app animation off in this popout only. |

Append with `?` when the URL has no parameters yet, otherwise with `&` — for example `https://lumio.vision/popout/chat?token=lm_pop_…&seasonStrength=subtle`. Unknown values are ignored. The last screen of the popout-token wizard lists these parameters next to the token.

### Overlays stay unchanged

Overlays, widgets, extensions, the fullscreen overlay/widget editors, the landing and legal pages, the login pages, the admin app and the public stats site always look the same — what you show on stream through an overlay or widget does not change.

## Related

- [Dashboard](/user-guide/dashboard) - sidebar, account switching, and dashboard navigation.
- [Cookie Preferences](/user-guide/cookie-preferences) - consent categories and preference-cookie management.
- [REST API](/api-reference/rest-api#get-usersme) - `GET` / `PATCH /v1/users/me` preference fields.
- [GraphQL](/api-reference/graphql) - `me` and `updateMe` preference fields.

---

## User Guide / Account Security

Source: https://docs.lumio.vision/user-guide/account-security

# Account Security

Open **Settings** in the dashboard, choose **You** at the top left, then choose an area under **Security**: **Overview** (`/dashboard/settings/security`), **Sign-in & 2FA** (`/dashboard/settings/security/login`), **Sessions** (`/dashboard/settings/security/sessions`), or **Activity** (`/dashboard/settings/security/activity`). These areas belong to your Lumio profile, even when no channel is selected. The links open the settings window over the dashboard home; while you work in the dashboard, the window stays over your current page and its address ends in `#settings/security/…`.

**Overview** shows a ring with how many of four checks are done and one tile per check: sign-in methods, two-factor authentication, active sessions, and failed sign-ins of the last 30 days. The sessions tile names the device and place of the session unused for the longest time when one has been idle for more than five days; the failed-sign-in tile names the date, place and device of the latest attempt. Tiles that still need attention carry an arrow to their tab. In [Streamer Mode](./streamer-mode.md) the place in both sentences appears as `••••••••` with an **Eye**; the Eye reveals only the place without opening the tile's area, and the rest of the sentence stays.

## Sign-in methods

You can sign in with Twitch, Kick, Google, Discord, or a verified email address and password. **Google** is the sign-in method; a YouTube channel connection is a separate connection. For Google, the ID shown after `#` is your Google account ID, not a YouTube channel ID. The Sign-in & 2FA area's **Login connections** card groups platform connections by provider and ends with the **Email & password** row and shows the channels assigned to each connection. A connection that has to be reconnected gets a red frame and a **Reconnect** button. Reconnecting opens the sign-in page for exactly that connection: it shows the account in one row - provider logo, name · platform ID and its state (**disconnected**, **rights missing** or **connected**) - and asks you to sign in to the provider as that account. A different provider account is turned down without changing anything; the page then names the account you were signed in with and the one that is needed, and suggests signing out at the provider or using a private window. You can add a channel or confirm replacement of an existing assignment. Each channel chip has an **×** that removes the assignment. A sign-in does not decide a channel's name or picture; that is set in the [channel settings](./channel-settings.md#name-and-picture). With `account:edit` in the active channel, the top of the card says so and links there.

To add a platform sign-in, choose **Connect** in its group. The dialog explains the provider hand-off and lets you select up to 25 channels to assign. Confirm **Is it really you?** first: with 2FA enabled, confirm with a passkey, authenticator app code or recovery code; otherwise confirm with an existing sign-in method. The dialog lists them under **Confirm with**, each with when it was last used or connected; the one you last signed in with is pre-selected, and one that must be reconnected cannot be chosen. The browser then goes to the provider and returns to the dashboard with a success or error notice. Reconnecting an existing link to the same provider account does not require this extra confirmation. Removing a login method requires it and is refused if it would leave you with no sign-in method.

## Email and password

To set up email sign-in on an existing profile, choose **Set up** in the **Email & password** row, the last row of the **Login connections** card. The row shows the state: not set up, a pending link (with when it was sent), or active (the address, when it was confirmed, and when the password was last changed). Enter the address, pass the **Is it really you?** check, then open the confirmation link from your inbox. The check slides into the same dialog like the other steps, which stays on the **Address** step while it asks; it is skipped if you confirmed in the last 10 minutes. The link is valid for 24 hours, and until you finish nothing changes about how you sign in. The waiting dialog advances even if you open the link on another device. The link's page asks for a deliberate **Confirm** click; merely loading the page does not confirm it. Return to the dialog, choose a password (the eye button shows what you typed; a check mark appears once both entries match), and review the finished state. From then on the address is also your Lumio email: notifications and security emails go there. The progress bar at the top of the dialog shows where you are: **Address**, **Confirm**, **Password**. An unconfirmed request does not reserve the address. If the address already belongs to another Lumio profile, it gets a notice instead of a link, saying that you can sign in with it or remove it there first under **Security › Sign-in**; nothing changes. Once the password is set, Lumio sends a security email to your previous profile address and to the new one. It names the new address, the date and time (in your timezone), the browser and operating system and, when it can be determined, the country — never the IP address. If that wasn't you, open **Security** and remove the method. In [Streamer Mode](./streamer-mode.md) every address in this row and in the setup dialog, including the address field, appears as `••••••••` with an **Eye** to reveal it.

The same section lets you change the sign-in address, resend or cancel a pending link, change the password, or remove email sign-in. The old address remains active until its replacement is confirmed. A password reset starts from **Forgot password?** on the ID-app sign-in page; the response does not disclose whether an address has a Lumio account. Completing the reset ends existing sessions, while 2FA stays enabled. Email confirmation by itself never signs you in.

After a wrong password, the entered password stays in the field, marked red, so you can correct it. From the second wrong password on, Cloudflare Turnstile checks in the background that a person is signing in; if Cloudflare is unsure, a checkbox appears across the card, the red notice asks you to confirm you are human, and **Sign in** stays locked until you tick it. Registration, **Forgot password?** and resending a link run the same check, and lock their button the same way while the checkbox waits. After five wrong passwords for an address, password sign-in pauses for 15 minutes. The sign-in page then shows **Short break** with the remaining minutes, **Reset password**, and the platform buttons, which keep working. If Lumio cannot be reached, the page says so, keeps its buttons visible but locked, and tries again on its own every few seconds.

Your email sign-in also sets your profile email, the address Lumio sends mail to, invoices and notices included (the setup dialog says so too): while you have an email sign-in, the profile email is always its confirmed address and follows when you change it. This section is the only place where you set an address; [Settings → Profile](/user-guide/settings) shows the profile email and its source and links here. When you remove the email sign-in, the profile email goes back to the address a platform sign-in gave you before, or is empty. A platform's unverified email claim is not proof that it owns your email sign-in, and Lumio does not automatically link profiles by matching email text.

## Two-factor authentication and recovery

Open **Security → Sign-in** to manage your profile's authenticator apps and passkeys. You can keep up to **five authenticator apps** and **ten passkeys** together. Your first method turns 2FA on; turning 2FA off removes every method. The Security overview shows the number of each. Each method has its own name (up to 40 characters), added date and last-used date; you can rename or remove it. Choose names without personal details. Only you see these names, not administrators, audit entries or security notices.

Choose **Set up** or **Add a method**, then choose **Passkey** or **Authenticator app**. Both require a recent **Is it really you?** confirmation. To add an app, scan its QR code or enter the shown key, then enter its six-digit code. Adding another app does not replace an existing one. For your first method, save the ten recovery codes and finish setup; adding further methods does not issue another set. A recovery code works once. **Generate new codes** replaces all unused codes immediately. Keep a copy somewhere private.

A passkey lives on a device, security key or password manager. It combines possession with unlocking that device **or password manager**; it does not demand a fingerprint at every sign-in. Choose **Add passkey**, complete your browser or password manager prompt, save the ten recovery codes if this is your first method, and name the passkey. The registration challenge lasts five minutes. If it expires, restart setup and discard the codes shown in that attempt. The list shows your chosen name and, when the browser supplies a known AAGUID, the provider or YubiKey model. Where Lumio has that provider's logo, it appears next to the name; otherwise the tile shows a generic passkey symbol. Some browsers suppress the AAGUID when Lumio requests no attestation; the entry then says **Passkey** with the generic symbol and can be renamed. A synced passkey and a device-only passkey are labelled accordingly. When at least one logo appears, the list shows this notice: **Provider logos are trademarks of their respective owners. Lumio is not affiliated with these providers.** Add a second passkey on a different device or password manager so losing one does not leave you relying only on recovery codes.

### Save a passkey in Bitwarden or 1Password

To save one in Bitwarden, open its browser extension and turn on **Settings → Notifications → Ask to save and use passkeys**. Choose **Add passkey** in Lumio and accept Bitwarden's save prompt. To use your device or a hardware key instead, choose that option in Bitwarden's prompt. Turn the same extension setting off if you do not want Bitwarden to offer to save or use passkeys; this also stops prompts for passkeys already in your vault. You can also exclude an individual domain. See [Bitwarden's passkey guide](https://bitwarden.com/help/storing-passkeys/). For 1Password, unlock the vault and choose it when the browser offers a place to save the passkey. Your browser and installed extensions determine which providers appear.

Passkey prompts need a supported system browser. **OBS and Streamlabs browser docks are unsupported**; open Lumio in a regular browser to create or use a passkey. Embedded in-app browsers such as Twitch or Discord on iOS and Android may not support them either. On Firefox for Linux, use a USB security key or passkey extension; phone QR hand-off is unavailable. Bitwarden's Firefox extension may not offer inline autofill; the **Sign in with passkey** button can still open it. If a passkey prompt fails, use an authenticator app or recovery code and try a supported browser.

When 2FA is on, every new email or platform sign-in asks for an app code, passkey or recovery code before a session begins. Signing in **with** a passkey already completes that second step. A trusted device can skip the second step for 30 days; revoke one or all trusted devices in the same section. Sensitive actions, including removing a method, turning 2FA off and generating new recovery codes, accept a passkey, an app code or a recovery code. Removing an individual method asks for confirmation; use **Turn 2FA off** to remove the last one. If you remove a passkey in Lumio, delete its entry from your device or password manager yourself; supported browsers may hide the unusable entry automatically. Removing the last method also clears recovery codes and trusted devices. If you lose all methods and recovery codes, contact support for a manual identity check and 2FA reset; the operator must record a reason.

If your account has admin access to Lumio and no 2FA method yet, the dashboard asks you to set one up: a dialog explains that admin access stays locked until you add a passkey or an authenticator app. **Set up two-factor** opens **Security → Sign-in** and starts the choice of method. **Later** hides the dialog until you close the browser; everything except admin access keeps working. The admin app sends you to the same dialog. Once your first method is added, the dialog no longer appears.

Lumio receives a passkey's public credential and signature, never biometric data or its private key. Registration sends your **display name**, never your email address, to the provider. Lumio requests `attestation: none` and does not use FIDO Metadata Service (MDS) to identify the device; provider names come from a local AAGUID list, with no runtime lookup.

## Sessions and activity

**Sessions** (**Active sessions**) shows device, sign-in method, whether 2FA was verified, approximate location, IP address, and last activity. Location can be absent when it cannot be resolved. The current session is marked **This device** and says in its row that it cannot be signed out here. The top of the table counts the sessions and the ones unused for more than five days (marked yellow), and holds **Export**, **Sign out unused (N)** while at least one session is unused, and **Sign out all others**; a note below the table says how many other devices **Sign out all others** signs out. **Sign out unused** asks for confirmation and then signs out exactly the sessions marked yellow, never this device. Sign out another session with its **Sign out** button, or tick several and use **Sign out selected** in the band that appears above the table. You can export all sessions or the selection as CSV or JSON. Streamer Mode covers the IP address and the location on screen; the export contains them in full.

Popout tokens are separate credentials and do not appear as sessions here. Revoking a browser session does not by itself revoke a popout token; manage those under [Tokens](/user-guide/tokens).

**Activity** (**My activity**) records your personal security events. Where the event carries it, the text names the context, for example **Sign-in via Twitch**, **Identity confirmed via authenticator app** or **Login connection Kick added**. Platforms appear under their brand name; a confirmation with an app code, a recovery code or the password is named as such. Filter by event or date (an empty end date means "until today"), expand a row for metadata and device details, and export the current filter or a selection as CSV or JSON. The export dialog shows the file name and its approximate size before the download; **Details (JSON)** starts unticked because the raw metadata is large. In Streamer Mode the IP address, location and user agent are masked per row, as in the [Audit Log](/user-guide/audit-log). The account-wide audit log has its own permission and page; see [Audit Log](/user-guide/audit-log).

---

## User Guide / Data & Privacy

Source: https://docs.lumio.vision/user-guide/privacy-and-export

# Data & Privacy

Open **Settings → You → Data & privacy** (`/dashboard/settings/privacy`) for self-service data exports and their request history.

## Export your data

Under **Data access & export**, pick one of two cards: **User data only** (for every profile) or **User + channel data** (only for channels you own; the card names them). Each card lists what the export contains. For the second model, select the owned channels to include; the optional chat data depends on the channel's plan and retention period. Then choose **Request export**. Lumio processes the request, notifies you when it is ready, and lists it in the export log. You can request one export per model at a time, with a 24-hour interval between requests of the same model.

Each log row shows the model, when you requested it, its state and what happens next: a progress bar with a percentage while it is created, **Ready** with the file size and the days left until it expires, **Expired** once the file is deleted, or **Cancelled**. To stop it, choose **Cancel** next to it. Lumio then stops building the file and keeps nothing; the entry stays in the log as cancelled. A cancelled export does not count towards the 24-hour interval as long as Lumio had not started building it yet, so you can request a new one right away. Once building had started, the cancelled export counts like any other. A finished export can no longer be cancelled.

When the ZIP is ready, choose **Download** and confirm **Is it really you?**. The resulting download link works for five minutes and for that export only. The export is encrypted at rest and removed after seven days. The ZIP includes a README explaining its files. If you uploaded your own profile picture, the export contains the picture file itself (`profile_picture.webp`). It does not contain passwords, API tokens, or other members' private identifiers. Its 2FA section lists `factors` with `kind`, `label`, `created_at`, and `last_used_at`. A passkey factor also has `provider` and `backup_state` (whether it is synced). The export excludes authenticator secrets, passkey keys, credential IDs, signature counters, the passkey user handle, and recovery codes. For example:

```json
{
  "factors": [
    {"kind": "totp", "label": "Phone app", "created_at": "2026-10-15T12:00:00Z", "last_used_at": null},
    {"kind": "passkey", "label": "Laptop", "created_at": "2026-10-15T12:05:00Z", "last_used_at": null, "provider": "Passkey", "backup_state": false}
  ]
}
```

The passkey's provider is a name looked up locally from the AAGUID supplied by the device; an unknown or withheld AAGUID is shown as `Passkey`.

Both models also contain what you did on Lumio as a person, outside any channel:

| File | Contents |
|------|----------|
| `ideas.json` | `ideas` you posted on the ideas board, your `comments` and replies, your `idea_votes` and `comment_votes`, and the idea `history` entries you caused. Other people's comments under your ideas and who voted on them are not included. A comment of yours under an idea that was deleted carries `idea_deleted: true` and an empty `idea_title`. |
| `developer.json` | Your developer `profile` with payout details (PayPal address and bank details in readable form; a value that can no longer be decrypted is `null`), `verifications`, developer `applications`, `limit_requests`, `payouts`, your self-billed `credit_notes` (number, dates, amounts, VAT treatment and the supplier details printed on them; the PDFs are in the developer settings under Payouts), `settled_released_balances` (a balance Lumio could not pay out when an earlier developer profile of yours was deleted and later credited to this profile with your claim code: amount, case, reason, release, claim and settlement dates), the developer `teams` you belong to with your role (no other members), and the `extensions` of your personal developer profile with their versions (metadata only, no bundles or sources). |
| `extension_reviews.json` | The marketplace reviews you wrote, with the extension name, rating and text. |
| `lumio_activity.json` | Your Stats `stats_watchlist`, `overlay_access` and `widget_access` shared with you, `extension_testing` invitations with your feedback, `channel_invites` addressed to you, your `channel_sign_in_assignments`, your `roles` (admin roles, user roles, permission overrides), and the `copyright_reports` and `copyright_confirmations` you submitted. Invite codes and who granted or assigned something are not included. |

Each section is an empty list (or `null` for the developer profile) when you have no such data. `sign_in_methods.json` also lists `known_sign_in_devices` with when each device was first and last seen (the device fingerprint itself is a hash and is not included).

The **Security → Activity** page and the account [Audit Log](/user-guide/audit-log) offer a separate CSV/JSON export of audit rows. The account log requires `audit-log:read`.

## AutoMod data and access requests

For Twitch messages held by AutoMod, Lumio keeps an AutoMod log with the sender, their last-known avatar, chat color and badges at hold time when available, the hold time, reason, outcome and moderator decision. The held text, flagged spans, blocked-term text, emotes and Cheers are kept with the log entry and deleted together with it once the hold is older than the account's chat retention window (Free 365 days, Pro 1,095 days), for **every** outcome, including denied, expired and allowed messages. An allowed message is also published as a new chat message and follows normal chat-message retention.

The log appears in the signed-in Stream History AutoMod tab for team members with both `history:read` and `chat:automod-read`, and as held-message rows in the chat history of Multichat and chat popouts for team members with `chat:read` and `chat:automod-read` (the last 24 hours without `history:read`). It is absent from shared reports, report exports and the self-service data export on this page. A chat participant can request access under Art. 15 GDPR at [hey@lumio.vision](mailto:hey@lumio.vision); the support response includes any AutoMod log rows Lumio still holds for that person. A participant can also object or request erasure there. The AutoMod log belongs to the channel: Lumio deletes a person's rows in a channel on that channel's instruction, in that channel only, and an objection does not stop new rows from being logged.

## Delete your profile

Open **Settings → Account** (`/dashboard/settings/account`). Three steps explain the way: **Export** (optional, a copy of your data first), **Confirm** (sign in again and hold), and **Choose the period**. Choose when the profile is deleted on one of three cards, each naming its date; **In 30 days** is preselected:

- **Now** - the profile is deleted right away, with no waiting period and no way back. You are signed out and the sign-in page says **Your profile was deleted**.
- **In 7 days** or **In 30 days** - Lumio ends your sessions and schedules the deletion for that date. The confirmation mail names it.

Then hold the red button for two seconds - it is named **Delete permanently now**, **Delete in 7 days** or **Delete in 30 days** - (or type your profile name when animations are Off) and pass a fresh **Is it really you?** check, which repeats the date. The check is needed for every choice.

If you own a channel that is not scheduled for dissolution, a yellow box names it and the button stays locked until you transfer, dissolve or schedule the channel for dissolution (see [Channel settings → Danger zone](./channel-settings.md)). Once every channel you own is scheduled, you can delete your profile with a period that ends no earlier than the last of them: the other cards are greyed out with the reason. **Now** needs you to own no channel at all. When both dates arrive, Lumio first dissolves the channels and then deletes the profile.

If you are an extension developer and Lumio still owes you money, the deletion pays it out first, and the section shows what applies above the step tiles:

- **A balance that can be paid out** — a blue box names the amount. With a waiting period of 7 or 30 days it is paid out with your deletion request as the closing payout, also below the minimum payout amount; **Now** is greyed out until then. The confirmation names the amount paid out.
- **A payout in progress** — a yellow box names it, and the button stays locked until the payout has completed.
- **Incomplete tax details** — a yellow box links to the tax details in the developer verification: the closing payout needs them for its credit note, and the button stays locked until they are complete.
- **No payout method or no verified developer identity** — a yellow box links to the payout settings (**Extensions › Payouts**) or the verification, and the button stays locked until the balance can be paid out. If it cannot be paid out, write to [hey@lumio.vision](mailto:hey@lumio.vision).

The box needs the channel you have selected to let you manage developer payouts. Without it the section shows no box, and the delete button answers with **You still have a developer balance with Lumio or a payout in progress. You can delete your profile once it has been paid out. If it cannot be paid out, for example because it is below the minimum payout amount, write to us at hey@lumio.vision.** The address in the message opens your mail client.

During the waiting period the deletion page shows your developer balance too. Revenue that arrives after the deletion request is paid out with **Request closing payout**, also below the minimum. While a payout is in progress the page says that the deletion runs once it has completed: when the waiting period ends, the deletion waits for the payout to finish. Your payout records are kept for 8 years after the year of the payout, as tax law requires, also after the profile is deleted.

During the waiting period, signing in leads to `/account/deletion`, which names the date. Hold **Cancel deletion** for two seconds to keep your profile (letting go early cancels; a plain button with animations Off), or sign out and leave it scheduled. Cancelling works until the date; once it has passed the deletion is already running and can no longer be cancelled. A reminder mail is sent seven days before the end of a 30-day period and one day before the end of a 7-day period. For the privacy policy and retention details, see [Legal pages](/user-guide/legal-pages).

---

## User Guide / Overlays

Source: https://docs.lumio.vision/user-guide/overlays

# Overlays

Overlays are the visual layers you composite on top of your stream in OBS (or any browser-source-capable encoder). Lumio ships a visual, layer-based editor for building them, a live preview that mirrors your canvas, and stable URLs you can drop into OBS as browser sources.

This guide walks you through creating, editing, and shipping overlays end-to-end.

## Where to find it

Open the dashboard sidebar and go to **Stream → Overlays** (`/dashboard/overlays`). You'll see a grid of every overlay on your account with its canvas resolution, plus a **Search Overlays** box and folders for grouping. The **New Overlay** button in the top right also shows how many overlays you have against your plan limit (for example `New Overlay 2/5`).

Each overlay card has an **Edit** button, a **Copy Link** button, and an overflow menu with **Insert Overlay**, **Rename**, **Move overlay**, **Overlay access**, **Revoke token**, and **Delete**.

## Quick start

1. Go to **Stream → Overlays** and click **New Overlay**.
2. Give the overlay a name (e.g. `Main Scene`), pick a resolution preset (1920×1080 is the default), and choose a background - **Transparent** is what you want for OBS in almost every case.
3. Click **Create**. Lumio immediately offers the finished browser-source URL - copy it right there.
4. Click **Edit** to open the visual editor.
5. Click the **+** button (bottom-left of the canvas) and pick a widget to add your first layer.
6. Drag it on the canvas, tune it in the right-hand properties panel, then press **Ctrl/Cmd + S** (or the **Save** button) to persist.
7. Paste the copied URL into OBS as a **Browser Source**.

### Resolution presets

**1920×1080 (Landscape)**, **1080×1920 (Portrait / TikTok)**, **1280×720 (720p)**, **2560×1440 (1440p)**, or **Custom** with your own width and height. The background is either **Transparent** or a custom colour.

## Folders

At the root of the overlays grid you can create folders to group overlays:

- **Create folder** makes a new folder; folder names must be unique.
- Open a folder to see the overlays inside it. Only root shows folders.
- The folder's own menu offers **Rename folder** and **Delete folder** - deleting a folder moves the overlays inside it back to root, it does not delete them.
- **Move overlay** on an overlay card lets you pick a target folder (or **Root**).

The search box filters both overlays and, at root, folders.

## The editor in depth

The editor fills the full window, follows your light or dark theme, and has four regions:

- **Toolbar (top):** panel toggles, **Snap**, zoom out / zoom in with the current zoom level, **Save** (a dot marks unsaved changes) and close. `Ctrl/Cmd + S` saves; `Ctrl/Cmd + \` or the fullscreen button hides both side panels.
- **Layer panel (left):** every layer on the canvas, stacked top-down in render order. Click a layer to select it. Each row has toggles for **visible** (eye icon) and **locked** (padlock). Drag rows to reorder, or focus a row's grip and use Space and the arrow keys. Locked layers can't be moved or resized on the canvas - handy once a layer is positioned correctly.
- **Canvas (center):** the WYSIWYG surface. Snap-to-grid helps with alignment. Use the zoom buttons in the toolbar; when the zoomed canvas is larger than the window, scroll to reach the rest. The canvas is always rendered at the overlay's native resolution, so what you see maps 1:1 to what OBS will see.
- **Properties panel (right):** every setting for the selected layer - position, size, rotation, opacity, and widget-specific options (text content, alert templates, event filters, Spotify theme, etc.).

On a narrow window (below 768 px) both side panels start closed and open over the canvas; use **Layers** and **Properties** in the toolbar to show them.

Below the canvas you have:

- A **+** button that opens the **Widget Picker**.
- A **Test Events** panel for firing synthetic follows, subs, cheers, etc. into the preview without waiting for a real viewer.
- A **Live preview** indicator plus an **Open preview** button that launches the full-resolution preview in a new tab.

### Layer types

The widget picker shows all widget extensions installed on the account. Built-in system widgets are pre-installed; additional widgets can be found in the Extension Store.

| Built-in Widget | What it does |
|---|---|
| Alert Box | Animated popups for follows/subs/cheers/raids/redemptions. |
| Chat Box | Live chat feed with platform badges. |
| Event List | Scrolling list of recent follows, subs, cheers, raids, etc. Filter per-platform. |
| Spotify Now Playing | Now-playing card (cover art, title, artist, progress). Requires a Spotify connection. |
| Text | Static or dynamic labels - stream title, clock, custom string. |
| Image | Upload or link to an image/PNG/GIF - logos, frames, decorations. |
| Timer | Countdown or stopwatch. Great for intermission screens and sub-goals. |
| Browser Source | Headless layer that talks to the OBS Browser Source API for scene control. |

The number of overlays and of standalone widget instances is limited by plan (overlays - Free: 1, Pro: 5; widgets - Free: 3, Pro: 20). Lumio admins can override these limits per account.

### Editing a layer

Select a layer and use the properties panel:

- **Position (x/y)** and **size (width/height)** in pixels, relative to the canvas origin.
- **Rotation** in degrees.
- **Opacity** from 0 (invisible) to 1 (fully opaque).
- **Widget settings** - specific to the type (e.g. Alerts has templates per event type; Event List has platform filters and direction).

Tips:

- Click and drag directly on the canvas for fast positioning.
- Shift-drag constrains movement.
- Hit **Delete** with a layer selected to remove it.
- Unsaved changes are marked in the toolbar; closing the editor or refreshing prompts you to **Save & Leave** or **Discard**.

### Preview: live vs production

Every overlay has two URLs:

| URL | What it's for |
|---|---|
| `/overlay/{key}/preview` | Live preview. Mirrors the editor canvas in real time - any change you make in the editor appears instantly. Safe to use during editing only. |
| `/overlay/{key}?token=…` | Production. Stable, cached, token-authenticated. This is what you paste into OBS. |

The editor opens the preview in a hidden iframe so you see changes instantly without switching windows. Use **Open preview** in the bottom bar to pop it out into its own tab (useful for a second monitor while editing).

### The overlay token

The production URL carries the overlay's **own** access token - you do **not** create a popout token for it, and you never assemble the URL by hand. **Copy Link** on the overlay card (or **Copy URL** in the Insert Overlay dialog) hands you the complete, ready-to-paste URL.

Two things follow from that:

1. Anyone holding that URL can render your overlay. Treat it like a password - never show it on stream.
2. **Revoke token** (in the overlay's menu) invalidates the current URL immediately. The confirmation says it plainly: your OBS browser source stops working until you click **Copy Link** again and update OBS. Use it if a laptop is lost or a collaborator leaves.

Popout tokens are a different credential entirely, used for the `/popout/*` dashboard views - see [Tokens](./tokens.md).

## Browser source setup

1. In **Stream → Overlays**, open the overlay's menu and click **Insert Overlay**. The dialog shows the exact canvas size and two ways to get the overlay into OBS.
2. Either **drag and drop** the entry straight into OBS, or click **Copy URL** and paste it into a new browser source.
3. In OBS: **Sources > + > Browser**. Paste the URL.
4. Set **Width** and **Height** to match the overlay's canvas (e.g. 1920 and 1080).
5. Leave **Custom CSS** empty unless you know you need it.
6. Enable **Control audio via OBS** and **Shutdown source when not visible**, as the dialog recommends.
7. Click **OK**. The overlay should render against a transparent background over your scene.

If nothing shows up: right-click the source > **Interact** and check for errors - usually a revoked token, meaning you need to copy the URL again.

## Sharing an overlay temporarily

The Insert Overlay dialog also has a **Share with Others** section for handing an overlay to a collaborator or a backup streaming PC without giving away your permanent URL:

- Pick an expiry - **1h**, **3h**, **6h**, **12h**, or **24h** - and click **Create Shared Link**. The dialog shows exactly when the link will expire.
- **Active Links** lists every link you created with its **Active** / **Expired** status, when it was created, and when it expires. You can copy it, extend it, or revoke it.

## Per-overlay access

**Overlay access** in the overlay's menu controls who on your account can reach that specific overlay:

- Search for a person and grant them **Viewer** or **Editor**, or set **No access**.
- Channel admins always have access.
- **No access** blocks a user even if their channel-wide role would otherwise let them in; **Viewer** / **Editor** grants access to users who have no channel role at all.

Managing this needs the per-overlay access permissions - `overlays:access-read` (view access entries and candidates), `overlays:access-grant` (set a user's access), and `overlays:access-revoke` (remove a user's access) - which Owner and Administrator hold by default.

## Common scenarios

**"I want the same overlay on two scenes."** Add the browser source to both scenes; OBS will share the same URL. Or duplicate the source. Both are fine; no need to create a second overlay.

**"I want different overlays per scene."** Create one overlay per scene (e.g. `Main`, `BRB`, `Ending`) and add each as a separate browser source to its scene.

**"I want to share an overlay with my editor."** Open **Insert Overlay → Share with Others** and create a shared link with the shortest expiry that covers the session. Revoke it from **Active Links** when they're done. For a permanent collaborator on your account, use **Overlay access** and give them **Editor** on just that overlay instead.

**"I want to test alerts before going live."** Open the editor, add an Alerts layer, and use the **Test Events** panel in the bottom bar to fire a fake follow/sub/cheer. The preview animates the alert so you can tune timing, text, and sound before a real viewer triggers it.

**"My overlay needs to portrait for TikTok."** Pick the **1080×1920 (Portrait / TikTok)** preset when creating the overlay.

## Permissions

| Action | Permission |
|---|---|
| See the overlays list and open the editor | `overlays:read` |
| Create a new overlay | `overlays:create` |
| Edit layers, save changes, manage folders | `overlays:edit` |
| Delete an overlay | `overlays:delete` |
| View per-overlay access entries and candidates | `overlays:access-read` |
| Grant a user per-overlay access | `overlays:access-grant` |
| Revoke a user's per-overlay access | `overlays:access-revoke` |

The UI hides buttons you don't have permission for, and the server rejects the request anyway - both sides enforce the same permissions.

## Tips & best practices

- **Design at your output resolution.** If you stream at 1920×1080, build the overlay at 1920×1080 - not 1280×720 scaled up. Browser sources don't resample gracefully.
- **Use the Transparent background** unless you have a specific reason not to. OBS composites the overlay on top of your scene.
- **Lock layers once positioned.** Prevents accidental drag during a quick edit.
- **Name your layers.** `alerts-follow`, `timer-countdown`, `spotify-top-right` - future-you will thank you when an overlay has 20 layers.
- **Test with the test events panel** before going live. Catches z-ordering and animation bugs that won't surface until a real viewer triggers them.
- **Use folders once you pass a handful of overlays** - one per scene set (`Live`, `BRB`, `Events`) keeps the grid readable.
- **Use a shared link, not your real URL,** whenever someone else needs the overlay temporarily.

## Troubleshooting

**Empty/blank overlay in OBS.** Usually the overlay token was revoked. Open the URL in a regular browser tab first - you should see the overlay render. If not, click **Copy Link** on the overlay card for a fresh URL and update OBS.

**Alerts never fire in production.** Check that the Alerts layer is visible (eye icon) and not locked under another layer. Then verify on **Stream → Events** that Lumio is actually receiving events from your platform (if the event list is empty, the platform connection is the problem, not the overlay).

**Preview shows changes but OBS doesn't update.** OBS aggressively caches browser sources. Right-click the source > **Refresh cache of current page**, or right-click and **Properties > OK** to force a reload. Enabling **Refresh browser when scene becomes active** prevents this going forward.

**"403 - Access token required" error.** You loaded `/overlay/{key}` without the `?token=…` part. Use the full URL from **Copy Link** rather than typing the path by hand.

**Layer moves off-canvas and I can't grab it.** Select it in the layer panel (left) and reset x/y in the properties panel.

**Save button stays disabled.** Nothing to save - the editor only enables Save when there are unsaved changes (dirty state).

**Unsaved changes dialog keeps appearing.** Click **Save & Leave** if you want to keep your edits, or **Discard** to drop them. Closing the browser tab with unsaved changes triggers the browser's native "leave?" prompt too.

## Related docs

- [Tokens](/user-guide/tokens) - generating and managing popout tokens for OBS.
- [Events](/user-guide/events) - the event stream that feeds the Event List and Alerts widgets.
- [Music](/user-guide/music) - the Spotify integration that powers the Spotify widget.
- [Channel Status](/user-guide/channel-status) - what controls "am I live" detection.
- [Roles and Permissions](/user-guide/roles-and-permissions) - how `overlays:*` permissions interact with roles.

---

## User Guide / Connections

Source: https://docs.lumio.vision/user-guide/connections

# Connections

Connections are the **Connections** group on the channel side of the [settings window](/user-guide/settings). Open **Settings** in the dashboard sidebar, select the channel at the top left, and choose an area under **Connections**. The short link `/dashboard/settings/channel/connections` opens the Overview; each platform has its own area, for example `/dashboard/settings/channel/connections/twitch`. The window opens over the page you are on. Areas appear only for the platforms, features and permissions available to your account. Existing bookmarks to the former Connections hub redirect permanently to the matching short link and keep their query.

## Find your connection

| Area | Short link | What you can manage |
|-----|---------|---------------------|
| Overview | `/dashboard/settings/channel/connections` | Connections needing attention, platform status and connected services |
| Twitch, YouTube, Kick | `/dashboard/settings/channel/connections/twitch`, `…/youtube`, `…/kick` | The channel, its permissions, its chat bot and its OAuth app |
| Spotify | `/dashboard/settings/channel/connections/spotify` | Music connection, permissions and your Spotify app |
| Discord | `/dashboard/settings/channel/connections/discord` | Servers using the Lumio bot |
| Services | `/dashboard/settings/channel/connections/services` | OBS, StreamElements and Shopify |

The Overview shows **Needs attention** when a channel or bot needs reconnecting, a required permission is missing, an own app cannot be read, a Discord server needs attention or Spotify authorization is nearing its end. Choose the action on that row to fix it or to open the platform's area. In the window's list, the Overview entry counts every outstanding item and each platform entry counts its own: red when something is disconnected or broken, amber for a warning or a missing permission. While anything needs attention, **Settings** in the dashboard sidebar carries a dot, and **Reconnect** in a dashboard alert opens the platform's area in the window. Login connections used to sign in to Lumio remain under [Security → Sign-in](/user-guide/account-security).

Above the table a legend says what the columns Channel, Bot, App and Permissions mean. The table lists each platform with its channel, bot, app and permission state and the action its state needs. It fits the window and never scrolls sideways. Where the space is tighter, it becomes more compact: the YouTube badge shows only its flask icon, and **Open** and **Rejoin all bots** show only their icons, with the full name on hover and for screen readers. Where the space is narrower still, as on a phone, every platform becomes a card with the same states as labelled lines and the action button underneath. A value too long for its column ends in **…**; hover over it to see the full text.

You can open the group if at least one area is available to you. A platform's channel sections need `connections:read` and the Connections feature; its chat bot needs `bot-connections:read` and the Bots feature. OBS needs `obs:read`, StreamElements needs `se-tokens:read`, and Shopify needs `connections:read`, each with its corresponding feature (Shopify: the Shopify integration on your plan). A direct link to an area you cannot access shows no access instead of its data.

Under **What Lumio may do**, every permission the platform granted is listed with one sentence on what Lumio uses it for. A missing permission is marked **missing**. Before a Twitch or Kick channel is connected, **What Lumio can do with it** sums up what connecting gives you instead. The channel connection reads the chat, events and moderation actions; writing and moderating in the Lumio chat use each member's own Twitch, Kick or Google sign-in. The connections page says so under **What Lumio may do** (or under **What Lumio can do with it** before connecting), and the connect dialog points it out too.

For Twitch, **AutoMod held messages** says Lumio can show messages held for review in the chat; allowing and denying use the acting member's own Twitch sign-in. **Blocked terms and AutoMod level** says Lumio requests these rights together so you need only one reconnect, but does not use them yet. Manage terms and the level on twitch.tv. If the channel was connected before these rights were requested, use **Grant permission** to reconnect it once.

## Connect a channel

1. Open the platform's area and check the **Channel** and **App** sections. Twitch and Kick normally use Lumio's app. YouTube and Spotify require your account's own OAuth app.
2. If **App** asks for setup, select **Set up app** and finish the guided steps below. Your client ID and secret are stored encrypted for this Lumio account.
3. Select **Connect** in the Channel section. Review the permissions in the dialog, then authorize on the platform's site.
4. You return to the same platform area. A toast reports the result and the channel row shows its connection state.

While YouTube or Spotify is not connected, its area shows these as two steps. Step 1 states whether an own app is stored:

- **No app stored:** Step 1 offers **Set up now**. **Connect** in step 2 stays disabled and shows **Step 1 first**.
- **App stored:** Step 1 is ticked as **Own … app set up** and shows the client ID's last four characters and the date it was saved. **Change** opens the guide to replace an app that does not fit. **Connect** is enabled. Removing the app is available in the App section after connecting.
- **Stored app can no longer be read:** Step 1 is highlighted as a warning with **Re-enter**. **Connect** stays disabled until you have entered the keys again.

A channel reconnect must authorize the same platform account. If you sign in as a different one, Lumio keeps the existing channel and shows which account is required. When a required scope is missing, **Grant permission** starts the same connect flow. You do not need to disconnect first. YouTube's optional Analytics revenue scope can be declined while the channel remains connected; it never creates a standing missing-permission warning. Your personal Twitch sign-in can also lack a right Lumio asks for, such as `moderator:manage:automod` for Allow and Deny. If you hold an affected chat permission, an amber **Twitch sign-in needs a new permission** notice in Chat and the dashboard offers **Sign in with Twitch again**; the Chat page also shows it above the input. The notice does not appear when Lumio does not know the old grant's scopes or in a popout, and a disconnected sign-in shows its disconnect notice instead. Members with `history:revenue-read` can see YouTube amounts in [Stream History](/features/stream-history#revenue-and-currency).

### Set up your own Spotify app

The Spotify area opens a five-step full-screen guide. Each step shows where to work in Spotify's developer dashboard:

1. **Account & Premium:** check that the Spotify account you intend to connect has Premium.
2. **Create the app:** register Lumio's callback address and select the Web API and Web Playback SDK.
3. **Allow your account:** add the connecting account's email under **User Management** while the app is in Development Mode. Spotify allows up to five users there. If the account is missing, Lumio saves no connection and its message points you to this step.
4. **Copy the keys:** copy the client ID and client secret from the app.
5. **Enter the keys:** save them in Lumio, then connect with the same Spotify account.

Spotify authorization ends **180 days after consent**, even if access tokens refresh in between. The Spotify area shows the authorization end date; the Overview asks you to reconnect during the last 14 days. **Reconnect** starts a new 180-day period and keeps your app and keys.

### Set up your own YouTube app

The YouTube area opens a six-step full-screen guide for a Google Cloud web application:

1. **Project & API:** create a project, enable YouTube Data API v3 and, if you want YouTube revenue figures, enable YouTube Analytics API.
2. **Create the app:** configure Google Auth Platform with an external audience.
3. **Branding:** enter the website, privacy and terms addresses shown by Lumio.
4. **Scopes & publish:** register the two required YouTube scopes and the optional Analytics monetary scope, then move the app to **In production**. An app left in Google's Testing status can issue refresh tokens that end after seven days.
5. **OAuth client:** create a web client, register the callback address and download its client JSON.
6. **Enter the keys:** drop the JSON file into Lumio. Lumio checks the web-client type and callback address in your browser before saving the ID and secret; manual entry is also available.

The callback address and scopes shown in each guide come from the current connection settings. Copy those values into the provider console exactly. See [OAuth provider setup](/getting-started/oauth-setup) for provider details.

On a phone, each guide keeps **Back** and the step's button in one bar at the bottom, long addresses wrap instead of running off the screen, and the console sketch opens with **Show sketch**.

Twitch asks for `channel:manage:raids` so a viewer with the Lumio `chat:raid` permission can cancel a running raid from the card above chat, including in a popout. Lumio does not start raids. The connection explains this under **Cancel running raids**.

## Reconnect or disconnect

A short-lived **access-token expiry** is informational because Lumio refreshes access tokens automatically. A **Reconnect required** state means the provider has rejected the grant. Reconnect from the relevant platform area. For Google Testing and Spotify's 180-day limit, the area can explain the specific cause.

Open the Channel row's menu and choose **Disconnect** to see what will be removed. Confirming stops that platform's worker and removes the connection with its tokens. Disconnecting YouTube also removes its associated revenue data, so only YouTube's dialog lists something under **Will be deleted**; Twitch, Kick and Spotify list only what stays. Your channel's data stays: chatter profiles, moderator notes, the moderation and AutoMod logs, chat history and events remain and are deleted only when their retention period ends or when you [dissolve the channel](./channel-settings.md#danger-zone--dissolve-the-channel). Stream reports have no retention period: they stay until you dissolve the channel. If you connect the platform again, you see them again. Your own OAuth app and its saved credentials remain, so you can connect again. Deleting an own app can also disconnect a channel that depends on those credentials.

## Chat bots and Discord

The **Chat bot** section on each Twitch, YouTube and Kick area shows whether the bot is in chat, paused, offline or disconnected. You can pause or resume it, ask it to re-enter chat, and connect your own bot identity when that feature is available. **Re-enter chat** asks a working bot to join again; **Reconnect bot** renews an OAuth grant. Use a bot account distinct from the channel account. Disconnecting an own bot returns the platform to its Lumio bot where available. Bot actions require `bot-connections:create`; removing an own bot requires `bot-connections:delete`.

In the [Discord area](/features/bot-connections#discord-servers), **Add server** invites the Lumio bot. You need **Manage Server** in Discord. Each linked server shows **Connected**, **Bot removed** or **Permissions missing**. A server with live notifications switched on also names the channel they post to. **Reconnect** repeats the verified invite; **Disconnect** removes the server mapping and its settings and makes the bot leave. Discord sign-in belongs under **Security → Sign-in** and cannot be assigned as a channel connection.

## Services

The **Services** area shows OBS and StreamElements independently, according to your permissions and plan. OBS can be configured for local or remote WebSocket access; **Test** checks the connection and reports the result on the row. StreamElements holds encrypted tokens for tip ingestion, with a platform and optional label for each token. Streamer.bot appears as later-service information rather than a setup control.

### Shopify

Lumio receives your Shopify store's orders as events. You cannot type a store address into Lumio: the connection always starts in your Shopify admin.

1. In **Services › Shopify**, select **Shopify App Store** (when the server has no App Store listing yet, the row says so) and install Lumio on your store.
2. In your Shopify admin, open **Apps › Lumio** and select **Connect Lumio account**. Shopify opens a Lumio tab.
3. The Lumio tab names the store by its `myshopify.com` address and shows the Lumio account it will go to. The warning above **Confirm connection** uses that address only, not a store display name. Pick another account in the list if needed; accounts where you may not create connections are shown but cannot be picked. Confirm only if you started the connection yourself in your Shopify admin. You need `connections:create`, and Shopify must be part of the account's plan. If you are not signed in, Lumio asks you to sign in first and then shows the same page again.
4. Switch back to Shopify. It asks once more whether the store should be connected to that Lumio account; confirm there to finish.

A link from Shopify is valid for 10 minutes and only once. An expired or used link says so; start again in your Shopify admin. One store belongs to one Lumio account, and one account connects one store; if the store or the account is already taken, the confirm page says so and what to do.

Once connected, the row shows the store name, its `myshopify.com` address and the date it was connected. **Open in Shopify** opens Lumio in your store's Shopify admin. **Expired** means Shopify no longer accepts Lumio's access; open Lumio in your Shopify admin (**Open in Shopify**) and Shopify renews it.

**Buyer name on stream** sets how order events name the buyer: no name (default), initial (`A.`), first name (`Alex`), first name and initial (`Alex M.`), or the buyer's own name (a name the buyer types in the cart for the stream). A name appears only when the buyer agreed in the cart or checkout or typed a name; you set up that block in Shopify (**Open in Shopify › Setup**). For the three real-name forms, Lumio also needs Shopify's approval for protected customer data (level 2). It applies to orders that arrive afterwards. Changing it needs `connections:edit`.

Place **Name on livestream** on the cart page of an Online Store 2.0 theme. Shopify Plus stores can also place Lumio's checkout block. The real-name forms show an unticked checkbox; **Your own name** shows an optional text field. If a buyer uses accelerated checkout without seeing an eligible block, no buyer name reaches Lumio. The embedded Shopify page shows setup steps and the shop's privacy-policy status.

**Order details on stream** has two switches: **Show items** (item name and quantity, on by default) and **Show price** (order total with currency and, with items shown, each item's price; off by default, hidden in streamer mode). Whatever is switched off, Lumio does not store at all. They apply to new orders and need `connections:edit`.

Automations can read `{{event.raw.line_items}}` only when **Show items** was on for that order, and `{{event.raw.total_price}}` only when **Show price** was on. Older events keep the details they had when received.

**Disconnect** (in the row's **⋯** menu, `connections:delete`) asks for confirmation, then stops accepting the orders and deletes Lumio's access. Shopify keeps sending orders until you remove Lumio in your Shopify admin; Lumio discards them unread.

In the **Events** feed an order shows the buyer name (as plain text, never a user card), up to three items (`2× Hoodie`, then `+2 more`) and the total, as far as your settings allow. **Hide name** (the eye icon on an order with a name, `events:edit`) removes the name from that order and from its **Order Paid** event after a confirmation. What was already shown on stream is not recalled. The chat shows the same order line without the action.

## See also

- [Connection architecture](/features/connections)
- [Shopify](/features/shopify)
- [Bot connections](/features/bot-connections)
- [Bot control](/features/bot-control)

---

## User Guide / Channel settings

Source: https://docs.lumio.vision/user-guide/channel-settings

# Channel settings

Channel settings apply to the **active channel** and to every member of it. Your personal settings (profile, appearance, notifications) stay under [Settings](./settings.md).

Open **Settings** at the bottom of the dashboard sidebar and select your channel at the top left of the window. The channel overview opens first; choose an area in the list to its left. A direct short link such as `/dashboard/settings/channel/members` opens that area over the dashboard home. In a narrow window, tap an area in the full-screen list, then use the back control to return to the list. In your personal profile the selector lists all your channels with your role; picking one switches the dashboard to that channel and opens its overview. With no channel, the selector offers **Create channel**.

Members, roles and the audit log are separate areas in the window. They have no sidebar entries of their own. Existing bookmarks to the former channel-settings pages redirect to the matching short links, including query parameters.

| Area | Short link | Who sees it | What you can do |
|---|---|---|---|
| **General** | `/dashboard/settings/channel/general` | Every member | See the channel's name, picture and ID; change the name and picture with `account:edit`. |
| **Members** | `/dashboard/settings/channel/members` | `members:read` | See the members and invitations, invite with `members:create`, change roles with `members:edit`. See [Members](./members.md). |
| **Roles** | `/dashboard/settings/channel/roles` | `roles:read` | See the roles; create and change them with `roles:edit`, delete them with `roles:delete`. See [Roles and permissions](./roles-and-permissions.md). |
| **Revenue assumptions** | `/dashboard/settings/channel/history` | `history:revenue-read`, with stream history on your plan | Read the revenue assumptions; change them with `history:revenue-edit`. |
| **Bots** | `/dashboard/settings/channel/bots` | `chat-bots:read` | See automatically recognised bots and your channel's bot list; add or remove entries with `chat-bots:edit`. |
| **Keywords** | `/dashboard/settings/channel/keywords` | `history:read`, with stream history on your plan | See and test tracked keywords; add, change or remove them with `history:keywords-edit`. |
| **Audit log** | `/dashboard/settings/channel/audit-log` | `audit-log:read` | Read and export the channel's audit log. See [Audit log](./audit-log.md). |
| **Danger zone** | `/dashboard/settings/channel/danger` | The channel owner (`account:delete`); while the channel waits to be dissolved, every member | Dissolve the channel now, in 7 days or in 30 days, or cancel a scheduled dissolution. |

Each area has its own address, and a link to an area you may not open shows **No access**. While the channel waits to be dissolved, the channel list shows **Danger zone**; keys, tokens and billing remain locked.

## Header

The channel overview shows the channel picture and name, and chips for:

- the channel's plan;
- the connected platforms (with `connections:read`; links to **Connections**);
- the number of members (with `members:read`; links to the **Members** area);
- your role in the channel.

It also shows the **Channel ID** with a copy button; after copying, the button shows a green check for a moment. In [Streamer Mode](./streamer-mode.md) the ID is covered with dots in the shape of the ID, the header shows a **Streamer mode** chip, and a line says that copying still works; the eye reveals the ID. On narrow screens the ID moves onto its own line and a long ID is shortened in the middle; copying always copies the full ID. **Go to connections** opens the connections page when you may read it.

## Name and picture

The channel's name and picture appear in the account switcher, the header above, **Settings → Profile → My channels**, the channel chips under **Security → Sign-in**, member lists and mails. When they come from a platform, that platform's icon sits as a small badge on the picture in the channel overview, in this area and under **My channels**.

The **Name & picture** area shows one card, built like the profile card in [Settings → Profile](./settings.md): the picture, the name and where they come from (for example *Twitch · @cruex*, or *Own details*). Changing them needs `account:edit` (owner and administrator by default) and a signed-in browser session, not an API key or a popout token. Without `account:edit` the card is read only: it shows the source without a choice and says who may change it.

Choose under **Name & picture from**. The list shows each of the channel's Twitch, YouTube and Kick connections with its platform icon (for example *Twitch · cruex*); **Own details** - *Set name and picture yourself* - sits below a divider. The connections are listed for members who may also read the connections (`connections:read`); otherwise the list shows the current source and **Own details** only.

- **A connected channel** - one of the channel's Twitch, YouTube or Kick connections (Spotify cannot be chosen). The name is that channel's name on the platform, the picture its profile picture there. Both follow the platform: they are refreshed when you connect or reconnect and when Lumio starts. If the platform picture cannot be shown, the first letter of the name appears instead.
- **Your own details** - a name you type and, optionally, a picture you upload. When you switch to your own details, the current name is kept as a starting point and the picture starts as the first letter of the name.
  - The name needs 2 to 50 characters; spaces at the start and end are removed, and invisible or control characters are not allowed.
  - The picture is a PNG, JPEG or WebP file of at most 5 MB and 16 megapixels. Lumio re-encodes it and removes all metadata (such as location). You can upload up to 10 pictures per hour. Remove the picture to show the first letter of the name again.

  With own details the card adds two rows: **Channel name** with a field and **Save** (Enter saves too; a name outside the rules shows why under the label), and **Channel picture** with **Upload picture** and, once there is a picture, **Remove**. **Upload picture** opens the same dialog as the profile picture: drop a file or choose one (a file of the wrong type or over 5 MB is refused right there), then crop it round. Drag the picture or use the arrow keys to move it, the slider, the mouse wheel or + and − to zoom, and **Rotate** to turn it by 90°. Three previews show the result; **Apply** uploads it.

Switching back to a connected channel asks first and deletes an uploaded picture. If you disconnect the connection that supplies the name and picture, the channel switches to your own details with that channel's last name and the first letter as picture, and the owner gets a notification that links here. New channels start with your own details.

Every change is recorded in the [audit log](./audit-log.md) as `account:identity_changed`. While the channel waits to be dissolved, nothing here can be changed.

## History · revenue assumptions

Lumio estimates the revenue of each stream in the [stream history](./stream-history.md) from its events and the values in this area. The Twitch and Kick sub prices, Prime, Bits and KICKs appear as **fixed USD values with a lock and source**. They cannot be edited here and are converted at the rate of the stream day. KICKs carry a warning because their $0.01 value is not published by Kick.

The YouTube section also shows the channel's Analytics revenue status when YouTube is connected: **on** after the Partner Program check succeeds, **unlocked** while that check is pending, or a hint to reconnect with the revenue permission, join the Partner Program, or enable the YouTube Analytics API in your Google app. The hints appear here and on a report's revenue card, not in general connection notices. You need `history:revenue-read` to see this area and YouTube's figures; every member with that permission can see them. YouTube values normally arrive 2–3 days after the stream. Until then the report shows the Lumio estimate. See [YouTube Analytics API setup](/getting-started/oauth-setup#youtube-analytics-api).

| Locked value | USD amount |
|---|---:|
| Twitch Tier 1 / 2 / 3 sub (also used for gifts) | $4.99 / $9.99 / $24.99 |
| Twitch Prime | $4.99 |
| Twitch Bit | $0.01 |
| Kick sub (also used for gifts) | $4.99 |
| Kick KICK | $0.01 (check against your payout) |

| Row | Fields |
|---|---|
| Twitch · your share | 50 % standard, 60 % Plus Program, 70 % legacy contract, or any value |
| Twitch · ads | CPM (empty = no amount), ad share, ad-free viewers |
| Kick · subs and gifts | Your share; the USD $4.99 sub value is locked |
| Kick · ads | CPM (empty = no amount), ad share, ad-free viewers; reconnect Kick if `ads:read` is missing |
| YouTube · ads | CPM (empty = no amount), mid-rolls per hour (empty = no ad line), ad share and ad-free viewers; pre-rolls are excluded |
| YouTube · Super Chats, Super Stickers and memberships | A separate creator share for each, 70 % by default |
| YouTube · membership levels | Up to six level names with a price in the payout currency; drag to reorder or use the keyboard |
| Payout currency | Currency for the editable money fields; fixed USD values are converted at the stream-day ECB rate |

The level list shows how often Lumio saw each name in stored YouTube membership events. Names seen but not yet priced appear as one-click suggestions; **Add level** lets you enter a name manually. A membership with an unknown or unpriced level uses the cheapest entered level and is marked as an assumption in the report. Without a level price, memberships remain unpriced. Membership milestones count as paid months.

**Save** writes the editable assumptions; **Reset** discards your unsaved changes. Both stay off until you change something. The change applies to new and past reports and is recorded in the [audit log](./audit-log.md) as `account:history_revenue_settings_updated`. Empty ad CPM fields leave their ad lines without an amount. An empty YouTube mid-roll rate leaves out the YouTube ad line entirely.

Without `history:revenue-edit` the tab is read only: a note at the top says who may change the values, every field is locked, and there are no level suggestions, reorder handles or save bar.

In Streamer Mode the money fields are covered until you reveal them.

## Bots

The **Bots** area shows bots Lumio recognises automatically from platform bot badges, its curated list and your connected Twitch or Kick bot account. It also shows the bot accounts your channel has marked. The account list supports Twitch, Kick and YouTube; entries are tied to a stable platform user ID or YouTube channel ID, never just a display name. The [Viewer List](./viewer-list.md) puts these accounts in **Bots** even when they are moderators or VIPs. [Stream History](./stream-history.md) leaves their messages out of chat totals and top lists, but still shows their link and keyword posts with a bot label.

With `chat-bots:edit`, choose a platform and enter a name or `@handle` to mark an account, or use the action on a chat user's card. Lumio looks up the platform account before saving; a name that cannot be resolved adds nothing. An existing entry is not duplicated. Remove a mark from the account list when you no longer want it. Automatically recognised bots are read only. Without edit permission, you can inspect both lists but cannot change them.

Marking a bot starts a background recalculation of retained stream sessions whose chat logs are still complete. Their bot-filtered figures can decrease. Removing a mark stops that mark from classifying future messages; badge, curated-list or own-connection recognition may still apply. Already recalculated session figures are not restored. Real list changes appear in the [audit log](./audit-log.md) as `account:bot_list_updated`.

## Keywords

The **Keywords** area tracks up to **50** account-wide chat terms for [Stream History → Chat insights](./stream-history.md). Each row shows the term, match mode, case setting and its count in the latest finalized stream when known. Choose **Whole word**, **Contains** or **Regex**. Whole word needs word boundaries on both sides; Contains finds the text anywhere; Regex uses Rust regex syntax. Matching ignores case by default, and you can change that per entry. A whole-word or contains term may have at most 100 characters; a regex may have at most 200, may not match empty text and must compile within the 1 MiB size limit. Regex look-around and backreferences are unavailable.

**Test pattern** checks a term against a sample of up to 500 characters using the same server matcher without saving it. It shows every matching span or the validation error and stays available with read-only access. The test permits 30 calls per minute. Saving, changing match or case, and removing an entry require `history:keywords-edit`; `history:read` is enough to open the tab and test. A duplicate term with the same mode is not added twice.

One message counts once for each keyword it matches, even when the text appears more than once. Bot posts count and are labelled. When a leading `#ad` or similar token matches a tracked keyword, the keyword wins and that message is not also counted as a command. A list change recounts finalized sessions in the background **only while their full chat log is retained**; older sessions without a complete log keep their frozen figures. Real changes appear in the [audit log](./audit-log.md) as `account:history_keywords_updated`.

## Danger zone · dissolve the channel

Only the channel owner sees this area (while the channel waits to be dissolved, every member sees it, see below). Dissolving deletes the channel in Lumio with its overlays, automations and memberships, and with them the channel's chat history, events, the stream reports in [Stream History](./stream-history.md), chatter profiles, moderator notes and the moderation and AutoMod logs. The channel's platform connections (Twitch, YouTube, Kick, Discord, Spotify) are deleted with their access tokens; for YouTube, Lumio also revokes its Google access. Your Lumio sign-in with Twitch, YouTube or Kick belongs to your profile, not to the channel, and stays until you [delete your profile](./privacy-and-export.md#delete-your-profile). Your accounts at those platforms themselves are not affected. With **In 7 days** or **In 30 days**, nothing is deleted until the date; until then you can cancel.

Dissolving works like deleting your profile:

1. **Choose when** on one of three cards: **Now** (final, no way back), **In 7 days** or **In 30 days**. Each card names its date; **In 30 days** is preselected. The sentence under the cards says what the choice means.
2. **Type the channel name** exactly. A check mark shows when it matches.
3. **Hold the button for 2 seconds.** It is named after your choice: **Dissolve permanently now**, **Dissolve in 7 days** or **Dissolve in 30 days**. Letting go early cancels. With **Animations in Lumio** set to Off there is no holding; the button works with a click once the name matches.
4. **Sign in again** in the **Is it really you?** dialog, as described in [Account security](./account-security.md). The dialog repeats the date you chose, or that the channel is dissolved right away. If you confirmed in the last 10 minutes, this step is skipped.

With **Now** the channel is dissolved and the dashboard opens without a channel selected.

- While a paid plan runs, the button is locked. The note names the date the paid period ends; cancel the plan first under [Subscription & billing](./billing.md).
- Dissolving works only in a signed-in browser session, not with an API key or a popout token.

### While the channel waits to be dissolved

With **In 7 days** or **In 30 days** the channel is suspended until the date:

- Every member gets a mail naming the channel and the date.
- While the channel is selected, a red banner sits fixed at the top of every dashboard page and the fullscreen editors: **This channel will be dissolved on … Bots, overlays, widgets and API keys are off until then.** It cannot be closed and takes its own space, so nothing lies under it, on phones too. The owner sees **Cancel dissolving ›** in it, which opens this area. Popouts and OBS show no banner; they are switched off.
- The account switcher and **Settings → Account** label the channel **being dissolved**.
- Members can still open their profile, security and developer settings, create or switch to another channel, or leave this one, but they cannot use the channel: its pages show **Channel is being dissolved** with the date instead of their content.
- This tab shows **Will be dissolved on …** to every member. Only the owner gets the button to cancel.
- API keys, service keys, popout links, overlay and widget links and extensions of the channel stop working. They are not deleted; after a cancel they work again.
- Bots leave the channel's chats and Discord servers. Automations, bot modules and incoming platform events stop. No new subscription can be bought.
- You get a reminder mail seven days before the end of a 30-day period and one day before the end of a 7-day period. On the date Lumio dissolves the channel.

The owner can **cancel the dissolution** at any time before the date: hold **Cancel dissolving** on this area for 2 seconds (the banner link leads here). Letting go early cancels; with **Animations in Lumio** set to Off it is a plain button. No new **Is it really you?** check is needed. Everything works again right away, and bots rejoin by themselves. Members are told by mail. If your own profile is scheduled for deletion too, a note asks you to cancel the profile deletion first and links to it. Once the date has passed the dissolution is already running and can no longer be cancelled.

You can also reach this area from **Settings → Account**: the link **Channel settings › Danger zone** next to a channel you own opens it. If that channel is not the active one, Lumio switches to it first.

---

## User Guide / Events

Source: https://docs.lumio.vision/user-guide/events

# Events

Events are the heartbeat of your stream. Every follow, sub, cheer, raid, channel-point
redemption, super chat, tip, and Spotify track change flows through Lumio's event
pipeline in real time. The Dashboard gives you a live feed of what is happening on
every connected platform, and the same stream powers your overlays, automations, and
bot reactions.

Lumio surfaces the same live feed in two places: the dedicated **Events** page in
the sidebar and the `/popout/events` window for OBS and secondary monitors. This
guide covers both, plus filtering and searching, sending test events, the
channel-status indicator, and every supported event type.

## Where to find it

- **Events page** (`/dashboard/events`): a dedicated, full-height feed in the
  sidebar under **Stream → Events**, right below Chat. This is the primary place to
  watch and filter events. It requires the `events:read` permission and the
  `feature:events` plan feature.
- **Popout window** (`/popout/events`): a borderless copy of the same feed for a
  second monitor or OBS browser source.

While Events opens on the dashboard or in a popout, its header, tabs and search bar
keep their places and the feed shows loading rows. A hidden header or footer stays
hidden during loading. Live events that arrive while the first history read is
pending remain in the feed when that read finishes.

Both surfaces share the same feed component, so filters and display settings you pick
carry across them, and each updates automatically as long as the WebSocket is
connected. The Dashboard home does not embed the live feed - it carries the
**Test Events** panel and a compact stream-history overview (the last few
sessions) instead.

## Quick start

1. Open **Stream → Events** in the sidebar for the full feed.
2. Connect at least one streaming platform under **Manage → Connections** so
   events can flow in.
3. Watch the feed. New events push in from the top.
4. If nothing arrives, go to the Dashboard home and click the **Test Events** header
   to expand the panel and fire a fake follow, sub, or cheer to verify your overlays
   and automations.
5. For a dedicated monitor, open the popout with the external-link icon (on the
   Events page or the home panel) or load `/popout/events` directly.

## The event feed

### Panel layout

Every surface shares the same controls:

- **Tab toggle** (`Events` / `Filters`) - switches between the event list and the
  filter controls.
- **Search box** - filter by any text in the event (username, message, reward title,
  track name). Placeholder reads `Search events...`.
- **Settings gear** - on both the **Events** page and the popout, a gear opens the
  display settings (font size, emote size, timestamps, badges, avatars, viewer count,
  and the header/footer toggles) shared with the chat popout. The font-size slider
  scales the row text and its emotes together; the emote-size slider (0.5×–2.0×) tunes
  the emotes on top of that. The General tab also carries a **Region & language**
  block (language, time zone, date format, and time format) - a second entry point to
  the same global user preference as [Dashboard → Settings](/user-guide/preferences),
  marked as applying everywhere you sign in; it is read-only in a token-authenticated
  popout. Both surfaces load older events
  automatically as you scroll (infinite scroll) - there is no page-by-page counter.

Each row shows the platform icon, a colored type badge (e.g. `Follow`, `Sub`, `Bits`,
`Raid`), the username, the timestamp, and an event-specific payload (message,
amount, reward title, etc.). Headline numbers sit as small chips right beside the
type badge rather than under the name - a raid's viewer count (incoming, outgoing and
completed), cheered bits, KICKs sent on Kick (`500 KICKs`), a resub's month count
(`×3`), or an ad break's length in seconds next to its `System` badge. The Bits and KICKs
chips carry a small graphic in front of the amount - the cheer's tier graphic or the Kick
gift's sticker - and cheermotes in a cheer's message (`Cheer100`) render as graphic plus
amount, as in the chat. A KICKs row also names the gift after the sender (`trainwreck_fan ·
Rage Quit`). The avatar keeps its place on the left; when no avatar is shown (avatars turned
off, or an anonymous sender) the graphic takes that spot instead. Without a graphic (a Kick
gift Lumio does not know yet, or an older event) the chip is text only. The graphics
follow the font-size slider everywhere; cheermotes in the message box also follow the
emote-size slider, while the chip graphic and the large graphic in the avatar spot follow
only the font size. Twitch's larger cheermote image is loaded on high-resolution screens
and for large graphics, so they stay sharp. With animations off or your system's
reduced-motion setting on, the graphics show their still image, and where the platform
sent no still image, the plain text instead of an animation. Clicking the **username** - or the small **ⓘ** button
beside it - opens the **User Info Card** (see below). The username click target and
the button appear together and only where a real platform user backs the row (not on
channel-wide events like raids out or hype trains, the anonymous gifter, or Spotify).

The header also shows the total event count - _"No events yet"_, _"1 event total"_,
or _"42 events total"_ - and, while any channel is live, a small viewer-count pill
per online platform.

### Twitch Shared Chat session events

The feed shows **Shared Chat started**, **channel joined**, **channel left** and
**Shared Chat ended** as Twitch events at the time they happened. Start and end
show the host-first channel stack and partner details; join and leave show the
affected channel. A join reconstructed from a later check says **Detected
later**. An unavailable category, viewer or follower value is simply omitted.
Use the **Shared Chat** chip to see these session events, or switch individual
types on and off in the existing **Twitch** filter group. They are on by
default and do not open a chat alert. The same session lines appear in the
chat's **All** and **Twitch** tabs, with start/end details collapsed there.

### Twitch Shared Chat partner events

During a [Twitch Shared Chat](./chat.md#twitch-shared-chat) session, subs, resubs, gift
subs, upgrades, pay-it-forward, raids into a partner and Bits that happen in a **partner**
channel appear in the feed as well. Their name line starts with a **channel chip**: the
partner channel's channel-coloured avatar plus its name in a grey pill (a long name is
shortened with `…`; hover: **"Happened in {channel}'s channel (Shared Chat)"**), so they
never read as your own events. The chip shows in both the full and the compact feed, also
with the type badge or avatars switched off. The stream report's announcement list names
the partner channel next to its avatar the same way.

Partner events use the same filters as your own events of that type and do not count in
your stream history. To hide all of them, switch off **Events from Shared Chat partners**
in the feed's display settings (gear icon, on by default). The four Shared Chat session
events always stay; the switch changes only what the feed shows.

### Real-time updates

The dashboard maintains a WebSocket connection to the API and subscribes to the
`events:{account_id}` and `chat:{account_id}` channels. Events flow through Redis
pub/sub → API → WsServer → browser. When the connection drops, Lumio reconnects
with exponential backoff (1s, 2s, 4s … capped at 30s) and you will see the
`connectionLost` banner briefly.

### Reconnect required

The per-platform stats row in the header (viewers / likes / views) doubles as a
health indicator. If a platform's OAuth connection expires and needs
reconnecting, that platform shows a **reconnect-required error pill** - and it
stays visible even while the channel is offline (a dead connection is exactly
when nothing is live, so the pill must not disappear). This is separate from the
transient `connectionLost` WebSocket notice above. Members who may reconnect
channels (`connections:create`) also get a red entry in the
[connection notices](../features/connections.md#connection-notices) under the header, with a
**Reconnect {platform}** button (e.g. **Reconnect Twitch**) that starts the platform's OAuth flow in place. Otherwise
reconnect from **Account → Profile** or **Connections**; see
[Connections → Reconnect flags](../features/connections.md#reconnect-flags).

### New permissions available

When Lumio starts requesting a scope that an existing connection was granted
without, the connection keeps working but some events cannot arrive until you
reconnect it. The Events page (and the [Chat](./chat.md#new-permissions-available) page) then shows an amber **needs new permissions**
entry in the [connection notices](../features/connections.md#connection-notices) under the header, one per affected platform - for example
_"Reconnect Kick to receive KICKs and channel points."_ Its **Grant {platform} permission** button
starts the same OAuth flow as the Connections page; from a popout window it opens in
a new tab. Nothing needs to be disconnected first. The notice is only shown to members
who may reconnect channels (`connections:create`), and a connection that already needs
a reconnect (above) shows only that entry. See
[Connections → Missing scopes](../features/connections.md#missing-scopes).

### Filtering

Switch to the **Filters** tab to narrow the feed:

- **Platform** - toggle Twitch, YouTube, Kick, Spotify, StreamElements,
  Discord, Shopify, 7TV, Copyright, System. Twitch, YouTube, Kick, and Spotify
  appear when the account has the corresponding channel connection;
  StreamElements appears when a StreamElements token is stored; 7TV appears
  when at least one Twitch, YouTube or Kick channel is connected. Discord,
  Shopify, Copyright, and System do not depend on those connections. If Lumio cannot read a
  connection or token status, its platform remains listed (including
  StreamElements for a moderator without `se-tokens:read`). Turning a platform
  off hides its events from the feed.
- **Type** - fine-grained toggles for every event type that has appeared for your
  account (follower, subscribe, resub, cheer, raid, reward, poll, prediction, hype
  train, superchat, track, tip, and so on).

Filters persist locally, so they stick across reloads. The feed re-queries and the
infinite-scroll list resets to match the filtered result set. Disconnecting a
platform removes its controls from the Filters tab, but does not erase saved
filter choices or older events from the feed history. Those events remain
visible when your saved filters and access settings allow them.

### Search

The search box performs a substring match on the rendered row. Useful examples:

- Type a username to find every action by that viewer.
- Type a reward title to audit channel-point redemptions.
- Type `@yourname` to find messages that tagged you.

### User Info Card

Clicking a username opens the user's card as a **full-page view** over the Events page -
tinted in the platform's colours, with the page behind faintly visible. It is the same card
the chat opens (see [User Info Card](./chat.md#user-info-card)): the header shows the avatar,
name, badges, `@username`, platform ID and an **Open Profile** link; on a wide screen the
profile facts and moderation actions sit in a left column next to the tabs, on a narrow
screen and in the events popout everything stacks into one column. Its tabs:

- **Messages** - the user's recent chat history on that platform. Links in these
  messages are clickable and open through the `External Link` warning (the same one
  the chat feed uses), so nothing leaves Lumio until you confirm; the warning appears on
  top of the card and `Esc` closes only the warning. This works on the Events page and in
  the events popout.
- **Mod Notes** - private notes shared with your moderators (requires `chat:notes`).
- **Moderation History** - bans, timeouts, deletions and treatment changes for this user.
- **Events** - every event that user has triggered (follows, subs, cheers, KICKs,
  redemptions, raids). Cheers and KICKs show their graphic in front of the amount, and
  the emotes in an event's message (for example a resub message's sub emotes, or the
  cheermotes in a cheer) render as images.

The card also shows account-created date, the user's own follower count (Twitch only),
follow status and date, and the user's treatment status. Close it with `X` or `Esc`.
Requires `events:userinfo` (or `chat:userinfo` when opened from the chat view). The chat-only **Highlight** / **Hide** buttons do not appear here.

## Test events

On the [Dashboard home](./dashboard.md#test-events), **Test Event** opens a side sheet;
on a phone it fills the screen. The button appears with `feature:events` and
`events:create`. The same catalog is available in the
[Test-Events popout](./tokens.md#where-popout-tokens-work), including as an OBS dock.

### What it does

Sending broadcasts an event marked `isTest: true` to the account's overlays and
dashboard activity. The activity row carries a **TEST** badge and dashed border.
The Events page and Events popout filter test broadcasts out. Tests are not
stored and do not affect metrics, the live **Now** card, milestones or history;
the activity row disappears after a reload.

### How to fire one

1. Open **Test Event** from the dashboard header.
2. Search the catalog or choose a platform tab; **More** contains other event sources. The catalog lists only sources that are connected, whose features are on and that your role may see — see [which events are offered](./dashboard.md#test-events).
3. Choose **Send** on a row to use its defaults, or expand the row to change values or pick random values before sending.
4. Check the confirmation and **Just sent** list. **Again** repeats a test. The sheet stays open for further sends.

Use this to:

- Verify a new overlay animation before going live.
- Check several overlay alerts without waiting for real audience activity.

## Popout window

Open `/popout/events` (or click the external-link icon on the **Events** page) to get
a borderless, chrome-free event list suitable for a second
monitor, a stream deck browser, or a browser source for your producer view.

Two authentication modes:

1. **Cookie auth** - if you are already logged in to Lumio in the same browser, the
   popout uses your session cookie automatically.
2. **Popout token** - append `?token=YOUR_TOKEN` to the URL
   (e.g. `https://lumio.vision/popout/events?token=lm_pop_…`). Use this when loading
   the popout inside OBS, where cookies are unavailable. Create popout tokens under
   **Settings → Channel → Access → Popout Tokens**, see [Tokens](./tokens.md).

The popout respects the permissions granted to the token - a scoped token may hide
moderation-only event types or the User Info Card.

The [seasonal look](/user-guide/preferences#popouts-and-obs) also shows in this popout; append `&season=off`, `&seasonStrength=subtle` or `&seasonMotion=off` to the URL to change it for this popout only.

### Animations for this view

Open the settings gear and choose **Animations → As global, Reduced, or Off**. The choice affects this view on the dashboard and in its popout, and is stored per browser and per user/account pair. It can only reduce motion further than your [global Animations in Lumio preference](/user-guide/preferences#animations-in-lumio); an unavailable looser choice is disabled. For an OBS popout, append `&motion=reduced` or `&motion=off` (use `?` if it is the first URL parameter) to apply a stricter choice to that URL without saving it. The global preference is read-only in a token popout.

## Where these settings apply

**These settings apply to you on this account.** Events settings are stored in your
browser (there is no server copy) and keyed to the pair *(you, the channel account
you are viewing)*. This covers **both** the event-feed display options and the
**event-feed filter** (the platform and type toggles under the Filters tab): switch
to a second channel account, or sign in as a different team member of the same
account, and they start from defaults — a filter you set while viewing one channel
is not applied to another, and never leaks between team members. You set them once
per browser context (the dashboard, and again in an OBS popout, which is separate).
To reuse them elsewhere, move them deliberately with Export / Import or a preset.

## Save and transfer your settings

Your events display options and event filters are stored in the browser, so they
only exist where you set them - a fresh OBS browser source, a second computer, or
a browser with cleared site data starts from defaults. **Transfer settings** lets
you save them and re-import them anywhere, with no server involved.

Open the **Settings** cog, go to the **Presets** tab, and use the **Export** /
**Import** buttons below the preset cards (the same controls are in the dashboard
and the popout). On a plan without the presets feature there is no Presets tab, so
Export / Import appears at the bottom of the **General** tab instead.

- **Export** - tick the sections you want (grouped *Chat / Events / Music*; your
  Events sections are pre-selected here); sections with nothing saved are greyed
  out. Take them with you by **Copy code** (a single `LS1…` line to send over a
  messenger), **Copy link** (a share link that carries the same code and opens the
  events settings with the import preview directly when clicked on any signed-in
  device - both update live as you change the selection), **Copy JSON**,
  or **Download** a file. Very long links can be wrapped by some messengers - for
  those, use the code or the file.
- **Import** - pick a file, drop it onto the dialog, or paste **a file, an `LS1…`
  code, or a share link** into the one input (detected automatically). A **preview** shows what each
  section will replace before anything is written; **import replaces a section
  wholesale, it does not merge**. The page reloads afterwards.

Event filters record which platforms and event types you show. Newly added event
types are enabled automatically on the next load, so an older file never silently
hides a brand-new event type. Importing something from a newer version of Lumio, an
incomplete code, or anything that is not a valid Lumio settings file or code, is
refused with a clear message.

See the [Multichat guide](./chat.md#save-and-transfer-your-settings) for the full
list of what is and is not included in a settings file.

## Presets

The Events settings panel also has a **Presets** tab - named snapshots of your Events
display and filter settings, saved to your account so you can switch layouts and reuse
them across devices. (Because the Events panel used to be a single column, the Presets
tab is what gives it a tab bar.) **New preset** opens an assistant to choose what to store
and name it; each saved preset card offers **Load**, share, overwrite, rename and delete,
with a quota line showing how many you have used. **Share** copies a code/link for the
preset and can make it visible to your whole account (with the `presets:share` permission);
presets teammates share into your account appear in a **Shared from the channel** section
you can load or save as your own. In a popout you can load a preset but not change or share
one. See the [Setting Presets](../features/setting-presets.md) feature page for details.

## Channel-status indicator

While a channel is live, the Events header shows a small pill per online platform
with that platform's icon and viewer count (and, on YouTube, optional like and
total-view counts you can switch on in the display settings). When every channel
is offline, no pill is shown. The Dashboard home shows the same state as a **LIVE**
badge on each channel card.

The Spotify worker and some event pollers only run while at least one channel is
live (see the [Channel Status](./channel-status.md) guide). This saves API calls
and avoids logging Spotify tracks when you are not streaming. If you need to bring
the Spotify worker up manually, use the **Connect** button on the Music page - it
starts the worker for 30 minutes.

## Supported event types

Event type strings follow the `platform:action` convention (e.g. `twitch:follower`,
`youtube:superchat`). The full set currently recognised:

### Twitch

`twitch:follower`, `twitch:subscribe`, `twitch:resub`, `twitch:prime_upgrade`,
`twitch:gift_upgrade`, `twitch:gift`, `twitch:pay_it_forward`, `twitch:bits_badge`,
`twitch:cheer`, `twitch:raid`, `twitch:raid_out`, `twitch:unraid`,
`twitch:raid_done`, `twitch:reward`, `twitch:reward_status`, `twitch:hype_train`, `twitch:hype_train_end`,
`twitch:poll`, `twitch:poll_end`, `twitch:poll_delete`, `twitch:prediction`,
`twitch:prediction_lock`, `twitch:prediction_end`, `twitch:goal`,
`twitch:goal_end`, `twitch:ad_break`, `twitch:stream_online`,
`twitch:stream_offline`, `twitch:stream_update`.

Twitch also reports `twitch:mod_added`, `twitch:mod_removed`,
`twitch:vip_added` and `twitch:vip_removed`. The feed labels them **New Mod**,
**Mod removed**, **New VIP** and **VIP removed**. In chat they are centred
event rows with the platform icon first when that setting is on: grants use
the role colour, while removals use a grey dashed treatment. The fallback VIP
symbol is a diamond. Each type has its own chat Events switch, on by default.
The row always says **Moderator** for a mod, including a Lead Moderator,
because Twitch does not report that distinction. These role rows exist only
for Twitch; Kick does not report its mod, VIP or OG commands to Lumio, and
YouTube reports bans only.

The three Twitch pin types are `twitch:pin_added`, `twitch:pin_updated` and
`twitch:pin_removed`. The feed calls them **Message pinned**, **Pin duration
changed** and **Pin removed**; the icon at the start identifies the platform.
Each type can be filtered independently and is on by default. A **Pin removed**
row also says how long the pin stood (or that it expired): in seconds or minutes
under an hour, in hours and minutes from one hour, and in days and hours from one
day, rounded down.

A goal row shows the goal text as its title and the translated goal type underneath, with the
progress as a chip in your language's number format (e.g. `13.284/14.000`). Its badge reads
**Goal Started** when the goal is created and **Goal Reached** or **Goal Missed** when it ends
(**Goal Ended** if Twitch did not say). Progress updates in between are not listed. **Stream Offline** shows the stream's length
as a clock chip, e.g. `3h 12m`.

A Twitch prediction's end badge reads **Prediction Resolved** (**Vorhersage aufgelöst**
in German) when Twitch reports it as resolved, or **Prediction Canceled**
(**Vorhersage abgebrochen**) when it was canceled. If Twitch sends no status, the
badge reads **Prediction End** (**Vorhersage Ende**). The prediction title and
outcome breakdown stay visible in the event row.

A channel-point redemption shows the reward title, its cost in points and the viewer's input. When
you complete or refund a redemption in Twitch's reward queue, that status change is its own
`twitch:reward_status` row that reads _completed_ or _refunded_; it is on by default and has its own
toggle under the **Twitch** heading of the type filter. Creating, editing or deleting a reward is not
listed in the feed — those changes reach widgets and extensions live only.

### YouTube

`youtube:subscribe`, `youtube:member`, `youtube:superchat`, `youtube:supersticker`,
`youtube:gift_membership`, `youtube:gift_membership_received`, `youtube:poll`,
`youtube:poll_end`, `youtube:stream_online`, `youtube:stream_offline`.

A YouTube poll is one channel-event row titled with the poll question. Below it, each
option shows its bar and its vote count, or its share of the votes when YouTube sends no
count. The row updates in place on every vote, and once the poll is closed the leading
option gets the trophy. Polls are not stored, so the row is only there while the page is
open.

Stream start and stream end render as channel events with a `System` badge, like
Twitch and Kick: **Stream Online** shows the broadcast's title underneath (YouTube
has no stream category, so none is shown), **Stream Offline** shows how long the stream
ran as a clock chip (e.g. `3h 12m`) when the start time is known, otherwise the label only.

### Kick

`kick:follower`, `kick:subscribe`, `kick:resub`, `kick:gift`, `kick:kicks`,
`kick:reward`, `kick:reward_status`, `kick:stream_online`, `kick:stream_offline`,
`kick:stream_update`.

`kick:pin_added` and `kick:pin_removed` use the same **Message pinned** and
**Pin removed** labels, with the Kick platform icon.

Pin rows have the ordinary event layout. The large head avatar belongs to the
person who pinned the message on **Message pinned** and to the sender on
**Pin duration changed** or **Pin removed**. The head name has no badges.
Below it, the message's sender appears with avatar, badges, text and the time
they wrote the message when known. The planned duration appears as a chip by
the type label. The moderator who pinned and a replaced sender show avatar
and name without badges. Names open the User Info Card when the viewer has
`chat:userinfo`; otherwise they are plain text. The feed row has no jump link
to the message.

Kick rows look like their Twitch counterparts: the viewer's name and avatar (click it
for the User Info Card), a months chip on a resub, the gift count and every recipient
on a gift (an anonymous gifter shows a `?` avatar and no clickable name), a gold
**KICKs** row with the amount chip and the sender's message, and a channel-point
redemption with the reward title, its cost in points and the viewer's input. A
redemption's later status change is its own `kick:reward_status` row that reads
_accepted_ or _rejected_. Stream start, stream end and stream-info changes render
as channel events with a `System` badge and the stream title or the changed fields
(see [Stream updates](#stream-updates)), not as a user row. Every Kick type is on by default and has its own toggle under
the **Kick** heading of the type filter; a filter saved before a type existed turns
the new type on automatically. Kick events need the `platform:kick` plan feature.

### Stream updates

A **Stream Update** row (`twitch:stream_update`, `kick:stream_update`) names only
the fields that actually changed, each with its own label:

| Label | Shows | Platforms |
|-------|-------|-----------|
| **Title** | The new title | Twitch, Kick |
| **Category** | `old → new` category (game); only the new one when the previous is unknown | Twitch, Kick |
| **Language** | `old → new` broadcast language, as a language name in your interface language (e.g. _English → German_); the raw code when there is no name for it (Twitch's `other`) | Twitch, Kick |
| **Tags** | The new tag list, comma-separated; `—` when every tag was removed | Twitch |

An unchanged field is never repeated. The title shows only the new value so the
line stays readable. The same line appears on the Events page, in the chat inline
event and on the **Events** tab of the User Info Card. Stream updates recorded
before Lumio tracked language and tags show title and category only. On Twitch, a
tag-only edit is reported together with the next title, category or language
change — Twitch sends no update for tags alone (details:
[Stream update payloads](/features/events#stream-update-payloads-twitchstream_update-kickstream_update)).

### Discord

`discord:member_join`, `discord:member_leave`, `discord:boost`.

### Spotify, StreamElements, Shopify, Copyright, System

`spotify:track`, `spotify:play`, `spotify:pause`, `spotify:skip`,
`spotify:previous`, `spotify:seek`, `spotify:shuffle`, `spotify:repeat`,
`spotify:volume`, `spotify:device`, `spotify:queue_add`,
`spotify:playlist_create`, `spotify:playlist_edit`, `spotify:playlist_delete`,
`spotify:playlist_add`, `spotify:playlist_remove`, `streamelements:tip`,
`shopify:order`, `shopify:order_paid`, `shopify:product`, `copyright:warning`,
`copyright:blocked`, `copyright:clear`, `system:test`.

## Permissions

| Permission        | What it unlocks                                        |
|-------------------|--------------------------------------------------------|
| `events:read`     | View the Events page and the popout                     |
| `events:create`   | Fire a test event                                       |
| `events:userinfo` | Open the User Info Card on an event row                |

## Tips & best practices

- **Use test events liberally before going live.** Fire `twitch:raid`,
  `twitch:cheer`, and `youtube:superchat` to make sure overlays, alerts, and
  automations all behave.
- **Pin a popout to your control monitor.** `/popout/events` in a narrow window
  makes a great always-visible activity feed next to your streaming software.
- **Generate a scoped token** for browser sources under **Settings → Channel → Access → Popout Tokens** so
  a compromised stream PC does not expose your full Lumio session.
- **Filter aggressively during raids.** Hide `spotify:*` and `chat:*` noise so you
  can focus on follow/sub/cheer incoming during the chaos.

## Troubleshooting

### No events arrive

1. Check the channel-status pill - if all channels are offline, most platforms only
   push events for live streams.
2. Open **Manage → Connections** and confirm every platform shows a green
   **Connected** badge. Re-authorize anything showing **Not connected**.
3. Fire a test event. If it shows up but real events do not, the issue is with your
   platform connection or that platform's event subscription scopes.
4. Reload the page to force a WebSocket reconnect.

### `Connection lost - reconnecting…` banner persists

The browser cannot reach the API's `/v1/ws` endpoint. Causes: your auth token
expired (log out and back in), a network blocker (VPN, corporate firewall), or the
API is genuinely down. Check **Account → Sessions** to confirm your session is
still valid.


### Test events do not fire

You need the `events:create` permission. Ask your account owner to grant it on
your role under **Settings → Channel → Roles**.

### Popout shows `Invalid or expired token`

The token was revoked, expired, or scoped too narrowly. Create a new one under
**Settings → Channel → Access → Popout Tokens** and update the URL in OBS / your second monitor.

### Popout shows `No authentication token provided`

You loaded `/popout/events` outside a browser session. Append `?token=YOUR_TOKEN`
to the URL, or load it inside the same browser where you are logged in.

## Related

- [Channel Status](./channel-status.md) - how online/offline state gates workers
  and pollers.
- [Overlays](./overlays.md) - how events drive on-stream widgets and alerts.
- [Automation Templates](./automation-templates.md) - react to any event with the visual builder.
- [Chat](./chat.md) - chat messages and moderation share the same WebSocket
  channel.

---

## User Guide / Music (Spotify)

Source: https://docs.lumio.vision/user-guide/music

# Music (Spotify)

Lumio integrates with Spotify to show and control the music playing on your
stream. It surfaces the currently playing track, full playback controls, device
selection, your playlists, and a recently-played log - all from the Dashboard,
and all available as an OBS-friendly popout. Track changes emit `spotify:track`
events so overlays and automations can react in real time.

This guide covers connecting Spotify (including the manual workaround for free
accounts), the Music page layout, playback controls, popout configuration, and
troubleshooting.

## Where to find it

- **Sidebar**: Stream → Music (`/dashboard/music`).
- **Popout window**: `/popout/music`.
- Requires `spotify:read` and the Music feature on your plan.

## Quick start

1. Open **Manage → Connections** and connect **Spotify**. Authorize every
   requested scope - Lumio needs read and playback access to show the current
   track and control playback.
2. Start playback on **any** Spotify device (desktop app, phone, Sonos, Alexa,
   browser web player). Spotify's API cannot cold-start a device - it can only
   transfer an already-active session.
3. Open **Stream → Music**. You should see the current track, album art, and
   playback controls.
4. If you are not live right now, click **Connect** in the banner at the top to
   wake the Spotify worker for 30 minutes.
5. Optional: open `/popout/music?token=YOUR_TOKEN` in OBS as a browser source to
   show a chrome-free player on your producer view.

## Connecting Spotify

Go to **Manage → Connections** and find the **Spotify** card. Click `Connect`, log in to Spotify,
and approve the scopes. On success the card shows `Connected as {name}` with an
auto-refresh note - Lumio keeps the OAuth token fresh via the Token Refresh
Worker, so you never re-authorize manually.

If the Music page shows `Connect Spotify to control your music`, Spotify is not
linked yet - the button `Go to Connections` takes you straight to the setup.

### Spotify Free accounts

The Spotify Web API refuses playback control for Free accounts for long stretches
of time, but **read access (current track, recently played) still works**. Lumio
shows the current track and emits `spotify:track` events even on Free; you just
cannot hit Play/Pause/Skip from the Music page without a Premium account.

## The Music page

### Now-playing header

At the top of the page:

- **Album art** - click to copy the Spotify track URL (`Copy URL` label).
- **Song title and artist** - links out to Spotify's web player.
- **Progress bar** - current position / duration in `mm:ss`.
- **Playback controls** - `Previous`, `Play/Pause`, `Next`, `Shuffle`, `Repeat`
  (with a `Repeat 1` state). Shuffle can display `Off`, `On`, or `Smart`.
  Smart Shuffle is a read-only state in Lumio: activate it in the Spotify app,
  because Spotify's public Web API only lets Lumio switch regular shuffle on or
  off. `Mute`/`Unmute` and the volume slider are a separate block that needs
  `spotify:volume`.
- **Popout button** - the external-link icon at the top right opens the
  `/popout/music` window (380×700 by default).

The page heading and popout button stay in place while Spotify status loads. If a
player is expected, loading rows occupy its space; a temporary loading state does
not show a connection error. Within the Music page, the loading player and an
unreachable-player message occupy the same space, keeping the recently played
section in place when the player read finishes.

If Spotify is connected but nothing is playing, you will see `Paused` or
`No active playback` with the hint `Open Spotify on any device to start
playback`. Once at least one device and one playlist are visible, a small
starter row appears with a **Device** dropdown, a **Playlist** dropdown, and a
`Start Playback` button that begins that playlist on that device. It requires
`spotify:playback`.

### Connect banner (channel-status gating)

To save API quota, Lumio only keeps the Spotify worker running while at least
one of your channels (Twitch, YouTube, Kick) is live. When you are
offline you will see a `Connect` banner:

- **Connect** - wakes the worker manually for 30 minutes so you can test
  overlays or listen on camera-off streams. Requires `spotify:worker`.

Once any channel goes live, the worker starts automatically and the banner
disappears. See [Channel Status](./channel-status.md) for details.

### Reconnect required

If your Spotify connection expires and cannot be refreshed, the player stays on
the page but turns **unavailable**: dimmed, with the last known track (or the
empty state) and every control disabled - separate from the "connect Spotify"
hint you see when nothing is linked yet. The red **Spotify channel disconnected**
entry of the [connection notices](../features/connections.md#connection-notices) above it says
why. On the dashboard its **Reconnect Spotify** button starts the Spotify OAuth flow; in
the popout the entry is read-only - a link that opens Connections in a new tab (a
delegated popout shows the text only). See
[Connections → Reconnect flags](../features/connections.md#reconnect-flags).

### Spotify rate limit

Spotify can temporarily throttle the account's app. When a Spotify request gets a
429, the Music player shows a warning banner with the seconds until it will read
again. The same banner appears in the dashboard and the popout, including an OBS
popout. The last known track stays visible; a rate limit does not mean the
connection has expired or the player is unreachable. If the first read is
throttled, the player still appears with the banner while it waits for its first
full state.

During the wait, the player pauses its regular 60-second poll and skips device
and playlist refreshes. It reads the full state once when the countdown ends,
then resumes regular polling. You do not need to reconnect or reload the page.
The banner's × hides it for the current wait; a later rate limit can show it
again. It has no action button in either view.

### Tabs

Three tabs sit below the player:

#### Search

Search Spotify's catalogue. Typing runs a debounced search once you have entered
at least two characters. While a search is running the panel shows `Searching…`.
If Spotify is unreachable, the panel shows `Search failed` with a **Retry** link
instead of an empty result. A rate-limited search shows the player-wide
[Spotify rate-limit banner](#spotify-rate-limit); while that banner is visible,
the panel does not repeat the rate-limit message. If you dismiss the banner,
the panel can show `Too many requests — please wait a moment` with **Retry**.
Results show cover, title, artist,
and two actions:

- **Add to queue** - queue the track on the active device. Requires
  `spotify:queue`.
- **Add to playlist** - drop it into one of your Lumio-managed playlists.
  Requires `spotify:playlist`.

#### Playlists

Your Spotify playlists, with create / rename / delete on the ones you own:

- The `New playlist name` input plus the `+` button creates a new playlist.
- Each playlist row shows its cover, name and track count. **Click the row** to
  start playing it.
- The pencil icon (only on playlists you own) opens a rename dialog, which also
  holds the delete action - it asks `Delete this playlist?` before removing it.
- The refresh icon (`Refresh playlists`) forces a resync if Spotify changes are
  slow to appear.

The whole tab requires `spotify:playlist`.

#### Devices

Lists every Spotify Connect device currently visible to your account (desktop,
mobile, browser, speakers, consoles). Each row shows the device name and
`Active` badge if it is the current playback target. Click any device to
transfer playback to it. `Refresh devices` forces a fresh poll. The list scrolls
inside the tab, so a long device list never spills out of the card; once you have
more than five devices a filter field appears above it so you can narrow the list
by name or type (with a `No matching devices` line when nothing matches).

Requires `spotify:device`.

### Queue panel

The queue panel sits next to the tabs and lists upcoming tracks (from Spotify's
read-only queue) plus anything you add via Lumio's `Add to queue` action. Click
a queue row to skip straight to that track. Once the queue has more than three
entries, a small search input appears in the panel header so you can find a
specific track quickly.

### Recently played

Below the player, the `Recently Played` section lists the last 7 days of tracks
(up to 50). Each row shows the cover art, song, artist, how long ago it played,
and a status badge (safe / blocked / reported, from the copyright database).
Small icon buttons at the end of each row let you copy the Spotify link, copy
the track ID, and - if you have the copyright feature and the matching
permission - report or recommend the song.

The same report and recommend actions appear on the inline `Now Playing` event
line in Multichat: on a Spotify track row the flag and plus buttons sit **always
visible** next to the copy-URL action - no hover needed, so they are reachable on
touch and in the pop-out just as they are on the dashboard. They show only if you
have the copyright feature and the `copyright:report` or `copyright:recommend`
permission; each button appears only when you hold that specific permission and
the track has both a song name and artist. A playlist line carries only the
copy-URL action.

## Popout (OBS and secondary monitors)

Open `/popout/music` or click the external-link icon on the Music page. Inside
OBS or a browser without your cookies, append `?token=YOUR_TOKEN` (popout tokens
are created under **Settings → Channel → Access → Popout Tokens**, see [Tokens](./tokens.md)).
The [seasonal look](/user-guide/preferences#popouts-and-obs) also shows in this popout; append `&season=off`, `&seasonStrength=subtle` or `&seasonMotion=off` to the URL to change it for this popout only.

The popout is a compact, chrome-free player with:

- The same now-playing header, playback controls, queue, search, playlists, and
  devices - in a single-column layout.
- A `Settings` cog that opens a **full-screen settings panel** - the same
  presentation as the Chat and Events popouts - with a **Font Size** slider, a
  **Streamer Mode** toggle, a **Theme** picker, and a **Region & language** block
  (language, time zone, date format, and time format). Close
  it with the `×` in its header. (The per-item display toggles you see in the
  Chat and Events popouts do not apply here.)

Once the view settings have loaded, the cog and wake-lock indicator remain in the
bottom bar whether Spotify is disconnected, needs reconnecting, is waiting for
manual connection, is playing, or is unreachable. The search field appears with the
player; its space remains reserved in the other states. The saved font size applies
from the first frame.

Permissions granted to the token determine which buttons appear - a token with
only `spotify:read` will show the player but hide Play/Pause, Skip, queue, and
device controls.

### Animations for this view

Open the settings gear and choose **Animations → As global, Reduced, or Off**. The choice affects this view on the dashboard and in its popout, and is stored per browser and per user/account pair. It can only reduce motion further than your [global Animations in Lumio preference](/user-guide/preferences#animations-in-lumio); an unavailable looser choice is disabled. For an OBS popout, append `&motion=reduced` or `&motion=off` (use `?` if it is the first URL parameter) to apply a stricter choice to that URL without saving it. The global preference is read-only in a token popout.

## Where these settings apply

**Most of these settings apply to you on this account.** Your Music **display
settings** (font size, theme and the layout options in the settings panel) are
stored in your browser and keyed to the pair *(you, the channel account you are
viewing)* — switch to a second channel account, or sign in as a different team
member of the same account, and they start from defaults. You set them once per
browser context (the dashboard, and again in an OBS popout, which is separate).

**Streamer Mode, the Region & language block, and Animations in Lumio are global
user settings.** Streamer Mode, your language, time zone, date/time format and global motion preference are
stored on your user profile, so they follow you across devices and every channel
account — the Region & language block here is a second entry point to the same
values as [Dashboard → Settings](/user-guide/preferences), not a per-account copy.

Which **Spotify account** is connected is a separate matter: that is a per-channel
**connection**, managed on the [Connections](./connections.md) page, not a view
setting stored here.

## Presets

The music settings panel has a **Presets** tab - named snapshots of your Music display
settings saved to your account, so you can switch layouts and reuse them across devices.
**New preset** opens an assistant to choose what to store and name it; each preset card
offers **Load**, share, overwrite, rename and delete, with a quota line for your plan's
limit. **Share** copies a code/link for the preset and can make it visible to your whole
account (with the `presets:share` permission); presets teammates share into your account
show up in a **Shared from the channel** section you can load or save as your own. The
**Export** / **Import** buttons below the cards move settings to a file, code or link (on a
plan without presets they sit in the General tab instead). In a popout you can load a preset
but not change or share one. See the
[Setting Presets](../features/setting-presets.md) feature page for details.

## Permissions

| Permission         | What it unlocks                                          |
|--------------------|----------------------------------------------------------|
| `spotify:read`     | See the current track, queue, recently played            |
| `spotify:playback` | Play / pause / skip / previous / shuffle / repeat / start a playlist |
| `spotify:volume`   | Mute / unmute and the volume slider                       |
| `spotify:queue`    | Add tracks to the playback queue                          |
| `spotify:playlist` | Create, edit, delete, and play your playlists             |
| `spotify:device`   | List and switch Spotify Connect devices                   |
| `spotify:worker`   | Manually wake the Spotify worker when offline             |

The Music page itself requires `spotify:read` (the `PermissionErrorBoundary`
enforces it). Without `spotify:read` the page shows a graceful access-denied
state instead of an empty player.

## Tips & best practices

- **Always start playback on a real device before the stream goes live.**
  Spotify cannot cold-start a device from the Web API; transfer a playing
  session.
- **Use playlists for stream music.** Curate copyright-safe playlists and swap
  between them from the Playlists tab during breaks.
- **Turn off private session on Spotify.** Private sessions hide the current
  track from the API - you will see `No active playback` even while music
  plays.
- **Pin the popout in OBS** with a token restricted to `spotify:read` if the
  popout will be visible on stream, so a viewer cannot trick an overlay into
  skipping a track.
- **Let the worker auto-start.** The 30-minute manual window is designed for
  setup and testing; under normal use the worker follows your live state.

## Troubleshooting

### `Connect Spotify to control your music`

Spotify is not connected at all. Go to **Manage → Connections**, find the
**Spotify** card, and authorize.

### Spotify rate-limit banner

Spotify is temporarily throttling requests for the connected app. Keep the
player open; its countdown shows when it will read again and it resumes
automatically. See [Spotify rate limit](#spotify-rate-limit).

### `No active playback` but music is playing

- Open Spotify on any device and press Play again to force a Connect handshake.
- Check that Spotify is not running in a private session (Settings → Social →
  `Private session` off).
- Free accounts cannot be remote-controlled but can still be read; you may need
  to control playback from the Spotify app itself.

### `Open Spotify on any device to start playback`

No device has been active recently. Spotify Connect devices go to sleep after
inactivity; open the Spotify desktop or mobile app to wake one up, then hit
`Start Playback` again.

### Playback buttons are disabled

Either the Spotify worker is not active (channels offline and no manual
connect), you do not have the relevant permission (`spotify:playback`,
`spotify:volume`, `spotify:queue`, `spotify:device`), or you are on a Free
account. The banner at the top of the page explains which case you are hitting.

### `Connection lost - reconnecting…`

The Spotify worker WebSocket dropped. Lumio reconnects automatically. If it
persists, your session token may have expired - log out and back in.

### Devices list is empty

Open any Spotify client (desktop, mobile, browser) so it registers as a
Connect device, then click `Refresh devices`.

### Track art never updates

The Spotify worker is probably stopped (no live channels). Click `Connect` in
the banner to wake it for 30 minutes, or go live on any connected platform.

## Related

- [Events](./events.md) - Spotify changes emit `spotify:track` events your
  overlays and automations can react to.
- [Channel Status](./channel-status.md) - controls when the Spotify worker runs
  automatically.
- [Overlays](./overlays.md) - add the Spotify Now Playing widget to your
  overlays.
- [Automation Templates](./automation-templates.md) - trigger flows on track
  changes, play, pause, skip, and playlist edits.

---

## User Guide / Multichat

Source: https://docs.lumio.vision/user-guide/chat

# Multichat

Multichat is Lumio's unified chat experience. It merges messages from every
connected platform - Twitch, YouTube, and Kick - into one stream with full
emote rendering, moderation tools, reply threading, and a rich user-info card.
It also shows live overlays for polls, predictions, hype trains, raids, ad breaks,
and every other mod-facing event so you can react without ever leaving the chat
view.

This guide walks through the Chat page, every moderation action, the user info
popup and mod notes, the `/popout/chat` window for OBS, and how to send messages
from Lumio directly.

## Where to find it

- **Sidebar**: Stream → Chat (`/dashboard/chat`).
- **Popout window**: `/popout/chat`.
- Requires `chat:read` and the Multichat feature on your plan.

## Quick start

1. Connect at least one streaming platform under **Manage → Connections**.
2. Open **Stream → Chat**. Messages start appearing as soon as the WebSocket
   connects - you will see the `Connected` indicator in the header.
3. Pick the platforms you want to see using the platform toggles at the top of the
   feed (Twitch / YouTube / Kick). Toggles let you read, send, or both per
   platform.
4. Type a message in the footer input, press `Enter` to send. Use the emote picker
   (the `:)` icon) to insert emotes from any of your connected sets.
5. Click any username to open the **User Info Card** for quick moderation context.

## The Multichat feed

When you open Chat on the dashboard or in a popout, its header, input bar and optional
viewer-list area keep their places while message rows load. The viewer list shows
loading rows immediately when enabled. If you have hidden the header, input bar or
viewer list, its loading frame respects that setting. When you switch to a platform
or YouTube broadcast tab, the feed shows loading rows in place. **No messages found.**
appears only once that
load has finished and there really is nothing to show (or every row is filtered out). A live
message that arrives during the load shows at once. With the Halloween look at **Full** strength
the empty feed shows a floating ghost instead (see [Preferences](./preferences.md)).

### Message rows

Every row shows:

- **Platform icon** (Twitch purple, YouTube red, Kick green).
- **User avatar** (squared, next to the platform icon).
- **Source-channel avatar** (Twitch Shared Chat only) - a square, rounded-corner avatar with a channel-coloured ring
  channel avatar directly *before* the badges when the message crossed in from
  another channel's room during a shared-chat session, as on Twitch (see
  [Twitch Shared Chat](#twitch-shared-chat)).
- **Badges** (broadcaster, moderator, VIP, subscriber, founder, artist, cheer).
  Twitch and YouTube member badges use the image the platform sends. Where a
  platform sends none, the badge is drawn in that platform's own artwork where
  Lumio has it - a Kick channel owner shows Kick's pink-to-purple microphone
  **host badge**, a Kick moderator shows Kick's blue sword **moderator
  badge** and a Kick VIP shows Kick's gold crown **VIP badge** - and otherwise falls back to the generic icon. On **Kick**, a
  subscriber shows the channel's own sub badge for their tier, and a chatter who
  turned on their Kick **level badge** shows Kick's level image. The level badge
  can be missing on a chatter's first message and appears from the next one. OG, Verified, Staff, Sidekick,
  Bot and Sub Gifter show Lumio's own Kick-style badges, as does a subscriber or level
  badge whose image is not known yet (the level plaque shows the number). Hover a
  badge to see what it is, with its tier where the platform sends one -
  `Subscriber · 12 months`, `Sub Gifter · 50`, `Level 7`.
- **Display name** in the user's Twitch/YouTube color (falls back to a platform
  default). On **Twitch**, a viewer whose display name is written in a non-Latin
  script that differs from their login - for example `こさむん` with the login
  `kosamun` - is shown as **`こさむん (kosamun)`**, so you still see the handle to
  moderate or search by. An ordinary name is shown on its own, never in brackets:
  a display name that differs from the login only by capitalization (`Cruex` /
  `cruex`) or an accented Latin name such as `Ömer` gets no bracket. This is
  Twitch-only - Kick and YouTube names never get it. Because the rule is applied
  as the chat renders, the bracket also appears on older messages in the history,
  and it shows the same way in the reply-preview header and the delete/moderation
  confirmation dialogs.
- **Message body** with inline emotes rendered from Twitch, YouTube, Kick, 7TV, BTTV, and FFZ.
- **Bits** in a Twitch message (`Cheer100`, or a channel's own cheermote such as `xqcCheer500`)
  render the way Twitch shows them: the cheermote graphic followed by the amount in the tier
  colour (grey 1, purple 100, teal 1000, blue 5000, red 10000), kept together on one line. The
  graphic is the same size as an emote and follows your **Emote Size** setting. Hover it to see
  the original word. If Lumio has no cheermote list for the channel, the word stays plain text.
- **GIFs** posted with the Twitch GIF keyboard render inline as images, loaded
  directly from the GIF provider (GIPHY) at their original URL. Click a GIF to open
  it in a lightbox - a larger preview over a blurred backdrop showing the GIF's
  name, ID, and URL (the ID and URL each with a copy button). Close the lightbox
  with the `✕` button, the `Esc` key, or a click outside it. GIFs never appear in a
  moderation placeholder or a deleted message. The **Show GIFs** setting (on by
  default) controls this: with
  it off, GIFs are not rendered and nothing is loaded from GIPHY. The setting is
  stored per browser.
- **Timestamp** (localized).
- **Action row** on hover: `Reply`, `Copy`, `Delete`, and the moderation dropdown.

Platform icons, avatars, badges, and timestamps are individually toggleable in the
chat settings (gear icon).

### Announcements and spotlight rows

Twitch announcements appear in the message feed in five colours: primary (Lumio's
fixed teal for `/announce`), blue, green, orange and purple. They keep their
colour, emotes, links and Shared Chat origin after a reload. Lumio reads these
messages but does not send announcements. Twitch does not let Lumio delete an
announcement, so its row has no Delete control. If its author is timed out or
banned, the row can still appear as deleted through the usual chat moderation
state. Twitch announcements cannot be pinned, so they have no Pin control.

A first-time chatter and a Twitch watch streak use spotlight rows in both full
and compact chat density. The full row carries the person's message and its
emotes and links; a watch streak also shows the streak count. Compact density
keeps an icon with a tooltip and omits the label. A bare domain such as
`example.com` is a clickable link in ordinary messages, announcements and
spotlight rows, subject to the same external-link warning as other links.

Announcements count as ordinary chat messages for keyword tabs and chat counts.

### Pinned messages

The card above chat shows the current Twitch and Kick pins. The sender has an
avatar and badges; **Pinned by** shows the moderator's avatar and name without
badges. **Sent at** is when the sender wrote the message, and is omitted when
that time is unknown. With `chat:userinfo`, names in the card and pin event rows
open the same User Info Card as other chat names; without it they are plain text.

Members with `chat:pin` can pin an ordinary Twitch message, unpin it or set its
duration from 30 seconds to 30 minutes or until stream end. Twitch uses that
member's own moderator login for the action. Kick pins are visible but read-only
in Lumio and stay pinned until Kick removes them or the channel moves from live
to offline. A Twitch pin made on twitch.tv, even while the channel is offline,
appears after the next poll: within 10 seconds while live or 30 seconds while
offline. At stream end Lumio checks Twitch; a timed pin may remain. An action
refused as **already pinned** refreshes the card. You can collapse the card or
hide a pin locally without changing it on the platform.

Pin changes also appear as chat event rows, including pins made on twitch.tv
without a stream. These rows show avatar and name without badges. The sentence
itself is not a link; use **↓ To message** at its right edge to jump to the
pinned message. Pin event types have individual switches in Chat's Events
settings and appear in the Twitch or Kick platform tab.

### Emote and badge details

Hover an inline emote or badge to see a larger image and its details. On a phone, tap it to open a bottom sheet; tap outside, swipe down, use Back, or press Escape to close. A touch tap on a wider tablet opens a card beside the item. Tapping a user's name still opens the User Info Card.

An emote card shows its provider and, when known, whether it is animated or static, its creator, and whether it belongs to this channel, another channel, or a global set. An unknown animation state has no chip. A linked other-channel name can open Twitch or YouTube; 7TV, BTTV, and FFZ emotes can link to their provider page. Kick may identify another channel without a usable channel link. Use **Copy name** for chat text (Kick uses `[emote:ID:NAME]` when the ID is numeric) or **Copy ID** when an ID is available. A badge card shows the badge title, tier or months when known, and platform, without copy buttons. These cards also work in the [chat popout](#popout-chat-for-obs); in an OBS browser source, use **Copy link** if OBS blocks opening an external link.

Reply chains are shown inline with a small `↳ Replying to {name}` marker. Mentions
of your own username are highlighted; the highlight style is configurable in the
popout settings (`Off`, `Border`, `Background`, `Border + Background`).

A **keyword rule** can carry its own highlight color: matching messages glow in
that color across the platform tabs (a rule's own keyword tab does not re-color its
own rows, since every row there already matches). When several colored rules match
one message, the first rule in your ordered list wins. A rule color outranks the
automatic role coloring: on a moderator's, VIP's, or self-mention row a matching
rule paints **both** the border and the background in the rule color, while the
mod/VIP **badge stays visible**. Rule colors honor the same
highlight-style setting above and are automatically adjusted for contrast in both
light and dark themes. Moderation always takes precedence: a message you have set to
`Monitor` or `Restrict` keeps its amber / red treatment marking regardless of any
rule color, and a rule with no color assigned highlights nothing.

A rule matches a message in one of two ways, combined with **or**: a **keyword**
matches when the message *contains* it (anywhere, or on whole-word boundaries - set
by the rule's matching mode), and a **prefix** matches when the trimmed message
*begins with* it, case-insensitively. Prefixes are made for command tabs: a rule
with the prefix `!frage` collects every message that *starts* with `!frage` but not
one that merely mentions it mid-sentence. A rule can mix both - for example prefix
`!frage` **or** keyword `umfrage` - and either one alone is enough: a rule needs at
least one keyword or one prefix, not both. The two fields are **never joined into a
single term**: a keyword `test` together with a prefix `#` matches messages that
contain `test` **or** that start with `#` - not the one string `#test`. To match
`#test`, enter `#test` itself, either as a prefix (begins-with) or as a keyword
(contains). Prefixes ignore the whole-word setting
(a prefix is always a begins-with test). Because a prefix rule is exactly what you
reach for alongside the global *Hide commands* switch, its matches stay visible even
when that switch would otherwise blank a `!` message.

### Inline stream events

Some stream events appear **inline in the feed**, between the message rows, styled to
match the Events feed but at chat-line density - not as an overlay card (that is the
separate [Alerts overlay](#alerts-overlay)).

- **Watch streak** (Twitch) renders as a **spotlight card**, not a plain event line - see
  [Spotlight cards](#spotlight-cards-first-time-chatters-and-watch-streaks) below.
- **Subs and resubs read in your language.** A sub, resub, gift sub, Prime upgrade or
  bits badge shows its summary - the **tier** ("Stufe 1", "Prime") and, for a resub, the
  **months** ("30 Monate") - **translated by Lumio**, not the English sentence Twitch sends
  (e.g. "subscribed at Tier 1. They've subscribed for 30 months!"). Month counts are
  pluralised correctly in each language ("1 Monat" vs "30 Monate").
- **Events carry the viewer's own message in a grey box below the line.** For the
  message-bearing types - resubs, cheers, tips, and YouTube SuperChats (and any other event
  the viewer can attach text to) - the event summary itself (name, and the translated
  platform recap such as "Stufe 1 · 30 Monate") stays **on the event line**, and the
  viewer's **own written message** drops onto **its own line below**, set apart in a **grey
  box with a small message icon** - the same way it appears on the Events page - so written
  text stands out from the automatic recap. Emotes in the message render as images and follow
  your **font size** and **emote size** settings, exactly like a normal chat message. A long
  message **wraps within the box** and is shown in full, exactly like a chat message - the box
  is never clipped with an ellipsis. Events with no written message (a follow) show no box.
- **Channel-point redemptions** (Twitch and Kick) name **what was redeemed and its price** on the
  line: after the redeemer's name comes the reward's title (a muted suffix) and its cost
  as a small accent plaque, e.g. "500 Points". If the reward has a message prompt, the
  viewer's own text follows in the same grey box **below the line** - the reward and its
  cost read on the line, and the viewer's text sits in the box beneath, wrapping when long.
  On Kick a redemption can change status after it was redeemed; that change is its own
  **Reward Status** line, which adds _accepted_ or _rejected_ after the reward title.
- **Cheers** (Twitch Bits) and **KICKs** (Kick's Bits) show the sender's name, the amount and
  the sender's own message in the grey box, highlighted in gold. The amount is a token like in
  the platform's own chat: the cheer's tier graphic or the Kick gift's sticker, then the number
  in the tier or gift colour (e.g. KICKs · trainwreck_fan · Rage Quit [sticker] 500). A KICKs
  line also names the gift. Cheermotes inside the cheer's message render as graphics too.
- **Twitch goals** name the goal, its type and how far it got: the goal text you set on
  Twitch, the translated goal type (Followers, Sub points, Subs, New sub points, New subs,
  Bits or Cheerers) and the progress as a plaque in your language's number format, e.g.
  "Goal Started · Road to 14k · Followers [13,284/14,000]". When the goal ends, the line is
  labelled **Goal Reached** or **Goal Missed** (a goal you end early on Twitch counts as
  missed - Twitch sends no separate cancel event). Progress in between is not shown as a
  line, so a busy goal never floods the chat. A part Twitch did not send is left out.
- **Twitch polls and predictions** show their title after the row label when Twitch
  supplies one. Poll start, prediction start, prediction lock and poll delete rows
  show the label and title only. A poll end with votes and a named winner adds a
  plaque with the trophy, winning option and vote share,
  e.g. 🏆 `Elden Ring · 62 %`. If the leading options tie, the plaque reads **Tie**
  (**Unentschieden** in German) without a trophy; with no votes, there is no result
  plaque. A prediction end reads **Prediction Resolved** (**Vorhersage aufgelöst**)
  with a trophy and the winning outcome, or **Prediction Canceled**
  (**Vorhersage abgebrochen**) when canceled. Without a status from Twitch, its label
  remains **Prediction End** (**Vorhersage Ende**). The line does not name who
  started or ended a poll or prediction: Twitch sends no creator for these events,
  and Lumio does not start them. The full breakdown of options, bars, channel points
  and Bits stays on the Events page and in the chat alert box.
- **YouTube polls** show the poll question after the row label, as one line per poll:
  vote updates do not add lines. The live share per option is in the chat alert box
  and on the Events page.
- **Stream Offline** shows how long the stream ran as a clock plaque, e.g. "Stream Offline
  [3h 12m]", on Twitch, YouTube and Kick. When the start time is unknown (for example an
  older Twitch or YouTube event) the line shows the label only.
  Hover the token for the full amount, e.g. "Rage Quit · 500 KICKs". When no graphic is
  available (a Kick gift Lumio does not know yet, or an older line), the line shows the coin
  or bolt icon with a text plaque such as "500 KICKs" or "500 Bits" instead. "KICKs" is Kick's
  product name and is not translated.
- **Bits and KICKs graphics** follow the theme (Twitch's light images in the light theme) and
  your **font size**; in a chat message and on the inline event line they also follow the
  **Emote Size** slider, exactly like an emote. Lumio loads Twitch's larger cheermote image on
  high-resolution screens and whenever the graphic is drawn large, so it stays sharp at big font
  or emote sizes. The graphics move only when animations are allowed: with **Animations in
  Lumio** off, or your system's reduced-motion setting on, they show their still image - and
  where the platform sent no still image, the plain text (`Cheer100`) instead of an animation.
  In the light theme the amount colour is slightly darker so it stays readable.
- **Resubs** (Twitch and Kick) name the months, e.g. "3 months".
- **Gift subs** (Twitch, Kick, and YouTube gift memberships) name **how many were gifted
  and who received them**: after the gifter's name comes the count as a small accent
  plaque, e.g. "×5", and then the recipients as a muted suffix, e.g. "to Ann, Bob, Cara,
  Dan, Eve". **Every** recipient is named, however large the bundle - the list is never
  shortened to a "+N" and never clipped; the segment simply **wraps** onto the next lines.
  A single targeted gift shows the one recipient's name. If the recipient list
  has not arrived yet (a large bundle is announced the instant it starts, its recipients a
  moment later), only the count shows and the "to …" part is left off - no empty separator.
  The recipient names are plain text, not clickable: the clickable name on the line is the
  gifter, matching who the User Info Card would open.
- **Hype Train** (Twitch) shows its **level** and running **total**: the line reads
  "Hype Train · Level 3" with the total as an accent plaque, e.g. "4,200 Points". The
  end-of-train line reads the same way. Hype Train has no single viewer, so its name is
  not clickable.
- **Raids** (incoming, Twitch) name **who raided and what they were streaming**: after
  the raider's name comes the raided stream's **title** and **category** as muted
  suffixes, and the **viewer count** as a plaque with a people icon, e.g. "150". If any
  of those details is missing it is simply left off - no empty separator.
- **First message** (a viewer's first-ever message in the channel) does **not** get a
  separate line - for a first message the event *is* the message. Instead the message
  itself becomes a **spotlight card** - see
  [Spotlight cards](#spotlight-cards-first-time-chatters-and-watch-streaks) below.
- **Click the name on an event line** to open the same **User Info Card** a message
  name opens - the quick moderation and profile context for that viewer. This needs the
  *View user info* permission (the same one a message-name click needs); without it the
  name is plain text. The name is only clickable where a real platform user backs the
  line: events with no viewer (a hype train, a Spotify track, a stream going live), the
  anonymous gifter (Twitch or Kick), and any event whose payload carries no user ID show no
  click target, so a click never opens the wrong card or nothing at all. Kick events carry
  the viewer's Kick user ID, so a Kick follower, subscriber, gifter, KICKs sender or redeemer
  is clickable like a Twitch viewer, and the card's **Open Profile** link goes to their Kick
  channel.

Beyond the watch streak, the inline catalog is the **same list as the Events feed** - every
event type the feed can show can appear inline too. That covers the high-value stream events
across platforms (subs, resubs, gifts, cheers, KICKs, tips, superchats, raids, the hype-train
lifecycle), follows, channel-point reward redemptions and their Kick status changes, the Spotify
now-playing family, **and** the stream-lifecycle events (stream online / offline / updated on
Twitch, YouTube and Kick, and Twitch ad breaks), Shopify orders, Discord member events, and
copyright notices. **Every event type is
shown by default.** Tune which types appear, and how each line looks, on the **Events** tab of
the chat settings (see below); the choice is per browser.

**7TV emote changes** also appear as chat lines: an emote is added, removed or
renamed, or the channel switches its active 7TV set. The line shows the 7TV
editor's name as plain text, the emote image and name (struck through when
removed), an `old → new` name for a rename, or the set name and an emote count
when known for a switch. In chat, consecutive additions or removals by the same editor in the
same set combine when each is within 30 seconds of the last and no other line
intervenes. Up to 12 emote images appear, followed by `+N more` for the rest.
Renames and set switches stay separate. The Events page and stored history keep
each change as its own event. A newly available emote normally reaches the
picker and autocomplete after the live event, with a short refresh delay.
Events from before the listener ran or during a full outage cannot be recovered.

A stream-lifecycle line (for example **Stream Online**) has no viewer behind it, so it renders
its label and the stream details - the title on go-live, the changed title or category on
**Stream Update** - with no avatar and no name.

The **All** chat tab keeps the mixed feed: all chat messages and all visible inline
event lines. Platform tabs narrow both parts of the feed: the Twitch tab shows Twitch
messages and `twitch:*` event lines, the YouTube tab shows YouTube messages and
`youtube:*` event lines, and so on. A 7TV line also appears in every platform
tab whose channel uses that set, including older history, when the event lists
those platforms. If the platform list is missing, the line appears only in **All**.

At the top of the **Events** tab a **Show Event Lines** master switch turns the inline
event lines off at once. It is a display switch only: turning it off leaves the per-type
selection below untouched (dimmed so you can see it resting intact), and turning it back
on restores exactly the choice you had. Two lines are **always** kept: the **first-message
marking** and the **Watch Streak** stay visible even with the switch off, because both carry
the viewer's own chat message - so they have no per-type toggle either, just a note in the
master switch's description. The count badge only ever counts the toggleable types, so with
the switch off it reads 0.

The display options under the master switch (avatar, platform icon, timestamp, event label)
also carry **Events from Shared Chat partners** (on by default). Off hides every event that
happened in a [Twitch Shared Chat](#twitch-shared-chat) partner channel; the four Shared Chat
session lines (start, join, leave, end) always stay.

Below the master switch, the event types are grouped into ten named groups - Twitch, YouTube,
Kick, **7TV**, Spotify, StreamElements, Discord, Shopify, Copyright, and **System** (only the test
event). A stream going online/offline, a title change and an ad break belong to their
platform's group; the **Kick** group lists every Kick type - follow, sub, resub, gift sub,
KICKs, reward, reward status, and stream online/offline/update. Each group is **collapsible and starts
collapsed**, with a "*n* of *m* on" counter on the heading so a closed group still tells you
how many of its types are enabled; click the heading to expand it.
The **7TV** group has four switches for added, removed, renamed and set-switched
events, all on by default. The Events page has a 7TV platform filter and type
filters, and the test-event panel can preview all four types.

The Twitch group also has individual, default-on switches for **Message
pinned**, **Pin duration changed**, **Pin removed**, **New Mod**, **Mod removed**,
**New VIP** and **VIP removed**. Kick has **Message pinned** and **Pin
removed**. The pin type labels do not repeat the platform name; the icon at
the start of the row identifies it. Moderator/VIP rows are available only
for Twitch. A **Pin removed** or **Pin expired** line says how long the pin
stood: in seconds or minutes under an hour (`45 sec`, `12:04 min`), in hours and
minutes from one hour (`1 hr 8 min`), and in days and hours from one day
(`2 days 20 hr`), rounded down.

**Each group heading is also an on/off switch** - a separate toggle beside the collapse control.
Switch *Twitch* off and every Twitch event line disappears at once - handy when you follow one
platform's chat but not another's - while the per-type selection underneath stays exactly as
you left it (it just dims), so switching the group back on restores your choices. Switching
*Kick* off silences every Kick line, including types added after you saved your settings.
Turning a group off leaves the master switch (which is the "all groups at once" lever)
untouched, and the always-on Watch Streak line still shows even with its group switched off.
Newly added groups start on, and so do event types added after you last saved: a type your
saved selection does not mention yet is shown by default. (This is separate from the platform **tabs** at the top of the
chat, which still narrow the feed by the event's platform prefix.)

Event lines follow the same **Highlight Events** setting as the rest of the chat (the
one under *General*): `Off` paints neither the accent border nor the tint, `Border` the
left accent border only, `Background` the tint only, and `Border + Background` both. The
setting applies on both the compact and full line densities. **Density** itself is a
*General*-tab control and is global - it applies to every message and every event line
alike. `Full` (the default) keeps the standard spacing and your font size. `Compact` tightens
the spacing and makes the **whole chat slightly smaller** - messages, event lines, avatars and
emotes shrink together, still following your **Font Size** and **Emote Size** settings.
Density never changes the highlight. The event's icon and label keep their accent
colour so the line stays recognizable even with the highlight off.
Event lines always use the **same text size as chat messages** and follow the
**Font Size** slider exactly like messages do. On both kinds of line the time, platform icon,
avatar, badges and event icon sit centred on the first line of text at every font size.

These event lines are **loaded back with the message history**, at the same moments the
messages are: when you open the chat, when you scroll up to reveal older messages, and
after a reconnect. So after a reload the feed shows past event lines interleaved with the
restored messages - not just new events as they happen - and the **first-time chatter**
and **watch streak** spotlight cards return where they belong (without replaying their
arrival animation). On open, reload, or navigation the feed **lands at
the newest line** and stays there until you scroll, even when the most recent lines are event
lines rather than chat messages - the later history and event waves, and any avatars or embeds
that finish loading afterwards, keep the view pinned to the end instead of leaving it above them.
The dashboard chat and the pop-out behave identically.

Messages and event lines are loaded over the **same time window**. Each time you open the
chat or scroll up, the feed pulls back one shared window - up to a full page of messages
*or* about a day of history, whichever comes first - and fetches the event lines for exactly
that step's span, from the oldest message the step revealed up to the top of the same window.
Because each step's events stop at the top of that step, a **quiet gap above a batch of
messages stays event-free** - scrolling up no longer drops you into days of event lines
skimmed off the top of the empty stretch between two sparse bursts of chat. On open, the event
history stops at your most recent chat message rather than reaching to the present, so a
channel that has been quiet for a while (its last chat is old but its events - Spotify
now-playing, follows - kept streaming) no longer opens on a wall of message-less event lines
with the chat far above them.
On a busy channel a page fills in minutes, so a step loads the same amount of
messages it always did; on a quiet channel the step is bounded by time instead, so you no
longer scroll through days of event lines to find the next batch of messages. **The number of
event lines a step brings back is tied to the messages that step revealed** - a quiet window
that holds only a handful of messages pulls just a few events, so a chat-still but event-busy
channel (Spotify now-playing, follows) no longer buries each scroll-up under a wall of
message-less event lines; a full page of messages still pulls a full page of events. When a
window holds more events than that budget or than the feed keeps, the **event lines** are
trimmed - the chat messages are never dropped and no gap appears in the message history.
**Whenever you are reading history** - the moment you scroll up off the bottom - the event
lines *older* than the oldest message you have loaded are held back, so events walk back in step
with the messages instead of a multi-day wall of message-less event lines running ahead of them.
This holds on a chat-quiet channel too, where the feed always technically still holds the newest
message; you no longer scroll up into a multi-day stretch of event lines with no chat between
them. **While you are reading history the inline event lines are also thinned per gap:** at most a
few event lines appear between any two chat messages (the ones closest in time to the message
below them), so however many events a window minted, scrolling up reads like a chat with the
occasional event line rather than an event log. The thinned-out events are still available in
the **Events** feed. This thinning applies only while you browse history - at the live tail every
event line shows as before. The **newest** event lines, by contrast, are never removed while you browse: on a chat-quiet,
event-busy channel the buffer keeps holding the newest message the whole time, so the most recent
event lines simply stay parked at the tail below your view and are **revealed again - never
re-fetched or re-assembled - when you scroll back down**, so nothing flickers or reloads at the
bottom. (Only on a busy channel, where a long scroll-up actually pushes the newest messages out of
the in-memory buffer, are those newest lines dropped until you jump back to the present.)
**Any upward scroll lets go of the live end** - even a single mouse-wheel notch, a short touch
swipe or *Arrow Up*: the feed stays exactly where you left it, and new messages, event lines or
late-loading avatars and GIFs no longer pull you back down. The chat **follows the newest
messages again only once you are back at the very bottom** - by scrolling all the way down, with
the jump-to-bottom button, or with *Page Down*. When
you scroll up and older content loads, the row you are reading **stays where it is**: the newly
loaded messages appear above it, so they are easy to find. Scrolling up loads the next window
**before you reach the very top**, so the trigger fires even when the lines above you are
mostly events. **Scrolling back down never fetches anything on its own** - it simply reveals the
messages you already loaded, so returning through your history is smooth and never re-pulls lines
that are already there. Coming back to the present is a deliberate step: the **jump-to-bottom
button** or *Page Down* **reloads the newest messages**, so after a long scroll back through
history you land on the current tail rather than a stale one, without reloading the page. If a
long scroll-up pushed the newest messages out of the in-memory buffer, the jump-to-bottom button
**stays available even once you reach the bottom** of what is loaded, so the live tail is always
one tap away. (Only events kept in the server's event history
come back; broadcaster-only alert frames such as same-level hype-train, poll, prediction,
and goal *progress* ticks are never stored and so cannot be restored. Hype-train milestones
- the start, each level-up, and the end - **are** stored and do come back.) Restored event
lines are treated as history:
they never move the unread counter or the "new messages" divider and never play the
notification sound. Inline events arrive on the dashboard chat and on a logged-in pop-out;
a delegated or share-token pop-out receives them (live and restored alike) only when its
token was granted `events:read`.

An event line stays visible even when it is **older than every chat message currently in the
feed**. This is the normal case for Spotify track lines: while you play music before going
live, or after the stream ends, the chat is quiet, so those lines predate the first message
that later arrives. While the feed is following live, such lines are pinned to the **top** of
the feed rather than dropped - they only leave when you close or reload the chat. Scrolling up
into history is different: there the feed shows the events that belong to the message window
you have scrolled to, so an event line settles back between the messages it happened around.
The dashboard chat and the pop-out behave identically.


### Spotlight cards (first-time chatters and watch streaks)

These captures show the current chat in dark, light and compact density.

<div style={{aspectRatio: '1208 / 448', overflow: 'hidden', position: 'relative'}}>
  <img src={FirstWatchDark} alt="First-time chatter and watch streak in dark chat" style={{width: '100%', position: 'absolute', bottom: 0}} />
</div>

<div style={{aspectRatio: '1208 / 448', overflow: 'hidden', position: 'relative'}}>
  <img src={FirstWatchLight} alt="First-time chatter and watch streak in light chat" style={{width: '100%', position: 'absolute', bottom: 0}} />
</div>

<div style={{aspectRatio: '1208 / 384', overflow: 'hidden', position: 'relative'}}>
  <img src={FirstWatchCompact} alt="Compact first-time chatter and watch streak in dark chat" style={{width: '100%', position: 'absolute', bottom: 0}} />
</div>

Two moments have a **spotlight row** with a coloured edge and soft tint. In
full density, the type and hint sit above the message; the platform icon,
time, avatar, badges and name follow the normal chat settings.

- **First-time chatter** (Twitch) - a blue edge and **First chat** heading,
  followed by the viewer's message and a **Greet** button when you can write.
  Replies, `/me` messages and deleted messages keep working in the row.
- **Watch streak** (Twitch) - a warm edge, **Watch Streak** heading, streak
  count and the viewer's own message when present. Badges, name colour and avatar come with the
  event; older streak events from before this change simply show no badges, the default name
  colour and an initial instead of the avatar.

**Greet a first-time chatter.** The **Greet** button on a first-time-chatter card does two
things: it sets that message as your **reply target** (on Twitch and Kick a native reply, so the
viewer is notified; on YouTube the usual `@Name` is added when you send) and fills the chat box
with a greeting, cursor at the end. **It never sends on its own** - you can edit the text and send
it with Enter. If you already typed something, your text stays and only the reply target is set.
The button only appears when you may write in that chat.

The greeting is set in the chat settings, **Events** tab, field **Greeting text**:

- **Untouched**, it is the default in your **Lumio language** ("Welcome to the chat, {name}! Glad
  you're here" / "Willkommen im Chat, {name}! Schön, dass du da bist") and follows a language
  switch.
- **Your own text** is used exactly as written, whatever the language. `{name}` becomes the
  viewer's display name. No `@` is added - the native reply already notifies them.
- **Empty** means Greet only sets the reply target.
- Up to 300 characters; **Reset to default** goes back to the language default. The field travels
  with presets and settings transfer like every other chat setting.

**Hover actions.** Both cards carry the same hover bar as a normal message, also reachable with
the keyboard (Tab into the card). On a first-time-chatter card it is exactly the message bar:
reply, copy, delete and the moderation menu. On a watch-streak card it offers **copy** (when there
is a message) and the **moderation menu** (timeout and ban, monitor, restrict), under the same
permissions as on messages. A watch-streak card has **no delete**: Twitch documents deleting only
for chat messages, not for streak notices - a short timeout clears the viewer's messages instead.
Older streak events without badge data offer no moderation at all, so a moderator is never shown
a timeout button against another moderator.

**Moderated viewers are not celebrated.** If the viewer is **restricted** or **monitored**, the
first-time-chatter message stays a normal row with the red/amber moderation styling and only a
small **First chat** pill; the watch-streak card swaps its frame for the red/amber edge and its
flame stands still.

**Motion.** A card arriving live enters once, quietly (a short fade-in, a soft glow and three
small sparks around the pill; the streak count counts up). Cards loaded from history, after a
reconnect, or when you scroll, filter or reload never replay that entry. The streak flame keeps a
gentle flicker and pauses while scrolled out of view. With **Reduced** motion, the cards use a brief fade; at **Off**, they show their final look immediately. The seasonal "animations off"
switch only affects the seasonal decoration, not these cards.

**Density and width.** With the global density **Compact** the card becomes a **spotlight row**:
built like a normal chat line (time, platform icon, small avatar, badges, name, icon, message),
only the frame makes it 2 px taller. The spotlight type is an icon with a tooltip,
without a text label; Greet becomes an icon button. In a very narrow column the full card drops the hint text and Greet becomes
an icon button.

These cards follow the **Badges**, **Platform Icon** and **Timestamp** settings like the rows
around them. "Highlight Events" and the event-line **Avatar**/**Label** options do not apply to
them - frame, avatar and spotlight mark are part of the card.

### Creating and editing a rule

Rules are built in a **full-screen, three-step assistant**. Open it from the
**Filters** tab of the chat settings (the *New* button) or from the **+** at the end
of the chat's tab bar - both open the same assistant and produce identical rules. The
assistant fills the whole chat window, so it works inside a pop-out too.

The three steps follow *what does the rule match?* → *where does it apply?* → *how is
it shown?*:

1. **Rule** - the rule's name plus its **keywords** and **prefixes** (both chip
   fields: type a value and press `Enter` or `,`). You cannot leave this step until
   the rule has a name and at least one keyword or one prefix.
2. **Scope** - the matching mode (anywhere vs. whole word) and the platform the rule
   applies to. Both have defaults, so you can pass straight through.
3. **Appearance** - show the rule as its own tab, give it a highlight colour, and pick
   a notification sound (with a preview button). These come last on purpose: for a
   quick command tab you just press *Next* twice.

When you **create** a rule the assistant is linear - *Back* and *Next*, with the
finish button only on the last step. When you **edit** an existing rule the same
assistant opens with every step clickable in the progress bar and **Save** active on
every step, so you can jump straight to *Appearance*, change a colour, and save
without touching the other steps. Closing the assistant (the **×**, *Cancel*, or
`Escape`) discards everything - a half-filled assistant never leaves a rule behind.

### Keyword tabs and history

A keyword rule can also appear as its own **tab** above the feed - a filtered view
that shows only the messages matching that rule. Keyword tabs behave like the main
feed, with three additions:

- **History back-fill.** A keyword tab starts from what is still in the in-browser
  buffer, then pulls older matches from the server as you scroll up - the same
  infinite-scroll as the main feed, but querying the keyword search over the last
  12 hours. Live and back-loaded messages are judged by the same matcher, so a
  message never shows in one place and not the other. If a fetched page happens to
  contain no visible match, the tab loads on automatically - capped, so a keyword
  with no recent hits never loops.
- **History timestamps.** Rows pulled from history always show their timestamp (even
  when timestamps are switched off globally), because for a keyword tab *when*
  something was asked is the point. A single divider
  separates the back-loaded history above from the live buffer below.
- **A named end.** When there are no older matches left in the window, the feed shows
  `No older matches in the last 12 hours` instead of the scroll indicator simply
  vanishing. Because a keyword search is time-bounded and retention trims old data,
  reaching this end is normal.

Each tab keeps its own scroll position, unread divider, and jump-to-latest counter:
switching tabs and back returns you to exactly where you were reading, and one tab's
new-message counter never leaks into another.

Entering a keyword tab that has unread matches draws a `new messages` line at your
read boundary and lands you there, so the matches the badge counted are the first
thing you see. **Leaving that tab counts as read:** as long as you did not scroll
while it was open, the line does not come back when you return - unless new matches
have arrived since, which draw a fresh line. The preserved read position of the
other views is unaffected: scroll up to read history in `All` (or a platform tab),
switch away and back, and you return to exactly that spot with its divider intact,
because the messages below it there are genuinely still unread.

### The tab bar

Platform tabs and keyword tabs share **one row** at the top of the chat. When there
are more tabs than fit - many rules, or a narrow pop-out - the row **scrolls
sideways** instead of wrapping onto a second line, so the chat never loses height to
the tab bar. The **+** (new rule) and the **gear** (settings) sit outside the
scrolling area and stay in place; everything else scrolls.

- **On a mouse/desktop**, a left and right **arrow** appear at the edges of the row
  only while there is more to reach in that direction, and a soft fade marks the
  scrollable edge. Click an arrow to scroll the row.
- **On touch**, there are no arrows - **swipe** the row sideways instead.
- The **active tab always scrolls into view** when you select it, and again after a
  reload restores your last tab, so the tab you are reading is never hidden off-screen.
- On narrow widths an inactive keyword tab collapses to just its **colour dot and
  unread count** to save room; the active tab keeps its label, and hovering a
  collapsed tab shows its name.

**Reordering.** On a mouse you can **drag a keyword tab** left or right to reorder it - a click still just selects the tab; only a small drag starts a move. Touch keeps
the **up/down arrows** in the **Filters** settings list for reordering. Both write the
same order, and it survives a reload.

### Twitch Shared Chat

[Twitch Shared Chat](https://help.twitch.tv/s/article/shared-chat) lets several
channels run **one shared chat** - a message sent in another channel's room also
appears in yours. Lumio recognises these cross-channel messages and shows **which
channel each came from**, attributed by channel (the public broadcaster), never by
viewer.

- Each shared-chat message row carries a square, rounded-corner **origin channel
  avatar** after the Twitch icon and before the badges. Its ring has that channel's
  colour; the avatar stays on older messages after a channel leaves. YouTube and
  Kick rows have no origin avatar.
- The **Shared Chat** bar appears below the tabs as soon as a session starts, even
  before a partner writes. It shows the Twitch icon, the host first with a crown,
  your channel next, then partners in joining order (up to four avatars and `+N`),
  live status and **Summe aller Kanäle**. It appears in **All** and **Twitch**;
  **YouTube**, **Kick** and keyword tabs show neither the bar nor Shared Chat
  session event lines. The tabs themselves have no channel avatars.
- Open the bar for a scrollable channel list with categories and viewers. **Only
  this channel** filters the chat locally; **Open on Twitch** visits that channel.
  Select a channel to see its card with live information, follower count when
  available and messages observed in this browser since session start. Escape
  returns from the card to the list, then closes it. Hovering a channel avatar
  with a mouse or activating it opens the same card directly.
- In an OBS popout the bar follows **Show Header**: with the header hidden, the
  bar is hidden too, while origin avatars and event lines remain. There is no
  separate Shared Chat bar setting. **Show Chat Input** does not affect the bar.

Start, join, leave and end appear as Twitch event lines at their event time. Start
and end have expandable channel details in chat; the Events feed shows those
details expanded. The ended bar gives the session duration and the number of all
partners seen, including partners who left earlier, then closes after eight
seconds. A reload or tab switch shows the current state without an entrance
animation. Full motion animates fresh joins and departures and pulses the live
dot; Reduced fades without movement; Off switches immediately. Your
**Chat/Events/Music** motion choice can reduce motion further.

Events in a partner channel of the session - subs, resubs, gift subs, upgrades,
pay-it-forward, raids into the partner and Bits - show up in your chat and events feed
too. Each one carries a **channel chip** - the same channel-coloured origin avatar as a
shared-chat message plus the channel's name in a grey pill - directly before the event
icon, for example `12:04 · Twitch · avatar · [▢ KiraPlays] · Gift Sub · Nordfan_24 · 5× Tier 1`.
A long channel name is shortened with `…`; hover the chip for **"Happened in {channel}'s
channel (Shared Chat)"**, which screen readers also announce. The chip shows even when the
platform icon, the event label or the event avatar is switched off. Shared-chat
**messages** keep the bare origin avatar without a name, like on Twitch.

Partner events follow the same event filters as your own events of that type. To hide
all of them at once, switch off **Events from Shared Chat partners** on the **Events**
tab of the chat settings (on by default). Shared Chat start, join, leave and end stay
visible with the switch off, and messages from partner channels are not affected (use
**Only this channel** in the Shared Chat bar for that). The switch only changes what the
chat shows. Partner events belong to that channel, so they do not count in your stream
history, do not trigger your automations and never open one of your own alerts (raid
countdown, hype train) above the chat.

Messages sent through a channel-points reward with text input carry an orange
**Redeemed with channel points** chip after the badges, in your own chat and from
partner channels (where the origin-channel avatar names the channel). Twitch does not
send the reward's name or cost with the message, so the chip names neither.

Shared-chat display is automatic - there is nothing to enable, and it needs no extra
permission.

### Hide and highlight lists

The **Filters** tab of the chat settings (gear icon) carries four editable lists,
grouped under *Hide* and *Highlight*. Each is a chip field: type a value and press
`Enter` or `,` to add it, `Backspace` on an empty field removes the last chip, and
the `×` on a chip removes it. Every change is saved to your browser immediately and
survives a reload - including in a token pop-out opened without signing in.

The two **user** lists - *Hidden users* and *Highlighted users* - suggest matching
viewers as you type (from two characters on), drawn from the people your account has
seen in chat. Pick one with the mouse or the keyboard (`↑`/`↓` to move, `Enter` or
`Tab` to take the marked entry, `Esc` to close) and the exact **username** is added -
so the rule keeps matching even after that viewer changes their display name. A rule
is not tied to a platform: one entry matches the same name everywhere you are
connected, and a name seen on several platforms appears once. The suggestions need
the *View user info* permission; without it - or if the lookup is briefly
unavailable - the field simply lets you type the name in by hand, exactly as before.
The *Command prefixes* and *Hidden words* lists are word lists and do not suggest.

Under **Hide**:

- **Hidden users** - messages from these users are hidden. The match is
  case-insensitive against the username *and* the display name.
- **Command prefixes** with a **Hide commands** switch - while the switch is on,
  any message whose text starts with one of these prefixes is hidden. `!` is
  pre-filled; add your own (for example `#` or `?`) or remove them. The switch is
  the master toggle - with it off, the prefixes are ignored.
- **Hidden words** with a **Whole word only** switch - messages containing one of
  these words are hidden. By default the word matches anywhere in the text; turn on
  *Whole word only* to match on word boundaries instead (so `art` no longer hides
  `start`).

Under **Highlight**:

- **Highlighted users** - messages from these users get a **highlight colour**,
  matched the same way as the hidden-user list. Each highlighted user has its own
  colour, edited from the **colour button** on the left of the chip - a small pill
  showing the current colour and a pencil icon. Clicking it opens a **colour dialog**
  with a **Highlight** switch, the colour picker, a **Default colour** option, and a
  live preview of a chat line in the chosen tone. Leave the switch on and keep the
  default to use the standard highlight colour, pick a colour for a custom one, or
  **switch it off** to keep the name in the list but stop highlighting it (the chip
  then reads dimmed, with no colour dot). Changes apply only when you press
  **Apply**; **Cancel** discards them. This
  highlight **overrides** the automatic mod/VIP row colouring - a highlighted
  moderator's row shows the highlight colour, not the mod colour - while their mod/VIP
  **badges stay visible**. Choosing a custom colour only changes how the row looks; it
  does **not** change priority - the highlight still ranks below a self-mention, a
  keyword-tab colour, and any moderation treatment, and it follows the same
  border/background highlight style as the rest of the chat.
- **Notification sound** - one built-in sound that plays when any highlighted user
  sends a message. Pick a sound from the dropdown - twelve built-ins grouped by
  character (`Chime`, `Ding`, `Marimba`, `Pop`, `Blip`, `Soft`, `Bubble`, `Click`,
  `Knock`, `Alert`, `Arpeggio`, `Cascade`) - or leave it on `No sound`. Every row has
  its own **play** button, so you can preview each sound right in the open menu (it
  plays the row you click without changing your selection or closing the menu), audible
  even when the volume slider is at `0`. All twelve are loudness-matched, so switching
  between them does not jump in volume. This is **one sound for the whole highlight list** -
  not a separate sound per user. A **switched-off** highlighted user is silent, exactly
  as their row is no longer coloured. If a message both belongs to a highlighted user
  **and** matches a keyword rule that has its own sound, the **keyword rule's sound
  wins** - the same order as the colour cascade. The shared **Notification volume**
  slider and its 1500 ms anti-spam gap cover this sound too, so there is no second
  volume control and no double-ringing.

A message you sent yourself is never hidden by these lists, and a message under a
`Monitor` or `Restrict` moderation treatment always stays visible with its
treatment marking, regardless of the hide lists. A keyword-tab match also shields a
message from the hide filters, so a `!frage` tab is not blanked by the default `!`
command prefix.

### Hidden and deleted messages

Filter-hidden messages are only hidden in your Lumio view. They are not deleted
from the source platform and they are not written as moderation actions. By default
a matching message is **removed from the feed entirely** - the row does not appear
at all. If you would rather keep a placeholder you can click to expand and moderate
what the filter took away, switch `Hidden Messages` to `Show placeholder`. A keyword
rule's own tab also shields its matching rows from the hide filters so the tab does
not immediately hide the messages it was created to collect.

Deleted messages are different: Lumio marks a row as deleted when it receives a
platform deletion event or when a delete/ban/timeout action succeeds in Lumio.
Twitch and YouTube deliver individual message deletions to Lumio, including
moderator deletes and YouTube author retracts. A message deleted on kick.com (by
a moderator or by Kick's AutoMod) reaches Lumio through Kick's unofficial chat
connection, so it is greyed out too - on a best-effort basis, since Kick offers no
official event for it. Kick bans and timeouts always sweep the user's messages.
The **Deleted Messages** setting only controls rows Lumio has actually received as deleted, and it affects the live
Multichat feed only; the User Info Card still shows deleted rows in that user's
message history with a muted deleted style.

A deleted row is attributed to whoever removed the message. For a **Twitch**
moderator delete the acting moderator's display name is shown ("Deleted by
{name}"): Twitch's single-message delete event omits the moderator, so Lumio
sources the name from the richer `channel.moderate` event and reconciles the two,
correcting the live row the moment the moderator is known. **YouTube** moderator
deletes stay attributed generically ("Deleted") because YouTube's delete payload
carries no moderator identity to source a name from.

### Notification sounds

Lumio plays a **notification sound** from two sources: a **keyword rule** that
matches a message, and the **highlighted-user list** (see *Hide and highlight lists*
above). In each case, pick one of **twelve** built-in sounds - grouped by character
from soft to attention-grabbing (`Chime`, `Ding`, `Marimba`, `Pop`, `Blip`, `Soft`,
`Bubble`, `Click`, `Knock`, `Alert`, `Arpeggio`, `Cascade`) - or leave it on
`No sound`. Each row in the dropdown has its own **play** button that previews that
sound in place, without changing the current selection, so you can audition the whole
catalog without picking blindly. The sounds ship with Lumio - there is no upload - and
are all loudness-matched, so switching between them never jumps in volume.

- A keyword rule's sound plays on any live match, **regardless of whether the rule is
  shown as a tab** - a rule set to highlight-only (no visible tab) still rings.
- The highlight-list sound plays when any switched-on highlighted user posts. It is
  **one sound for the whole list**, not one per user.
- If a message matches **both** a sound-carrying keyword rule and a highlighted user,
  the **keyword rule's sound wins** - the same priority as the colour cascade - and
  only one sound plays.
- A sound only plays for a message you can actually see. **Hidden messages do not ring:**
  a message removed by your hidden-user or hidden-word lists is silent, even if its author
  is also a highlighted user - you cannot get a chime for a line that never appears. The
  reverse holds as well: anything the feed shows can ring, including your **own** messages
  (so you can test a rule by posting the keyword yourself) and messages from users under a
  `Monitor`/`Restrict` moderation treatment. (A keyword-rule match still shields a message
  from the hidden-word list, so such a message stays visible **and** rings.) Sounds from a
  platform or keyword tab you are not currently viewing **do** still play - the chime is
  the cue to look there.
- A single **Notification volume** slider in the chat settings' *Filter* tab controls
  the volume for **both** sources; set it to `0` to mute every notification sound.
- Rapid matches are rate-limited, so a burst of matching messages plays at most one
  sound at a time rather than a wall of overlapping beeps. A sound the browser refuses
  to play does not consume that gap - the next match can ring immediately.
- Sounds work the same in the pop-out chat, including a token pop-out opened without
  signing in.
- Browsers only allow audio once you have interacted with the page, so Lumio enables
  playback on your first click or keypress anywhere in the chat. If a sound is still
  refused - most often in a pop-out window parked on a second monitor that you never
  click into - a **`Your browser blocked the notification sound.` / `Enable sound`**
  bar appears above the feed. One click on it both explains the silence and turns the
  sound back on; it disappears as soon as playback is allowed. Every window has its own
  permission, so a pop-out needs its own click even when the dashboard already rings.

### Platform toggles and YouTube multi-stream

The platform-icon row at the top of the feed lets you enable/disable each platform
for **reading** and **sending** independently. YouTube gets an extra dropdown for
broadcast selection:

- **All Broadcasts** shows messages from every YouTube broadcast (current and historical).
- Selecting a specific broadcast filters the chat feed to show only messages from that broadcast's `live_chat_id`. Messages from other platforms (Twitch, Kick) are always visible regardless of the YouTube broadcast filter.
- Outgoing messages are sent to the selected broadcast. Replies always target the original message's broadcast.
- The dropdown works in both the dashboard and the popout chat window (browser source).

### Reconnect required

If a platform's OAuth connection expires and needs reconnecting, that platform
**keeps its tab** (it is never silently dropped) and shows a
**reconnect-required marker** in place of its live counts, in both the dashboard
and the popout. This is a per-platform OAuth state and is deliberately kept
distinct from the WebSocket `Connection lost - reconnecting…` notice, which is
about the live chat socket rather than a platform grant. Reconnect from
**Account → Profile** or **Connections**; see
[Connections → Reconnect flags](../features/connections.md#reconnect-flags).

When a platform you can **send** on needs reconnecting, the
[connection notices](../features/connections.md#connection-notices) under the header say so before a send fails -
one entry per affected platform, paged with **‹ ›** when there are several. This
covers **both** an expired *channel* connection **and** an expired *personal login*
(the login you actually send with); they are two separate entries because they are
repaired in different places. A dead **personal login** entry is red, comes first and
sends you to **Account → Profile**; a dead **channel** connection entry starts the
platform's OAuth flow when you may reconnect channels (`connections:create`), and
otherwise - for a Moderator who can send there - links to the **Connections** page.
The notices sit in the normal layout: they shorten the message feed and never cover
chat messages, and a chat scrolled to the bottom stays at its newest message while
they appear, change or disappear. The affected platform's send toggle is disabled so
you cannot accidentally send a message that would just fail. In a delegated pop-out
(a shared token window, not your own login) the entries have no button, because a
guest cannot repair the connection, and the login-assignment notice is not shown.

With the pop-out **header hidden** but the input visible, only the notices that
concern sending (expired login or channel on a platform you can send on) appear,
compactly, **directly above the message input**. With header and input both hidden
nothing is shown, so a browser source never composites a notice into the stream.

If a send still fails, the failed-send notice shows a plain, translated message -
for a dead personal login it shows the reconnect line and a **Jetzt neu verbinden**
button that opens **Account → Profile**; a message the platform itself refused (for
example slow mode, a ban, or blocked content) shows "*Platform* rejected the message.";
an internal Lumio error shows "Lumio could not send the message - please try again.";
any other failure shows only "Send failed" with the status code. Every failed message
keeps a **Retry send** and a **Dismiss** control. The raw server error is never shown.

### New permissions available

When Lumio starts requesting a scope that an existing connection was granted
without (for example Kick's KICKs and channel points), the connection keeps working
but those events cannot arrive until you reconnect it. The Chat page then shows an
amber **needs new permissions** entry in its [connection notices](../features/connections.md#connection-notices),
with a **Grant {platform} permission** button that starts the same OAuth flow as the Connections page
(from a popout window it opens in a new tab). Only chat platforms appear here. The
entry is only shown to members who may reconnect channels (`connections:create`),
and a connection that already needs a reconnect (above) shows only that entry. The
Events page shows the same entry; see
[Connections → Missing scopes](../features/connections.md#missing-scopes).

### Alerts overlay

When a mod-facing event fires, a compact alert card pins to the top of the feed so
you can act from the same screen:

- **Raid incoming** - shows the raider and viewer count, with quick links.
- **Raid outgoing** - the `Cancel Raid` button stays visible until the raid fires
  or Twitch reports `raid_done` / `unraid`.
- **Ad break** - shows the duration and whether the break was `Automatic`.
- **Hype Train** - live progress and `Hype Train Complete` summary at the end.
- **Polls** - running totals per option with an `End Poll` shortcut. A YouTube poll
  shows its question and each option's share of the votes, with the vote count when
  YouTube sends one (its InnerTube feed sends only the share). The card updates on every
  vote, turns **ended** when YouTube closes the poll, then disappears after 90 seconds.
  It has no `End Poll` shortcut: Lumio can end Twitch polls only.
- **Predictions** - `Lock`, pick a `Winner`, or `Cancel (Refund)` from the card.

These shortcuts appear only with the relevant chat permission (`chat:raid`,
`chat:poll`, `chat:prediction`). The broadcaster's channel connection token
performs the action, including from a popout; a popout token's own permissions
determine which buttons its viewer sees. A failed action leaves the card in
place and shows an error. `TWITCH_CHANNEL_RECONNECT_REQUIRED` includes a hint
to reconnect the Twitch channel.

**Alerts survive a page refresh.** The alert box remembers the cards that are
currently on screen - a hype train, ad break, poll, prediction, or outgoing raid -
so a reload or navigating away and back no longer wipes them. Countdowns are anchored
to absolute end times, so an ad break or raid resumes with the correct remaining
seconds instead of restarting. A restored card looks exactly like a live one - there is
no extra badge or marker - and its numbers are the last ones this browser saw until the
next live event updates them. Anything whose end has already
passed comes back **ended** (with its wind-down countdown) or not at all - never as
"still running" - and nothing older than a few minutes reappears. A card you dismiss
with the `X` stays dismissed across the refresh, and the dismiss also propagates to a
second open window (dashboard ↔ pop-out) within a moment.

If your storage was cleared, or you open the chat on a **different device**, Lumio
additionally replays the recent Twitch event history (the last 30 minutes) to
reconstruct a running alert - an ad break, poll, prediction, hype train, or outgoing
raid. This server replay needs the `events:read` permission: the dashboard and the
normal chat pop-out have it through your login, so both behave identically. An OBS dock
opened with a **share token** that does not include `events:read` simply skips the
replay and still shows everything that browser saw itself - it never errors and never
blanks the box. YouTube polls are remembered on the device that saw them but are not
part of the server replay.

## Sending messages

The footer input supports:

- **Plain text** - `Enter` sends, `Shift+Enter` inserts a newline.
- **@mentions** - autocompletes against recent chatters.
- **Emotes** - click the smiley icon to open the **Emote Library**: Recently Used,
  then one section per channel (Twitch and Kick alike, each labelled with the
  streamer's name and avatar), then 7TV/BTTV/FFZ, then Twitch Global, YouTube
  Global, **Kick Global** and **Kick Emojis**. The platform tabs above the grid
  narrow it to one platform; the **Kick** tab shows only your connected Kick
  channels' emotes, Kick Global, Kick Emojis and the 7TV/BTTV/FFZ emotes of those
  channels. Kick has no way to list the emotes of other Kick channels you are
  subscribed to, so those do not appear. Kick emotes that only the channel's subscribers can use carry a
  small lock and the tooltip `Subscribers only`. Clicking an emote inserts its
  **name** into the input; when the message goes to Kick, Lumio sends every known
  Kick emote name as a Kick emote. Search with the placeholder `Search emotes…`.
  The emote goes where the cursor is in the message field (at the end if you never
  clicked into it), and the cursor moves behind it, so several emotes land in the
  order you pick them. Lumio adds a space before and after an emote only where one
  is missing, so it never sticks to a word and never leaves a double space. The
  library stays open after an insert; close it with the `X`, the smiley icon or
  `Escape`.

  **Narrow windows and phones.** In a window up to 480 pixels wide (a narrow chat
  popout, OBS docks, phones) the library opens as a **bottom sheet** across the full
  width, right above the message bar. The message bar stays visible and usable: you
  can see what you typed, click into it, keep typing and send while the sheet is
  open. The chat above the sheet is dimmed; tapping it closes the sheet. The sheet
  is 60 % of the window high. Drag the grip at its top to make it taller or smaller
  (with the mouse or a finger, or focus the grip and use the arrow keys); Lumio
  remembers that height on this device, and a double click or double tap on the grip
  resets it to 60 %. Drag it down past its smallest size, swipe down quickly, tap the
  dimmed chat, use the `X`, `Escape` or your phone's Back button to close it. The
  platform tabs sit next to the search field and the section shortcuts run in a row
  under it. Wider windows keep the library as a panel above the message bar.

  **On a phone with the on-screen keyboard.** Opening the library closes the
  keyboard, so the sheet has its full height; the search field does not open the
  keyboard until you tap it, and then the sheet shrinks to 60 % of what is still
  visible. When you tap into the message field while the library is open, the
  keyboard opens and the library folds into **one row of emotes** right above the
  message bar: your recently used emotes first, then the rest in library order. Tap
  one to insert it at the cursor; the keyboard stays open. **All** (or dragging the
  grip up) closes the keyboard and opens the full library again. The message bar
  always sits directly on the keyboard, in the dashboard chat and in the chat popout,
  also when you switch between the search field and the message field.
- **Reply** - click `Reply` on any message; the input shows `Replying to {name}`
  with an `X` to cancel.

Sending requires the `chat:write` permission. The send toggles next to the
input show a platform only when **both** are true for the **active account**:

- the account has a **channel connection** for that platform, and
- one of your **login connections** for that platform is assigned to the account.

A login on its own is not enough - if you have a YouTube login but the active
account has no YouTube channel, no YouTube toggle appears and nothing is sent to
YouTube. Switch to an account that has the channel connected and the toggle
returns (with your previously saved selection). A shown toggle is greyed out only
while its connection needs reconnecting (see [Reconnect required](#reconnect-required) above).

## Twitch AutoMod held messages

Twitch AutoMod holds some messages for a moderator instead of publishing them. With `chat:automod-read`, you see each hold at its original time in Multichat, with the sender, marked text and reason, such as a blocked link, blocked term or AutoMod category and level. The row shows the sender's avatar, name color and badges as Lumio last saw them when the message was held. If that look is unavailable, it uses the sender's latest chat row in the feed; a first-time chatter has the usual no-avatar placeholder and no badges. Your avatar, badges and compact-density settings apply to the held row too. With `chat:userinfo`, selecting the name opens the same user card as a regular chat message; without that right it remains plain text in every hold state. Twitch emotes and Cheers show their images and Cheer amounts, and 7TV, BTTV and FFZ emotes are matched from the channel's emote set. Links in held text are never clickable. The row shows how long it has waited; Twitch does not currently send Lumio an expiry deadline, so there is no countdown or expiry bar. Held text never goes to overlays or widgets.

**Allow** and **Deny** require separate `chat:automod-allow` and `chat:automod-deny` rights. The action uses your own Twitch sign-in, and you must be a moderator for the channel. A channel connected before the AutoMod scope was requested needs one [reconnect](./connections.md). If your stored personal Twitch sign-in lacks `moderator:manage:automod`, the dashboard replaces the decision buttons on an open hold with **Sign in with Twitch again** and shows a [connection notice](../features/connections.md#connection-notices). A member with only read access sees the hold without action buttons. Popout tokens can be granted these three rights independently; a popout keeps its Allow and Deny buttons, and a failed click shows an error toast. The backend refuses a decision with `login_scope_missing` before contacting Twitch when the missing scope is known.

An allowed message appears later as a normal chat message with a new Twitch message ID; the held row does not flash green. **Go to message** appears only when exactly one message from the same sender with identical text arrives within 30 seconds of the decision. A denied or expired hold is never published. A decision made on twitch.tv also resolves the row; if another moderator acted first, Lumio says your click came too late. After a reconnect, a hold that can no longer be found may say **No longer open**. If the queue cannot be read, the chat points you to twitch.tv. Lumio records allow and deny in the chat moderation log, with no separate audit event.

Holds survive a reload and appear when you scroll back: the chat history loads them at their original time. Open holds retain their decision buttons; resolved rows say who allowed or denied them, or that they expired. The name still opens the user card when permitted in open, allowed, denied, expired, conflict and read-only states. History rows require `feature:multichat`, `chat:read` and `chat:automod-read`; with `history:read` you see holds across the account's chat retention window, without it the last 24 hours. Members, user and service keys, and popout tokens follow the same window rule.

This queue is Twitch-only and uses EventSub and Helix, not Twitch IRC or PubSub. Kick AutoMod deletes immediately; Lumio attributes that deletion to **Kick AutoMod**, but there is no Kick queue or Allow/Deny action. Held messages can be reviewed later in the private [Stream History AutoMod tab](./stream-history.md#automod-log), subject to its retention.

## Moderation actions

Hovering any message reveals a chevron that opens the **Moderation dropdown**. Lumio
enforces a role hierarchy (broadcaster > lead moderator > moderator > user) so
moderators cannot act on the broadcaster or peers.

### What each platform supports

Moderation actions depend on what the platform's API allows. Actions a platform
cannot perform are greyed out in the dropdown and the user info card, so you can
see the limit before you click:

| Platform | Delete message | Timeout | Ban |
|----------|:--------------:|:-------:|:---:|
| Twitch   | ✅ | ✅ | ✅ |
| YouTube  | ✅ | ✅ | ✅ |
| Kick     | ✅ | ✅ (up to 7 days) | ✅ |

The same table applies to the dropdown and to the [User Info Card](#user-info-card),
whether you open the card from a chat name or from an event row. **Treatments**
(monitor / restrict, below) are Lumio-native and work on every platform regardless of
this table.

**Timeout limits.** Kick accepts timeouts in whole minutes up to **7 days**
(10 080 minutes), Twitch up to **14 days**. A longer custom value is not shortened
silently: the timeout button stays disabled and a hint shows the platform's longest
timeout.

**Kick moderation uses your Kick login.** Lumio moderates Kick with your personal
Kick login, so that login must include Kick's moderation permissions. If you logged
in with Kick before Lumio asked for them, a Kick timeout, ban or delete shows
*"Kick has not allowed Lumio to moderate yet - log in with Kick again"*. Open
**Account → Profile**, click **Reconnect** on your Kick login connection (or sign in
with Kick again) and approve the moderation permissions once. If you are not a
moderator in that Kick channel, Lumio says so instead.

If a moderation action fails for any other reason - an expired login or a platform
rate-limit - Lumio shows an error message with the reason and leaves the user's
messages in place. It never pretends a failed ban succeeded.

### Delete a single message

Click the trash icon or `Delete` in the menu. Deleted messages show
`Deleted message` in-place so the context of a conversation remains visible for
other mods. Requires `chat:delete`.

### Timeout

Presets: `1min`, `5min`, `10min`, `30min`. Pick `Custom timeout…` for any duration
in minutes, up to the platform's limit (see above). Every timeout opens a confirmation
dialog:

> Are you sure you want to `Timeout 10min` `{name}`?

Requires `chat:timeout`.

### Ban

The `Ban user` button is destructive and always requires confirmation. Bans are
permanent until reversed on the source platform. Requires `chat:ban`.

### Treatments (monitor / restrict)

Lumio-native moderation flags that travel across platforms:

- **Monitor user** - flags the user; their messages get a subtle amber badge and
  mod notes are surfaced.
- **Restrict user** - stronger warning; messages get a red badge and are
  down-weighted in alerts.
- **Remove treatment** - clears the flag.

Treatments are stored in Lumio, not on the platform, so they work on every
platform, independent of what its moderation API supports.

### Raids, polls, and predictions

The alerts overlay surfaces Twitch raids, polls, and predictions as they happen and
lets you act on the one in progress:

- **Cancel a pending raid** - requires `chat:raid`.
- **End an active poll** - requires `chat:poll`.
- **End or cancel a prediction** - requires `chat:prediction`.

Lumio does not start raids. It surfaces ongoing polls and predictions and lets
permitted viewers end or resolve them. A raid card also disappears when the
replayed `raid_done` or `unraid` event ends it after a reload.

## User Info Card

Click any username (in chat or in the event feed) to open the user's card. It opens as a
**full-page view** over the dashboard: a thin line in the platform's colour runs along the
top, the platform's colours tint the background, and the page behind stays faintly visible
through a slight blur. Close it with the `X` in the top-right corner or `Esc`.

**Layout.** The header always shows the avatar, display name (with a `Partner` /
`Affiliate` badge where the platform has one), the user's chat badges, `@username` and the
platform **ID** (click to copy; hidden in [streamer mode](./streamer-mode.md)), plus
**Open Profile** and **Refresh profile data**. On a wide screen the body splits into two
columns: on the left, **who** the user is (profile facts, treatment status and the action
buttons, which stay in view while you scroll); on the right, **what** they did (the tabs, at
full height). On a narrow screen and in the popout chat (e.g. an OBS dock) everything
stacks into one column: header, actions, then tabs.

Profile facts and actions:

- **Follower** / `Not following` badge with `Following since {date}`.
- **Follower count** - how many followers the user's own channel has, in compact form in
  your language (e.g. `12K followers`, `1,5 Mio. Follower`). Twitch only: YouTube and Kick
  profiles, and Twitch profiles whose data has not been fetched yet, show no follower-count
  line.
- **Account created** and **last updated** dates, the user's **message count** and when
  Lumio **first saw** them.
- **Bio** (where the platform exposes one).
- **Treatment status** - `Monitored` / `Restricted`, and which moderator set it.
- **Moderation actions** - Monitor, Restrict, remove treatment, **Timeout** and **Ban**,
  subject to your permissions and the platform (see below). `Timeout` expands the duration
  choices (`1m` to `1d`, or a custom value in minutes or hours) right under the buttons;
  `Esc` collapses them again. A custom value above the platform's longest timeout (Kick
  7 days = 168 hours, Twitch 14 days) is refused with a hint. Kick timeout and ban work
  here exactly as in the dropdown, from the chat card and from an event row alike. Every action asks for confirmation, and the confirmation
  appears **on top of** the card.
- **Tabs**:
  - `Messages` - recent messages by that user in this channel, with the same
    moderation controls as the live feed. Links in these messages - including
    deleted ones - are clickable and open through the `External Link` warning,
    which appears on top of the card; `Esc` closes only the warning (or the
    confirmation) and leaves the card open.
  - `Mod Notes` - private notes shared with your mod team. Create, edit, and
    delete with `chat:notes`. Great for tagging repeat offenders or regulars.
  - `Events` - every event this user has triggered (follows, subs, cheers,
    raids, superchats, tips).
- **Moderation History** - timeline of bans, unbans, timeouts, deletions, and
  treatment changes, each annotated with `by {moderator name}`. Timeout lengths show
  up to two units, e.g. `10m`, `1h 30m` or `1d 12h`.
- **Currently Banned** - shows `Banned on {date}` if the user is still banned on
  this platform.
- **Open Profile** - deep link to the user's page on the source platform.
- **Highlight** / **Hide** - one-click shortcuts to the *Highlighted users* and
  *Hidden users* filter lists (see [Hide and highlight lists](#hide-and-highlight-lists)),
  to the left of the moderation buttons. They write the **same** name-based rule the Filters
  tab does, so the change also shows up there. Both rules are **cross-platform**: the
  button hides or highlights that **name** on every platform (and any same-named account
  elsewhere) - the button tooltip spells this reach out, which is why the buttons carry
  no platform icon. Each button toggles: click again to remove the rule (or, for a
  highlight you had *switched off* in the Filters tab, to switch it back on). While a
  user is hidden the **Highlight** button is disabled - hiding wins over highlighting.
  Hiding removes all of that person's messages from the live feed at once; the button
  flips to **Hidden ✓** so you can undo it, and the `Messages` tab notes that you are
  still looking at their history even though the live feed dropped them. These buttons
  appear only in the chat's card, not when the card is opened from an event row.

Requires `chat:userinfo` (or `events:userinfo` when opened from an event row).

## Popout chat for OBS

`/popout/chat` gives you a borderless chat window perfect for an OBS browser
source, a Stream Deck, or a secondary monitor. The same moderation tools are
available subject to the token's permissions.

1. Create a popout token under **Settings → Channel → Access → Popout Tokens** and copy it.
2. Open `/popout/chat?token=YOUR_TOKEN` in OBS as a custom browser dock, or in a
   secondary browser. The [seasonal look](/user-guide/preferences#popouts-and-obs) also shows in this popout; append `&season=off`, `&seasonStrength=subtle` or `&seasonMotion=off` to the URL to change it for this popout only.
3. Use the **Settings** cog (top right) to configure:
   - **General**: `Font Size`, `Emote Size` (a `0.5×`-`2.0×` scaling factor for
     inline emotes, shown as a factor next to the slider), `Density` (`Full` or
     `Compact`; sets the line spacing for both message rows and the inline
     event lines, and `Compact` also shrinks the whole chat slightly - see [below](#inline-stream-events)), `Timestamp`, `User Badges`,
     `Platform Icon`, `User Avatars`, `Deleted Messages`, `Show GIFs` (render Twitch
     GIF-keyboard GIFs; on by default - off loads nothing from GIPHY), `Show Header`,
     `Show Chat Input`, the **Viewer list** section (on/off, position, width, font size - see
     [Viewer List](./viewer-list.md)), `Highlight Events`, `Theme`, and a **Region & language**
     block (language, time zone, date format, and time format). The Region &
     language block is a second entry point to the same global user preference as
     [Dashboard → Settings](/user-guide/preferences); it applies everywhere you
     sign in, not just to this channel, and a hint says so. In a token-authenticated
     popout it is read-only with a pointer to the settings page.
   - **Events**: a `Show Event Lines` master switch at the top (turns the inline event
     lines off at once, leaving the per-type selection below untouched - except the
     first-message marking and the Watch Streak, which always stay visible), the
     **Greeting text** for the [Greet button](#spotlight-cards-first-time-chatters-and-watch-streaks),
     then how the
     [inline stream-event lines](#inline-stream-events) look (`Avatar`, `Icon`,
     `Timestamp`, and `Label`; icon and timestamp inherit the chat's own setting until you
     set them here), and a per-type visibility list grouped by platform, where **each
     platform heading is itself an on/off switch** for that whole platform's event lines.
     **Every event type is on by default** - untick the ones you do not want inline, or
     switch off a whole platform at its heading (the always-visible types have no toggle).
     Twitch, YouTube, Kick, and Spotify groups appear when the account has the
     corresponding channel connection; StreamElements appears when a StreamElements
     token is stored. Discord, Shopify, 7TV, Copyright, and System do not depend on
     these connections. If Lumio cannot read a connection or token status, its
     group stays visible (for example, StreamElements remains listed for a
     moderator without `se-tokens:read`). Disconnecting a platform does not
     erase its saved switches or its older event lines from chat history.
   - **Filters**: `Hidden Messages` (`Remove entirely` by default, or `Show
     placeholder`), the
     *Hide* and *Highlight* lists (hidden users, command prefixes with a `Hide
     commands` switch, hidden words with a `Whole word only` switch, and highlighted
     users each with a per-user colour that can also be switched off, plus one
     `Notification sound` for the whole highlight list), `Notification Volume`, and the
     keyword-rule list for editing,
     reordering, or deleting keyword tabs.

**Show Header** also controls the Shared Chat session bar. Hiding it does not
hide the origin avatars or Shared Chat event lines, and there is no separate
Shared Chat bar switch. Display settings are stored per browser, so each
popout window keeps its own look.
Chat filters and keyword tabs are stored per account and are also mirrored so a
token-authenticated popout picks up the same filter setup without a signed-in
session.

**Which account and user a popout represents.** A popout is tied to the Lumio
account and member that its token belongs to. A token you assigned to a specific
member acts as that member; a token left on **Yourself** acts as you, the member
who created it (or who last removed its member assignment). That pairing — fixed by the token, not
by anything the popout can see on screen — decides whose channel settings the
popout loads for the account.

### Animations for this view

Open the settings gear and choose **Animations → As global, Reduced, or Off**. The choice affects this view on the dashboard and in its popout, and is stored per browser and per user/account pair. It can only reduce motion further than your [global Animations in Lumio preference](/user-guide/preferences#animations-in-lumio); an unavailable looser choice is disabled. For an OBS popout, append `&motion=reduced` or `&motion=off` (use `?` if it is the first URL parameter) to apply a stricter choice to that URL without saving it. The global preference is read-only in a token popout.

Live 7TV changes get a brief tint and emote/name motion at full speed. Reduced
keeps only short fades; Off shows the final line immediately. History and
reconnect gap-fill never animate.

## Where these settings apply

**These settings apply to you on this account.** Every Multichat setting is kept in
your browser (there is no server copy) and keyed to the pair *(you, the channel
account you are viewing)* — never global, never shared across the accounts you can
switch between, and never shared between team members of the same account. This
covers **all** of them: the display options (font size, emote scaling, row density,
whether timestamps, icons, avatars and badges show, the highlight style, how hidden
and deleted messages look, GIF playback, and the inline stream-event controls — the
event types shown, the on/off switch, per-platform toggles and their density) *and*
the channel-facing ones (your **hide and highlight lists**, **keyword tabs**, the
running **alerts overlay**, the selected **send platforms**, and the active platform
tab).

- **A different channel account starts empty.** Switch to a second account and these
  settings start from defaults — a fresh channel never inherits the viewer names or
  keyword rules you set on another one.
- **A different team member starts empty too.** Each member on the same channel
  account keeps their own view, keybinds and filters; your settings are never applied
  to a teammate.
- **The pair is resolved before anything loads**, so nothing flickers and no setting
  is ever written under the wrong account — a dashboard resolves it from your session,
  an OBS popout from its popout token's account and user.

To reuse a filter list on another channel or hand it to a teammate, move it
deliberately with [Export / Import](#save-and-transfer-your-settings) or a
[preset](#presets); there is no automatic copy between pairs.

## Save and transfer your settings

Because chat settings live in your browser, they exist only on the device (and
browser profile) where you set them. That is a problem when you set up an OBS
browser source, move to a second computer, clear your site data, switch accounts,
or want a teammate to use the same filter list. **Transfer settings** solves this
without any server.

Open the **Settings** cog, go to the **Presets** tab, and use the **Export** /
**Import** buttons below the preset cards (available in the dashboard and in every
popout). On a plan without the presets feature there is no Presets tab, so the same
Export / Import buttons appear at the bottom of the **General** tab instead.

**Export** - tick the sections you want (grouped *Chat / Events / Music*); sections
with nothing saved are greyed out. You can export settings from other surfaces too - e.g. export your Events and Music settings from the chat panel. There are four
ways to take them with you:

- **Copy code** - a single `LS1…` line you can paste into Discord, WhatsApp or an
  email. This is the easiest way to send settings to someone else. Its length is
  shown next to the button.
- **Copy link** - a share link (`…/dashboard/chat#s=LS1…`) that carries the same
  code in its address. Opening it on any device signed in to Lumio lands in that
  feature's settings with the import preview directly, no typing. Both the code and
  the link update live as you change the selection. Very long links can be broken up
  by some messengers - for those, use *Copy code* or the file.
- **Copy JSON** - the raw JSON on your clipboard, handy for support or hand-editing.
- **Download** - a `lumio-settings-YYYY-MM-DD.json` file. Best for a backup.

**Import** - pick a file, drop it onto the dialog, or paste **a JSON file, an
`LS1…` code, or a share link** into the one input field (Lumio detects which it is
automatically - a pasted link is reduced to the code it carries). A
**preview** lists every section it found and shows what each one will replace
**before** anything is written. Choose which sections to apply, then confirm.
**Import replaces a section wholesale - it does not merge** with what you have. The
page reloads after import so every view picks up the new settings.

What can be transferred: chat display, chat filters, keyword rules, events display,
event filters, and music display. What is **not** included: your theme, your
Region & language preferences (language, time zone, date and time format),
streamer mode, active account, the currently selected platform/tab, and emote
caches - those are device, user, or account properties, not feature settings.

> **Caution:**
> The code, link, JSON and file are **reversible plain text - not a hash and not
> encryption**. If you selected **chat filters** or **keyword rules**, they contain
> the viewer names you personally hid or highlighted, and your keyword lists. That is
> fine as a backup, but anyone you send the code or link to gets those names too.

Importing something from a **newer** version of Lumio, an incomplete/truncated
code, or anything that is not a valid Lumio settings file or code, is refused with
a clear message - nothing is half-written.

## Presets

Where **Transfer settings** moves settings between devices without a server, **Presets**
save named snapshots to your Lumio account so you can switch layouts and reuse them
across devices. Open the **Settings** cog and pick the **Presets** tab.

- **New preset** opens a full-screen assistant: choose which of your current settings to
  store, then name it (and optionally mark it as your default).
- Each saved preset is a card with **Load** (apply it here - the page reloads), plus icons
  to **share** it, **overwrite** it with your current settings, **rename** it, or **delete**
  it. Overwrite and delete ask for confirmation first.
- **Share** opens a dialog to copy a **code** or **share link** for that preset (the same
  transport as Export/Import), and - with the `presets:share` permission and an active
  account - a switch to make the preset **visible to every member of the account**. Members
  can then load it; they can't edit, delete or re-share it.
- A **Shared from the channel** section below your own cards lists presets teammates have
  shared into your account. You can **Load** them or **Save as your own preset** (which
  copies it into your list); loading one does not count against your quota.
- A quota line shows how many presets you have used of your plan's limit (only your own
  presets count).

Presets are per user and filtered by surface, so the Multichat Presets tab shows only chat
presets. In an OBS popout you can **load** a preset but not create, change or share one -
presets are authored in the dashboard. See the
[Setting Presets](../features/setting-presets.md) feature page for the full details.

## Permissions

| Permission        | What it unlocks                                         |
|-------------------|---------------------------------------------------------|
| `chat:read`       | View the Multichat feed and the popout                   |
| `chat:write`      | Send messages from Lumio                                 |
| `chat:delete`     | Delete individual chat messages                          |
| `chat:timeout`    | Timeout users (preset and custom durations)              |
| `chat:ban`        | Ban users                                                |
| `chat:userinfo`   | Open the User Info Card                                 |
| `chat:notes`      | Read and write mod notes                                 |
| `chat:raid`       | Cancel a pending raid                                    |
| `chat:pin`        | Pin, re-time and unpin Twitch chat messages              |
| `chat:poll`       | End an active poll                                       |
| `chat:prediction` | End or cancel a prediction                               |
| `chat:refresh_user` | Manually refresh a user's platform profile from the User Info Card (once per 10 minutes per user) |

The broadcaster / moderator hierarchy applies on top of these permissions -
moderators cannot delete the broadcaster's messages even with `chat:delete`, for
example.

## Tips & best practices

- **Use treatments instead of escalating immediately.** `Monitor User` lets you
  keep an eye on borderline chatters before committing to a timeout or ban, and
  the badge stays visible across platforms.
- **Add mod notes the moment a user does something worth remembering.** Future
  you (and every co-moderator) will thank you.
- **Separate popouts for your team.** Give each moderator their own scoped token
  with `chat:delete`, `chat:timeout`, and `chat:ban` but not `chat:notes` if you
  want to keep notes private to a smaller circle.
- **Keep the alerts overlay visible during events.** The raid/ad-break/hype-train
  cards are context you cannot get from the native platform dashboards without
  tab-switching.
- **Emote search is fuzzy.** Type the first few letters to narrow huge emote
  collections like BTTV/7TV channel sets.

## Troubleshooting

### Messages appear only from some platforms

- Check the platform toggles at the top of the feed - a toggled-off platform is
  hidden.
- Check the **Filters** tab in the Settings cog. A hide-user, hide-command, or
  hide-word rule removes matching rows from the feed entirely by default (or
  collapses them into a placeholder if you switched `Hidden Messages`).
- Open **Manage → Connections** and confirm each platform shows a green **Connected** badge.
- For YouTube, make sure the dropdown on the toggle includes the stream IDs you
  expect.

### `Connection lost - reconnecting…` banner

The WebSocket dropped. Lumio reconnects automatically with exponential backoff. If
it persists, your token is probably expired - log out and back in.

### Send box is disabled

You do not have `chat:write`, or you have no login/bot connection for the
currently-filtered platform. Check your role and confirm the bot connection under
**Connections → the platform tab → Chat bot**.

### Ban / timeout silently fails

The target may outrank you - Lumio refuses to run a moderator action against the
broadcaster or (on Twitch) against a lead moderator from a regular moderator.
You will see `Mod-only on Twitch` or the button disabled on the dropdown.

### Emotes render as plain text

The emote library has not loaded yet (check the `loadingEmotes` state) or the
channel does not have the relevant 7TV/BTTV/FFZ set linked. Click `Refresh
playlists` in the popout, or reload the page to force a refetch.

### External-link warning keeps popping up

Lumio deliberately intercepts outbound links with the `External Link` modal so a
single misclick cannot push a viewer to a malicious URL - in the live feed and in
the User Info Card's `Messages` tab alike. Approve only links you actually trust.

## Related

- [Events](./events.md) - shares the same WebSocket pipeline; mod-facing events
  surface in the chat alerts overlay.
- [Roles & Permissions](./roles-and-permissions.md) - how to design scoped mod roles.
- [Connections](./connections.md) - connect platforms and custom bot identities.
- [Overlays](./overlays.md) - show Multichat on stream with the chat widget.

---

## User Guide / Viewer List

Source: https://docs.lumio.vision/user-guide/viewer-list

# Viewer List

The viewer list is a side panel in [Multichat](./chat.md) that shows **who is in your chat right now** and **for how long**, grouped as **Broadcaster → Moderators → Bots → VIPs → Viewers**. People who left in the last 30 minutes are listed below in **Last seen**. It is available on the chat page and in the chat popout (`/popout/chat`), including OBS docks. The events page and the events popout have no viewer list.

The list counts logged-in chat participants. Logged-out viewers are invisible to every platform, so the number is less than or equal to your viewer count. Twitch is supported; Kick appears when your account has a connected Kick channel. The settings name the supported platforms.

The **Bots** group includes automatically recognised bots and accounts your channel marks under [Settings → Channel → Bots](./channel-settings.md#bots). A marked bot stays in Bots even if it is a moderator or VIP. Members with `chat-bots:edit` can manage the channel list; `chat-bots:read` allows viewing it.

## Turning it on

1. Open the chat settings (cog in the chat header).
2. On the **General** tab, find **Viewer list** and switch on **Show viewer list**.
3. Pick the **Position** (left or right) and the **Width** (*Auto* or *Fixed* with a 200–480 px slider).
4. Set the list's own **Font size** (8–32 px, default 14 px). It is independent of the chat's font size: a larger chat leaves the list as it is, and a larger list leaves the chat as it is.

Position, Width and Font size are greyed out while the list is off. Every change applies at once, on the chat page and in the chat popout.

The list is off by default. Switching it on — or applying a preset with the list on — always opens the panel. After that, the panel stays the way you left it with the header button or its **X**.

- Without a connected supported platform the section is visible but locked, and it links to your connections.
- Without the viewer list in your plan, or without the `chat:read` permission, the section is not shown.

## The header button

When the list is on, a **people** button sits directly left of the settings cog — in the chat header, in the input row when the header is hidden, or in the floating corner group when header and input bar are both hidden. The button is an icon only (green while the panel is shown); the count lives in the panel head.

- **Green** = panel shown, **grey** = hidden.
- A click hides or shows the panel; the **X** in the panel head hides it too. The choice is saved **in this browser** for your account: after a reload the panel stays hidden or shown, and the chat page and the chat popout in the same browser follow it. An OBS dock has its own browser storage and keeps its own choice.
- While the panel is hidden, Lumio does not follow the chat's viewers; the list refreshes as soon as you show it again.
- The hide is not part of your display settings: presets, export and import never carry it. Applying a preset or an import of the chat display, or switching the list off and on again in the settings, shows the panel again.

## Reading the list

- The head shows **In chat · count** (people in the chat now; *Last seen* is not counted), when the platform list was last updated, and the search box — with two or more platforms, the platform filter sits left of it. A divider under the search separates the head from the list; only the list scrolls.
- Status notes (reconnect hint, source availability, or a platform's entry cap) appear below the divider, above the list.
- Groups have sticky headers with counts and can be collapsed; collapsed groups are remembered.
- Inside a group names are sorted alphabetically; newcomers appear at their alphabetical place.
- Each row has two lines next to a round avatar (the initial in the user's colour until the avatar arrives): the display name, and below it **how long the person has been in the chat** — *just arrived*, *here 48 min*, *here 1 h 52 min*. Twitch lurkers can appear and get a time too; Kick's source lists only recent writers, so Kick lurkers do not appear. When a Twitch display name uses a non-Latin script (for example こさむん), the login follows the name in grey, the same rule as in the chat.
- The times count up on their own (about every 30 seconds) and start when the person entered the chat during the current stream.

### Last seen

Someone who leaves the chat moves from their group into **Last seen** at the bottom of the list, below Viewers. They stay there for 30 minutes, greyed out, with an eye icon and the time they were last seen — *last seen 4 min ago* — newest first; then they disappear. If they come back in that time, they move back to their group and their time starts again.

- *Last seen* is collapsible like the other groups, and the collapsed state is remembered.
- Its people are never part of the counts.
- A click still opens their user info card.
- A small speech-bubble mark means the person wrote in the last two minutes.
- Use the search box to filter by display name or login.
- With two or more supported platforms connected, a **platform filter** sits left of the search box: an icon button (stacked layers for *All platforms*, otherwise the chosen platform's icon) that opens a list of *All platforms* plus every connected platform. Pick one platform to show only its people — the groups, their counts, the head count and the search results follow at once. The choice is remembered; if that platform is no longer connected, the list shows all platforms again. Every row then also shows its platform icon at the end of the row (the *Auto* width makes room for it). With one platform there is no filter and no icons.
- The whole list follows its own **Font size** (Viewer list section of the chat settings), not the chat's: the head (title and count, *updated …*, platform filter, search box), the group names and their counts, the loading animation, and every row — name, time icon and time, avatar, platform icon and row height — grow and shrink with it.

Click a name to open the **user info card** — the same card as a click on a name in the chat. It also works for people who have not written anything yet. Without the `chat:userinfo` permission the rows are plain text.

### How fast does it update?

People who write appear **immediately**. Twitch also lists people who only watch with a snapshot every 30 s, plus Twitch's own delay — often 30 s to a few minutes. Kick checks its recent-writer list every 60 s and does not list lurkers. Leaving can show up after the platform's delay, so a *last seen* time may be later than the moment the person actually left.

### States

| What you see | Meaning |
|---|---|
| Loading animation | The list is waiting for its first snapshot. With the season look on it shows the season's icons instead of the spinner. If no platform has delivered a snapshot after 15 seconds, the empty state appears instead |
| **Only people who write are listed. Reconnect Twitch once …** | The Twitch connection predates the viewer-list permissions. Reconnect it once under **Connections** for the full list |
| **Kick list temporarily unavailable — showing people who write** | Kick's list source cannot be read. Recent writers still appear, but people known only from the list move to *Last seen* after two failed polls. The hint appears only when Kick is included in your platform filter. No reconnect is needed; Twitch keeps working |
| **Nobody in the chat right now** | The platform reports an empty chat |
| **5,000 of 12,400** or **100 of 538** | The platform supplied a larger total than the entries it lists. Lumio caps Twitch snapshots at 5,000; Kick's ordinary chatter group stops at 100, while its role groups are complete. The head still shows the full count |

## Width and position

- **Auto** fits the widest row — the longer of the name and its time line (200–320 px at the default 14 px list font size; with a larger list font the upper limit grows with it, up to 480 px). Changing the list font size re-fits *Auto* at once; a fixed width stays as it is. It grows during a session but never jumps on single arrivals; it fits again the next time the panel opens.
- **Drag the inner edge** of the panel to resize it, in any mode — no detour through the settings. The panel edge follows the pointer directly (no pixel readout while dragging; the slider in the settings shows the value). Releasing stores a fixed width (the settings slider follows). **Double-click** the edge to go back to *Auto*.
- Keyboard: focus the edge, then use the arrow keys (±8 px) and **Home** for *Auto*.
- The chat always keeps at least **420 px**. The panel docks beside the chat while the chat area is at least 420 px + the panel width; otherwise it lies over the chat as a drawer. A 48 px strip of chat stays visible next to the drawer — click it or press **Esc** to hide the drawer. The drawer has a resize edge from 288 px chat-area width on.
- With the list on, the **Open popout** button on the chat page opens the popout wide enough to dock it (740 px with *Auto* at the default list font size).

The chat page and the chat popout share the settings in the same browser. An OBS dock has its own browser storage; use [presets](../features/setting-presets.md) to carry the setup over.

## Presets and export

On/off, position, width, font size, collapsed groups and the platform filter are part of the chat display settings, so presets, export and import carry them. The export dialog summarises them as e.g. *Viewer list on · right · Auto*. The header-button hide is never exported.

## Motion

The panel slides in and out from its side, new rows fade in, leaving rows fade out. Someone who leaves fades out of their group and fades in under *Last seen*; the list closes the gap smoothly instead of jumping. Large batches of changes (more than 20 at once) change without animation. Under **Reduced** or **Off** — from the system setting, **Animations in Lumio**, or the chat's own **Animations** setting — everything changes instantly.

See [Chatter List](../features/chatter-list.md) for how the list is built.

---

## User Guide / Members

Source: https://docs.lumio.vision/user-guide/members

# Members

Lumio is built around team-managed accounts. The **Members** tab of the channel settings is where you invite teammates (moderators, editors, co-hosts), change the role of existing members, and revoke invitations that are no longer needed. This guide walks through every tab, dialog, and invite method.

## Where to find it

- Navigation: **Settings → Channel → Members**
- Short link: `/dashboard/settings/channel/members` (opens the area over the dashboard home)
- Required permission to open: `members:read`

The tab starts with the description _"Manage your team and invitations"_. If you have `members:create`, an **Invite** button with a user-plus icon is shown on the right of it (full width on phones).

## Quick start

1. Click **Invite** at the top of the Members tab.
2. In the wizard, pick **Invite Link** (default) as the method.
3. Click **Next**, pick the role (e.g. **Moderator**), click **Next** again.
4. Choose how long the link should be valid and how many people can redeem it (default: 7 days, 1 use).
5. Click **Create Invite**, copy the generated URL, and send it to your teammate.

They open the link, sign in to Lumio, and click **Accept Invite** - they are now a member of your account.

## Tabs

The page has two tabs, each with a count badge: **Members** and **Invites**.

### Members tab

Lists all current members of the account. For each member you see:

- Avatar and display name (plus a **You** badge if it is you).
- Badges for their assigned platform identities (Twitch/YouTube/Kick), when they have any. Discord sign-in connections cannot be assigned to a channel.
- **Role** on the right - either a coloured badge or a dropdown if you can change it.
- **Joined** date.
- A red **Remove** button (person-minus icon) if you have `members:delete` and the member is neither the owner nor yourself.

#### Changing a role

If you have `members:edit`:

1. Click the role dropdown next to the member.
2. Pick a new role from the list. The dropdown shows each role's colour dot, name, and short description.
3. The change is saved immediately. The page refreshes to reflect the new role.

The Owner role cannot be assigned to anyone - it is reserved for the original creator of the account and appears as a static badge labelled **Owner**.

#### Removing a member

1. Click the red **Remove** icon to the right of the member row.
2. A confirmation dialog appears: _"Are you sure you want to remove {name} from this account?"_
3. Click **Remove** to confirm, or **Cancel** to abort.

Removing a member revokes their access immediately. They stay signed in to Lumio but no longer see this account in their account switcher.

The account owner's row never shows a role dropdown or a remove button - the owner cannot be changed or removed from within the UI.

### Invites tab

Lists every invite ever created for the account, filterable by status. Above the list there are four filter pills with count badges:

- **All** - every invite.
- **Pending** - accepting still possible.
- **Accepted** - already redeemed.
- **Expired** - past validity, or reached max uses.

Each invite row shows:

- An icon indicating the type: **link** icon for shareable link/token invites, **user-plus** icon for direct invites.
- The label - **Invite Link** for anonymous invites, or the email/code/user for direct invites.
- A coloured status badge (**Pending**, **Accepted**, or **Expired**).
- The creator (_"by {name}"_) and the expiry time.
- The target role, as a coloured badge.
- For pending link invites: a **Copy** button (with copy/check icon feedback).
- A red **Trash** button to revoke if you have `members:delete`. It is not shown on **Accepted** invites - deleting the invite row would not remove the resulting membership, so manage those from the **Members** tab instead.

Accepted and expired invites are dimmed to make pending ones easier to spot.

## Invite wizard

The invite wizard is a four-step modal launched by the **Invite** button. The top bar shows _"Step X of 4"_.

### Step 1 - Method

Three cards side by side. Click to select.

- **Invite Link** _(default)_ - _"Generate a shareable link."_ Anyone with the link can redeem it, subject to expiry and max uses.
- **Invite Token** - _"Generate a code to share manually."_ A short token the recipient types in their dashboard. Use when you cannot send a URL (voice only, on-stream).
- **Invite Person** - _"Search by username, email, or platform."_ Requires the person to already have a Lumio account. A search box appears; type at least 3 characters.

For **Invite Person**, the search hits the global Lumio user directory and returns matching users with their avatar, display name, and assigned platform badges (Twitch/YouTube/Kick). Click a result to select it; a check-mark shows which user is selected.

You cannot advance to step 2 until a method is fully chosen. For **Invite Person**, that means a specific user must be selected.

### Step 2 - Role

A single dropdown listing every role you can assign. Each item shows the role colour, name, and description. The Owner role is excluded - a note reads _"Owner role cannot be assigned."_

The default selection is the first non-owner role on the account.

### Step 3 - Options

Two fields side by side plus a summary card.

- **Validity** - dropdown with fixed choices: **1 hour**, **24 hours**, **7 days** _(default)_, **30 days**, **Never**.
- **Max Uses** - dropdown with **1** _(default)_, **5**, **10**, **Unlimited**. For **Invite Person** this field is greyed out and fixed at `1` - direct invites are always single-use.

The summary card below repeats your choices so you can sanity-check before creating: method, role, validity, max uses.

Click **Create Invite** to submit. Errors are shown inline in a red banner.

### Step 4 - Result

Depending on the method, you see:

- **Invite Link** - a read-only URL field (`{origin}/invite/{code}`) with a **Copy** button. A short note shows the validity you picked.
- **Invite Token** - a monospaced token field with a **Copy** button and the hint _"Share this token - the recipient enters it on their dashboard to join."_
- **Invite Person** - a confirmation card with the user's avatar, name, and target role badge. A notification has been sent inside Lumio.

When you invite an existing Lumio user via the user search, they receive an in-dashboard notification with Accept and Decline buttons. If the invitee has a verified email address on file, the same invite email is sent in addition (otherwise the dashboard notification is the only channel).

Click **Close** to dismiss the wizard. The Invites tab now shows the new invite in the **Pending** filter.

## Accepting an invite

From the invitee's point of view:

1. They open the invite link (`{origin}/invite/{code}`) or enter the token on the invite-accept page.
2. The **Invite Details** screen shows the account name, the role they will receive, and who invited them.
3. If they are not signed in, they click **Sign in to join** and complete login. They are redirected back to the same invite.
4. They click **Accept Invite** to confirm.
5. A success screen shows _"You are now a member of {account} as {role}"_ with a **Go to Dashboard** button.
6. Their active account switches automatically to the new account.

Specific failure screens are shown for expired invites, fully-used invites, invalid codes, when the user is already a member, and when a targeted invite belongs to a different user ("This invite was issued to a different user").

## Permissions

| Action                               | Required permission |
| ------------------------------------ | ------------------- |
| Open the Members tab                 | `members:read`      |
| Invite new members                   | `members:create`    |
| Change a member's role               | `members:edit`      |
| Remove a member / revoke an invite   | `members:delete`    |

Owners implicitly have all four. If you cannot see the **Invite** button, the role dropdown, or the delete icons, your role is missing one of these permissions - ask the account owner.

## Tips and best practices

- **Start with the three default roles** (Owner, Administrator, Moderator). Only create custom roles when the defaults cannot express what you need.
- **Use short validity for public links.** A 7-day link floating in a Discord server is a risk - a 1-hour link for onboarding a specific person is safer.
- **Prefer Invite Person for long-term team.** Direct invites bind to a specific Lumio user and cannot be forwarded or leaked.
- **Use Invite Token for voice-only handoffs.** Much easier to read over voice than a 40-character URL.
- **Set max uses to match the intent.** A single-use link works well for one moderator; a multi-use link for a small team. Do not default to Unlimited.
- **Audit the Invites tab monthly.** Revoke anything pending you do not remember creating.

## Troubleshooting

**Invite button is missing.**
You do not have `members:create`. Ask the account owner or someone with role-editing rights.

**Role dropdown is missing but I see the member row.**
You have `members:read` but not `members:edit`.

**Invite link says "Invite Expired" immediately after creating it.**
Your system clock is wrong, or the invite was created with an expiry of `1 hour` while you were in a very slow network round-trip. Create a new one with a longer validity.

**"Invite Full" on accept.**
The `max_uses` was reached. Ask the inviter to create a new invite or raise the limit.

**"Already a Member" on accept.**
The invitee is already part of the account. They can switch to it from the account picker in the top bar.

**Cannot find a user via Invite Person search.**
The search requires at least 3 characters and looks at display name, email, and connected platform identities. The user must have signed in to Lumio at least once - users who have never signed in are invisible. Use **Invite Link** or **Invite Token** instead.

**A removed member still sees the account.**
Removal takes effect immediately on the server, but their browser tab may keep a cached account list until it reloads. Ask them to refresh.

## Related

- [Dashboard](./dashboard.md) - overview of everything members can access.
- [Roles and permissions](../features/roles.md) - design roles that match your team's responsibilities.
- [Connections](./connections.md) - what members can manage once they have `connections:*` permissions.

---

## User Guide / Roles & Permissions

Source: https://docs.lumio.vision/user-guide/roles-and-permissions

# Roles & Permissions

Lumio uses role-based access control (RBAC) to decide exactly what every team member can see and do inside your account. Roles are **account-scoped**: the same user can be a Moderator on your channel and an Owner on a friend's channel, and Lumio tracks that separately.

**Who needs this guide?**

- **Account owners** setting up a team for the first time.
- **Administrators** who need to create custom roles (for example, an "Editor" that can manage overlays but not chat).
- **Members** who want to understand why a page or button is hidden for them.
- **Popout-token users** configuring OBS browser-source docks with the right permissions.

## Where to Find It

- **Roles** live under `Settings → Channel → Roles` (`/dashboard/settings/channel/roles`). You need `roles:read` to see the area and `roles:edit` / `roles:delete` to modify roles.
- **Members** live under `Settings → Channel → Members` (`/dashboard/settings/channel/members`). You need `members:read` to see the area and `members:edit` to change someone's role.
- **Your own permissions** are reflected everywhere - buttons, nav items, and entire pages simply disappear when you lack a permission, and protected pages show a "No Access" state with the message "Contact the account owner to get access."

## Quick Start

1. The account creator is always the **Owner** - they start with every permission.
2. Two other default roles exist for every new account: **Administrator** and **Moderator**.
3. To bring someone onto your team:
   - Open `Settings → Channel → Members`, click **Invite**.
   - Choose a method: **Invite Link**, **Invite Token**, or **Invite Person** (search by username/email/platform).
   - Pick a role (the Owner role cannot be assigned this way - it's reserved for the account creator).
   - Configure validity (1 hour, 24 hours, 7 days, 30 days, or Never) and max uses.
   - Share the link or token.
4. If the three default roles don't fit, create a custom role under `Settings → Channel → Roles → Create Role` and pick exactly the permissions it needs.

## How It Works

Every action in Lumio - sending a chat message, saving an overlay, creating an invite - is guarded by a **permission string** in the form `resource:action` (for example `chat:ban`, `overlays:edit`). Wildcards like `*` or `chat:*` are **not** supported; permissions are always granular.

When a user performs an action, Lumio looks up the roles assigned to them on the current account, unions their permissions, and checks whether the required string is present.

- The **backend** enforces permissions on every GraphQL resolver and REST handler, so switching protocols can't bypass a guard.
- The **frontend** uses the same permission list to hide nav items, dim disabled buttons, and render graceful "No Access" pages instead of raw 403 errors.
- Permissions are **cached in Redis** per user + account for performance. The cache is automatically invalidated whenever a role's permissions change, a member is added/removed, or a role is reassigned, so changes take effect within seconds.

### Role anatomy

Every role has:

| Field | Purpose |
|-------|---------|
| `name` | Human-readable label shown in the UI (e.g. "Moderator", "Content Editor"). |
| `slug` | Machine identifier auto-generated from the name (e.g. `content-editor`). Used for translations and API calls. |
| `description` | Free-text hint shown in the role list. |
| `color` | Hex color used in the member list badge. |
| `is_system` | If `true`, the role is protected: it can't be deleted and, for Owner, can't be edited. |
| `permissions` | The list of `resource:action` strings granted by this role. |

## Default Roles

Lumio seeds three roles into every new account. All slugs are stable and match those checked by the backend. Accounts created earlier may have a fourth role named `viewer`: unused ones were deleted, while those with a member or a redeemable invite became ordinary custom roles with unchanged permissions.

### Owner (`owner`)

- `is_system: true` - cannot be deleted and is the only role that cannot be revoked from the account creator.
- Holds **every** account permission including `account:delete` (dissolve the account) and `plan:edit` (change billing).
- Automatically assigned to whoever created the account; ownership can be transferred via the settings page, but the role itself always exists.

### Administrator (`administrator`)

- Same broad access as Owner, **minus** `account:delete`, `plan:read`, `plan:edit` and `extension-dev:payouts`.
- Can manage team, overlays, chat, automations, connections, etc. - essentially everything a co-streamer or production lead needs.
- Can be edited (it is not a system role), but like every seeded default role it has no delete button.

### Moderator (`moderator`)

- Built for chat mods: `chat:read`, `chat:write`, `chat:userinfo`, `chat:delete`, `chat:ban`, `chat:timeout`, `chat:notes`, `chat:raid`, `chat:pin`, `chat:poll`, `chat:prediction`, `chat:refresh_user`, `chat:automod-read`, `chat:automod-allow`, `chat:automod-deny`.
- Events: `events:read`, `events:create` (fire test events), `events:userinfo`.
- Read access to overlays, connections, uploads, rewards, widgets, sounds, bot-modules, bot-commands, bot-connections, account chat bots, and the OBS config (`obs:read`).
- Spotify: read + playback + queue + playlist + device (no volume, no worker start/stop).
- Automations: read + execute + history (cannot create or edit).
- Members/roles: read-only (`members:read`, `roles:read`) - mods can see the team but not change it.
- Sessions: can view and revoke their own active sessions.
- Copyright: the viewer-style actions only - `copyright:vote`, `copyright:report`, `copyright:recommend`.
- Extensions: `extension-store:read`, `extension-store:review`, `extension-data:read`.
- Sounds: `sounds:read` + `sounds:play`.
- Stream History: `history:read` + `history:export`.
- Setting Presets: `presets:share` (may share their own presets with the account).
- Public Stats: `public-stats:read` (view publicness settings; cannot change them).

## Custom Roles

If the defaults don't fit - the most common case is "I want a role that can do X but not Y" - create a custom role.

1. Open `Settings → Channel → Roles`, click **Create Role**.
2. **Step 1 - Role Details:** enter a name, an optional description ("What can this role do?"), and pick a color. The slug is auto-derived.
3. **Step 2 - Permissions:** check exactly the permissions you want. They are grouped by category (Events, Overlays, Spotify, Chat, …). The UI shows a running count at the bottom: "N permissions selected".
4. **Step 3 - Summary:** review and click **Create Role**.

Editing works the same way - click the pencil icon on the role card and the three-step wizard reopens with the current values; in edit mode you can jump to any step and save from there. The Owner role shows a **System** badge and has no pencil icon. None of the three seeded default roles show a delete icon - only custom roles you create can be deleted.

To assign a custom role: go to `Settings → Channel → Members`, find the member, and change their role from the Role column. You need `members:edit` to do this.

## Permission Categories

Platform operators can be granted the admin-scope `support:verify` permission to view and check a user's hourly support code in the Admin app. It does not belong to a channel role. Resetting a user's 2FA is a different operator action guarded by admin `users:edit` and requires a reason.

Permissions are grouped into categories that double as UI section headers in the role editor. Below are the categories and the `resource:action` strings inside each.

### Granular pattern

Almost every category follows the same shape:

- `resource:read` - see the data.
- `resource:create` - make new entries.
- `resource:edit` - modify existing entries.
- `resource:delete` - remove entries.

**One historical exception uses `:write` instead of granular create/edit/delete:**

- `chat:write` - permission to send chat messages. (Deleting chat messages is separate: `chat:delete`.)

Everywhere else, stick to the granular triple.

### Events

- `events:read` - view the events feed and history.
- `events:create` - emit test events.
- `events:edit` - hide the buyer name of a Shopify order in the events feed. Owner and Administrator have it by default.
- `events:userinfo` - open the user card from an event row.

### Overlays

- `overlays:read`, `overlays:create`, `overlays:edit`, `overlays:delete`.
- `overlays:access-read` - read per-overlay access entries/candidates and see all overlays (access-manager visibility; Owner and Administrator only).
- `overlays:access-grant` - grant (set) per-overlay access for a user (Owner and Administrator only).
- `overlays:access-revoke` - revoke per-overlay access for a user (Owner and Administrator only).

### Widgets

- `widgets:read`, `widgets:create`, `widgets:edit`, `widgets:delete` - standard widget instance CRUD.
- `widgets:access-read` - read per-widget access entries/candidates and see all widgets, including ones set to `none` for you (access-manager visibility; it does not grant editing; Owner and Administrator only).
- `widgets:access-grant` - grant (set) per-widget access for a user (Owner and Administrator only).
- `widgets:access-revoke` - revoke per-widget access for a user (Owner and Administrator only).

### Sounds

- `sounds:read`, `sounds:create` (upload), `sounds:edit`, `sounds:delete` - the sound library used by alerts and automations.
- `sounds:play` - trigger playback of a sound. Moderators get `sounds:read` + `sounds:play`.

### Extension Store

- `extension-store:read` - browse the store and the Installed list (Owner, Administrator, Moderator).
- `extension-store:install`, `extension-store:uninstall`, `extension-store:configure` - install, remove and configure extensions on this account (Owner and Administrator only).
- `extension-store:review` - write a store review for an extension.

### Extension Developer

- `extension-dev:read` - open the developer dashboard.
- `extension-dev:create`, `extension-dev:edit`, `extension-dev:delete` - manage your own extensions.
- `extension-dev:publish` - submit and publish versions.
- `extension-dev:analytics` - see install and usage analytics for your extensions.
- `extension-dev:payouts` - manage payout details and request payouts (Owner only).

These only matter once your user has been approved as a developer - see [Developer Application & Team Roles](#developer-application--team-roles).

### Extension Data

- `extension-data:read` - read data from an installed extension's server query functions (Owner, Administrator, Moderator).
- `extension-data:edit` - insert / patch / delete data through an installed extension's server functions (Owner and Administrator only).
- These gate only direct calls from the dashboard editor or the `lumio run` CLI. Widgets running in a Browser Source use the extension install's own scope and are unaffected.

### Stream History

- `history:read` - view the session list, reports and time-series stats, and the current Sub count of each connected channel (Owner, Administrator, Moderator).
- `history:export` - export filtered lists and finalized reports as CSV / PDF / TXT / JSON (Owner, Administrator, Moderator).
- `history:share` - create, extend and revoke shareable report links (Owner and Administrator only).
- `history:delete` - delete stored sessions (Owner and Administrator only).
- `history:revenue-read` - read estimated revenue and assumptions and include revenue in shared reports (Owner and Administrator only).
- `history:revenue-edit` - edit revenue assumptions (Owner and Administrator only).
- `history:keywords-edit` - add, change and remove tracked keywords (Owner and Administrator only). `history:read` also permits listing keywords and testing a pattern.
- All seven are gated behind the Stream History feature (available on the Free and Pro plans).

### Setting Presets

- `presets:share` - share one of your own setting presets with the members of your active account, so the team can load ("use") it (Owner, Administrator, Moderator).
- Only *sharing* is gated: creating, editing and loading presets is per-user and needs no permission, and reading the shared section needs only account membership.
- Gated behind the Setting Presets feature. When you share a preset, every member of the account can see and load it - the confirmation says so.

### Public Stats

- `public-stats:read` - view your channels' publicness settings for the public Stats app (Owner, Administrator, Moderator).
- `public-stats:edit` - toggle a channel's publicness (opt out / opt back in) and hide or show its chatter leaderboard (Owner and Administrator only).
- Both are gated behind the Public Stats feature (available on the Free and Pro plans). Publicness is **public-by-default**: a channel is listed until its broadcaster opts out.

### Crawler

Platform-operator controls for the public stats crawler, exposed in the Admin app (and gated on `admin:access` to reach it). These are **admin-scope** permissions (ZAF-725), assigned via admin roles (seeded to `system_admin`) - they are **not** account role permissions, so no account owner/administrator/moderator holds them.

- `crawler:scope-read` / `crawler:scope-edit` - read and set which live channels the crawler covers (`lumio`, `list`, `lumio_plus_list`, or the opt-in `global` sweep). The default is the bounded `lumio_plus_list`.
- `crawler:watchlist-read` / `crawler:watchlist-create` / `crawler:watchlist-delete` - view and curate the crawl watchlist (the `list` component of the scope).

Each scope change or watchlist edit is recorded in the operator audit log.

### Audit Log

- `audit-log:read` - view this account's [Audit Log](./audit-log.md): role and permission changes, member-role assignments, channel connections, and account-scoped GDPR erasures (Owner, Administrator). This account-scope permission is separate from the Lumio-internal admin audit log, which uses a same-named admin permission. It is not needed for **Account → My Activity**, which is self-only for every signed-in user.

### Spotify

- `spotify:read` - now playing, queue, devices, playlists, search.
- `spotify:playback` - play / pause / skip / shuffle / repeat.
- `spotify:volume` - change playback volume (hides the volume slider when missing).
- `spotify:queue` - add tracks to the queue.
- `spotify:playlist` - create / rename / delete playlists, manage tracks.
- `spotify:device` - transfer playback between devices.
- `spotify:worker` - start / stop the manual Spotify connect worker.

### Chat

- `chat:read`, `chat:write`, `chat:userinfo`, `chat:delete`, `chat:ban`, `chat:timeout`, `chat:notes`, `chat:raid`, `chat:pin`, `chat:poll`, `chat:prediction`, `chat:refresh_user`, `chat:automod-read`, `chat:automod-allow`, `chat:automod-deny`.
- `chat:automod-read` shows held Twitch messages in Multichat. The AutoMod tab in Stream History additionally requires `history:read`; allow and deny have their own permissions and use your Twitch sign-in. A popout token can carry the three live AutoMod permissions, but cannot open the history log.
- `chat:refresh_user` - manually refresh a user's platform profile (avatar, bio, follow status) from the UserInfoModal. Rate-limited to once per 10 minutes per user. Available to Owner, Administrator, and Moderator.
- `chat:userinfo` also controls whether the `{{username}}`, `{{displayName}}`, `{{avatarUrl}}`, and `{{userId}}` automation template variables resolve (see [Automation Templates](./automation-templates.md)).

### Connections

- `connections:read`, `connections:create`, `connections:edit`, `connections:delete` - for Twitch/YouTube/Kick channel connections, Discord, Spotify, StreamElements, the Shopify store, etc. `connections:edit` changes the Shopify customer label. `connections:read` also controls the dashboard's channel status and the `channelStatus` / `GET /v1/channel-status` reads; `spotify:read` controls Spotify music and manual status separately.

### Settings

- `settings:read`, `settings:edit`.

### Members

- `members:read` - see the members and invites tabs.
- `members:create` - create invite links / tokens / direct invites, search users.
- `members:edit` - change someone's role.
- `members:delete` - remove a member or revoke an invite.

### Roles

- `roles:read`, `roles:edit`, `roles:delete`.

### Uploads

- `uploads:read`, `uploads:create`, `uploads:delete`. Plan limits apply on top - see [Billing & Subscription](./billing.md) for the current per-file and total storage limits.

### Rewards

- `rewards:read`, `rewards:create`, `rewards:edit`, `rewards:delete` - channel-point rewards and their handlers.

### Tokens

- `tokens:read`, `tokens:create`, `tokens:delete` - view, create, and revoke **popout tokens** (OBS browser-source docks). Managed under the `feature:tokens` feature gate.
- `tokens:edit` - edit popout token labels, expiry, user assignment, and permissions.

### API Keys

Both personal **user API keys** (`lm_usr_…`) and account **service keys** (`lm_svc_…`) share one dedicated permission family, separate from popout tokens. The **Settings → Channel → Access → API Keys** page uses these permissions plus the `feature:apikeys` feature gate - see [API Keys](./api-keys.md) for the personal-vs-service distinction.

- `apikeys:read` - view API keys.
- `apikeys:create` - create a new key (scoped within your own permissions - a key can never exceed what its creator holds).
- `apikeys:edit` - rename a key **or rotate its secret**. The scopes and expiry are immutable once minted; you can change the display name and regenerate (rotate) the secret in place. Rotation returns the new full key once and invalidates the old secret immediately.
- `apikeys:delete` - revoke a key.

Service keys introduce **no new permission** - they reuse the same `apikeys:{read,create,edit,delete}` family. The one behavioural difference is ownership: a service key belongs to the account and keeps working after the member who created it leaves, whereas a personal key stops the moment its owner is no longer a member.

**Operator management (support).** Lumio platform operators and support staff can view, edit (label + scopes), rotate, and revoke **any** account's or user's API keys from the admin app, under the separate admin-scope `account-apikeys:{read,edit,rotate,delete}` family (never assignable to a tenant role). This is distinct from the account-scope `apikeys:*` above - an operator editing a key can never push it above the key's own principal (a personal key stays capped to its owner's permissions). See [Admin → API Keys](../admin/api-keys.md).

### Automations

- `automations:read`, `automations:create`, `automations:edit`, `automations:delete` - standard automation CRUD. `automations:edit` also covers renaming, toggling enabled, and modifying nodes/edges.
- `automations:execute` - manually trigger and start/stop automations.

### Account & Plan

- `account:read`, `account:edit` (the channel name and picture: source, own name, own picture), `account:delete` (dissolve the whole account - Owner only by default).
- `plan:read`, `plan:edit` (subscription / billing - Owner only by default).

### Sessions

Session management is **not** an account-role permission. Every authenticated user can view and revoke their **own** active browser sessions regardless of account role, and regardless of whether an account is selected in the account switcher at all. The former `sessions:read` / `sessions:delete` role permissions were removed in ZAF-1094 - they gated nothing.

### OBS

- `obs:read`, `obs:edit`, `obs:delete` - the OBS WebSocket remote-control configuration.

### Copyright

- `copyright:read`, `copyright:edit`, `copyright:delete` - this account's own copyright review lists.
- `copyright:vote`, `copyright:report`, `copyright:recommend` - viewer-style actions (moderators get these but not edit/delete).
- `copyright:moderate` - approve/dismiss community vote candidates into the **global** cross-account blocked/safe catalogue. This is a **platform-operator (admin) permission**, not an account-role permission: it is held only by platform staff via the admin (`system_admin`) role, never by a tenant Owner or Administrator. It was moved out of account scope in ZAF-742 because it writes the shared global catalogue, not your own account's lists (which `copyright:edit` covers).

### Bot Modules / Bot Commands / Bot Connections / SE Tokens

- `bot-modules:read`, `bot-modules:edit` - link protection, spam, word filter, timed messages.
- `bot-commands:read`, `bot-commands:create`, `bot-commands:edit`, `bot-commands:delete`.
- `chat-bots:read` - see the channel bot list and automatically recognised bots (Owner, Administrator, Moderator).
- `chat-bots:edit` - mark and unmark platform accounts as bots (Owner and Administrator). See [Channel settings → Bots](./channel-settings.md#bots).
- `bot-connections:read`, `bot-connections:create`, `bot-connections:delete` - custom bot identities.
- `se-tokens:read`, `se-tokens:create`, `se-tokens:delete` - StreamElements tip-jar tokens.

### Login Assignments (User-Level)

| Permission | Description |
|-----------|-------------|
| `login-assignments:read` | View which login connections are assigned to the account (all users) |
| `login-assignments:create` | Assign login connections for any user on the account |
| `login-assignments:delete` | Remove login connection assignments for any user |

Every user can always manage their own login assignments without these permissions. The permissions above are user-level and control access to other users' assignments on the same account.

## Developer Application & Team Roles

Becoming a developer on Lumio requires an application. The developer application flow and team roles use a separate permission layer from account roles.

### Becoming a Developer

1. Navigate to **Account > Developer** (`/dashboard/settings/developer`).
2. Fill out the application wizard: choose **Solo** or **Team**, provide a display name, URL slug, description, motivation, and what you plan to build.
3. Submit the application for review.
4. A Lumio admin reviews the application and approves or rejects it with notes.
5. On approval, a developer profile is created. For team applications, a team is also created with default roles.

The `me` query exposes an `isDeveloper` boolean field that is `true` when the user has a developer profile or has the admin `extension_dev_mode` override. This field controls access to the developer dashboard.

### Developer Team Roles

Developer teams use their own RBAC system, separate from account roles. Each team has custom roles with granular `team-*` permissions covering extensions, versions, secrets, testers, members, settings, and payouts.

Three default roles are seeded for every new team:

| Role | Description |
|------|-------------|
| **Owner** | Full team access. System role, cannot be deleted. |
| **Admin** | Manage extensions and members. Cannot edit team settings, payouts, or remove members. |
| **Member** | Edit extensions, create and upload versions, and view analytics. Cannot submit a version, delete an extension, or manage or list testers and private access. |

For team-owned extensions, the role controls each action after Lumio confirms you belong to the owning team. A missing grant returns `Missing team permission: <permission>`; role changes take effect on your next request. A solo extension has no team-role check. The Owner and Admin roles can submit versions and manage testers; a custom role can grant those actions selectively.

Custom team roles can be created through the team settings page. The team role editor works the same way as the account role editor: pick a name, description, and a set of `team-*` permissions.

### Notifications

The developer lifecycle includes email and in-app notifications for:

- Application submitted, approved, or rejected
- Extension created, version submitted/approved/rejected/published, extension suspended
- Access granted or revoked, tester invited/removed, tester feedback
- Team invite sent/accepted, team member removed, team role changed

## Concrete Recipes

### "A mod who can ban but not touch overlays"

The default Moderator already does this - they have `chat:ban` + `chat:timeout` + `chat:delete`, and only `overlays:read`. If you want to also block overlay viewing, create a custom role with the Moderator's permissions minus `overlays:read`.

### "A content editor who designs overlays but should never moderate chat"

Create **Content Editor** with:

- `overlays:read`, `overlays:create`, `overlays:edit`, `overlays:delete`
- `uploads:read`, `uploads:create`, `uploads:delete`
- `rewards:read`, `rewards:edit`
- `events:read`, `events:userinfo`
- `settings:read` (to see OBS URLs)
- `tokens:read`, `tokens:create` (so they can create popout tokens for preview docks)

Leave chat, automations, connections, members, roles untouched.

### "A stats-only seat for an agency / manager"

Create a custom role with only the read permissions this person needs, such as `events:read`, `events:userinfo` and `overlays:read`. Add `chat:read` + `chat:userinfo` if they need chat context. Do **not** grant `chat:write`.

### "A co-host who can run the whole stream except billing"

That's exactly **Administrator**. Assign it as-is.

### "A VA who triggers automations but can't change them"

Start from Moderator; ensure `automations:read` + `automations:execute` are on (Moderator already has both by default); leave `automations:create`, `automations:edit`, and `automations:delete` off. Optionally remove chat moderation if they shouldn't ban/timeout.

## Popout Tokens

When you create a popout token under `Settings → Channel → Access → Popout Tokens`, you choose a subset of permissions for that token. The token can **never** have more permissions than the creator's role - Lumio intersects the two lists on save.

A Moderator creating a popout token for OBS can therefore never produce a token with `settings:edit` or `automations:edit`, even by editing the request manually.

## Permissions Cheat-Sheet

| Capability | Permission |
|------------|------------|
| Read chat | `chat:read` |
| Pin, change the duration or unpin a Twitch message | `chat:pin` |
| Send chat messages | `chat:write` |
| Timeout users | `chat:timeout` |
| Ban users | `chat:ban` |
| Create overlays | `overlays:create` |
| Edit overlays | `overlays:edit` |
| Create / duplicate widgets | `widgets:create` (duplicating also needs Editor access to the source widget) |
| Edit widget config | `widgets:edit` |
| Read widget access | `widgets:access-read` |
| Grant widget access | `widgets:access-grant` |
| Revoke widget access | `widgets:access-revoke` |
| Upload files | `uploads:create` |
| Connect Twitch/YouTube/etc. | `connections:create` |
| Invite members | `members:create` |
| Change member roles | `members:edit` |
| Create custom roles | `roles:edit` |
| Create automations | `automations:create` |
| Edit automations (nodes, edges, enabled) | `automations:edit` |
| Delete automations | `automations:delete` |
| Run automations manually | `automations:execute` |
| Create popout tokens | `tokens:create` |
| Create personal API keys | `apikeys:create` |
| Change plan / billing | `plan:edit` |
| Dissolve account | `account:delete` |
| View account audit log | `audit-log:read` |
| View your own activity log | none - signed-in user only |

## Lumio Internal: Privacy Tooling

`admin:privacy-erase` is a Lumio-internal **admin-scope** permission used by support staff to honour GDPR Art-17 erasure requests (currently: YouTube member-channel records, chat-subject data, a person's entries on Lumio's own surfaces, and orphaned extension upload files). A chat-subject or member erasure acts in one channel only, on that channel's instruction; the Lumio-only erasure touches no channel's data. It is **not** assigned to per-account roles like Owner/Administrator/Moderator - only the `system_admin` Lumio admin role carries it. End users do not see this permission in the role editor. Erasures are audit-logged.

`admin:privacy-objection-create` and `admin:privacy-objection-delete` are Lumio-internal **admin-scope** permissions of the same kind. Support staff use them to record or lift a chatter's GDPR Art-21 objection: afterwards, public Stats leaderboards hide the name, also on streams published earlier, without erasing anything. A channel's own stream reports, share links and AutoMod log are not affected. Only the `system_admin` Lumio admin role carries them; end users do not see them in the role editor. Both actions are audit-logged.

`admin:privacy-erase-withdraw` is another Lumio-internal **admin-scope** permission. Support staff use it when a channel withdraws its instruction to erase a chat participant: that channel's stream reports created afterwards show the participant's name again. Nothing the erasure deleted comes back, and other channels are not affected. Only the `system_admin` Lumio admin role carries it; end users do not see it in the role editor. The withdrawal is audit-logged.

`csp-reports:read` is likewise a Lumio-internal **admin-scope** permission. It lets platform staff read the CSP-violation calibration aggregate (which browser Content-Security-Policy rules would have blocked, and on which host) so the policy can be tightened safely. It stores only the violated directive and the scheme+host of the blocked resource - **no page URL, no viewer identity** - and is **not** assigned to per-account roles; only the `system_admin` Lumio admin role carries it. End users do not see it in the role editor.

### Withdrawal and cancellation permissions

A signed-in member needs `plan:edit` to submit a withdrawal or cancellation for a plan and `extension-store:uninstall` for a paid extension purchase or subscription. The public `/withdraw` and `/cancel` forms require no account role. A signed-in **Other contract** withdrawal needs an interactive session. [Withdrawal & Cancellation](/user-guide/withdrawal-and-cancellation) explains the forms.

The operator queue uses admin-scoped `contract-declarations:read` to view cases and `contract-declarations:edit` to match, close or extend them. These grants do not appear in account role pickers and are assigned to `system_admin` by default.

`developer-funds:release-deletion` is a Lumio-internal **admin-scope** permission. Support staff use it, on a developer's request, to delete a developer profile whose balance cannot be paid out (no payout method or no verified identity); Lumio keeps the balance as a claim and mails the person a claim code. It is assigned to `system_admin` by default and does not appear in account role pickers.

`developer-funds:settle` is the matching **admin-scope** permission for when that person comes back with the claim code: support staff record the claim and credit the kept balance to the person's new, verified developer profile, from where the normal payout pays it out. It is assigned to `system_admin` by default and does not appear in account role pickers.

`extension-purchases:read` is likewise a Lumio-internal **admin-scope** permission. Support staff use it to find paid extension checkouts that were never delivered (for example, an automatic refund that Stripe refused), so they can refund the buyer or install the extension. It is **not** assigned to per-account roles; only the `system_admin` Lumio admin role carries it. End users do not see it in the role editor.

`devtools:read` is likewise a Lumio-internal **admin-scope** permission. It shows the Dev & Admin menu in the web app to Lumio staff (for example, to preview a seasonal look in their own browser). It is **not** assigned to per-account roles; the `system_admin` Lumio admin role carries it, and Lumio can grant it to further internal admin roles. End users do not see it in the role editor.

## Ideas Hub Roles

The sections above describe **account-scoped roles** - they control what you can do within a specific account (overlays, chat, music, automations, etc.). The Ideas Hub uses a separate permission layer: **user-scoped roles**. These roles are tied to your user identity across Lumio, not to any single account.

### Why a separate layer?

Account roles answer "What can this person do on *my* channel?" User roles answer "What can this person do in *cross-account* features like the Ideas Hub?" The two layers are independent: an Owner on their own account still has whatever user role they hold when they visit the Ideas Hub, and a Restricted user in the Ideas Hub can still be an Administrator on someone else's account.

### Default User Roles

Lumio assigns one of three user roles to every user. All new users start as **Member**.

#### Member

The default role. Members have full access to the Ideas Hub:

- Create new ideas
- Edit and delete their own ideas
- Vote on ideas
- Read and create comments
- Vote on comments and replies
- Edit and delete their own comments

#### Restricted

Read-only access. Restricted users can browse ideas and read comments but cannot contribute content or vote. This role is assigned by Lumio moderators to users who have violated community guidelines.

#### Moderator

Everything a Member can do, plus moderation capabilities across the entire Ideas Hub:

- Review and change the status of any idea (e.g. mark as planned, completed, or declined)
- Edit or delete any idea, regardless of author
- Delete any comment, regardless of author (editing a comment is always author-only)

### Permissions by Role

| Action | Member | Restricted | Moderator |
|--------|--------|------------|-----------|
| Browse ideas | Yes | Yes | Yes |
| Create ideas | Yes | No | Yes |
| Edit own ideas | Yes | No | Yes |
| Delete own ideas | Yes | No | Yes |
| Vote on ideas | Yes | No | Yes |
| Read comments | Yes | Yes | Yes |
| Create comments | Yes | No | Yes |
| Vote on comments | Yes | No | Yes |
| Edit own comments | Yes | No | Yes |
| Delete own comments | Yes | No | Yes |
| Moderate all ideas | No | No | Yes |
| Change idea status | No | No | Yes |

## Tips & Best Practices

- **Prefer custom roles over editing the defaults.** If you change the Moderator role, every mod on the account changes with it. A custom "Chat Mod (no polls)" role keeps the default intact.
- **Start restrictive.** It's easier to add permissions on request than to explain a security incident.
- **Name roles by function, not by person.** "Content Editor" ages better than "Sarah".
- **Use the color field.** Member badges use it - green-for-mods, blue-for-editors is much faster to scan than reading labels.
- **Invite tokens for manual distribution, invite links for DMs.** Invite links include the role; the recipient clicks and lands on a "You have been invited" page. Tokens are paste-into-dashboard for people already signed in.
- **Sessions matter.** Every user manages their own sessions under `Account → Sessions`; if a collaborator's laptop is lost, have them revoke their sessions there before you change their role - otherwise their existing browser tab keeps the cached permissions until the next refresh.

## Troubleshooting

### "Why can't I see the Music page?"

Your role lacks `spotify:read` (and usually also `spotify:playback`). Ask the Owner to add the Spotify permissions - the entire Music nav item is hidden when `spotify:read` is missing.

### "I see 'No Access - Contact the account owner to get access.'"

You navigated to a URL (maybe from a bookmark) for a feature you don't have permission to use. The message is a deliberate friendly 403; check your role under `Settings → Channel → Roles`.

### "I edited the role but the member still can't do the thing."

The permission cache refreshes when the role is saved, but the member's browser may need a reload to pick up the new hidden/visible UI. Ask them to refresh. If it still fails, verify the permission string is really on the role (open the role, check the Permissions step).

### "The Owner role is greyed out - I can't edit it."

Correct. Owner is a **system role** (`is_system: true`). It always has every permission and cannot be modified or deleted. If you need a "near-Owner" role, edit or clone **Administrator** instead.

### "I can't assign the Owner role when inviting."

By design. The invite wizard hides Owner ("Owner role cannot be assigned"). Ownership transfers go through account settings, not invites.

### "Can a member belong to multiple roles?"

Currently no: each member has exactly one role per account. To give someone a superset of permissions, create a custom role combining the two.

### "How do I give a popout token fewer permissions than my role?"

Create the token under `Settings → Channel → Access → Popout Tokens → New Token`, and uncheck permissions you don't want on it. The list is pre-filled with your current permissions as the upper bound.

## Related Docs

- [Automation Templates](./automation-templates.md) - which permissions gate which template variables.
- [Account Switching](../features/accounts.md) - how roles work across multiple accounts you belong to.
- [Popout Tokens](../features/tokens.md) - permission-bounded tokens for browser sources.

---

## User Guide / Automation Templates

Source: https://docs.lumio.vision/user-guide/automation-templates

# Automation Templates

Template variables let you weave live data - the viewer's name, the current song, the stream title, a custom variable you set - into an automation action or a bot command response. You wrap a variable name in curly braces, and Lumio replaces it with the matching value at runtime.

Lumio has **two** template surfaces, and they use **different** brace styles and different variable sets:

| Surface | Braces | Variable set |
|---------|--------|--------------|
| **Automation actions** (the automation builder) | double - `{{displayName}}` | the large reference below |
| **Bot command responses** (Response Type **Template**) | single - `{user}` | seven built-ins, see [Bot command variables](#bot-command-variables-single-braces) |

Most of this guide covers the **automation** engine. If you are editing a `!command` response, jump straight to [Bot command variables](#bot-command-variables-single-braces).

> **Note:**
> Trigger nodes fire only where the operator has turned automation triggers on. Otherwise an automation runs only when you execute it manually. Variables that a trigger fills (the triggering user, the event, captured command arguments) are empty in a manual run. See [Automations → Data Flow](../features/automations.md#data-flow).

**Who needs this guide?**

- Anyone building **automation actions** that send chat messages, Discord posts, or overlay alerts.
- Anyone writing a **bot command** whose response should include the caller's name or the current song.
- Anyone debugging a template that resolves to an empty string or leaks a literal `{{name}}` into chat.

## Where Templates Are Used

The double-brace engine resolves variables in these **automation action** fields:

- **Chat Message** - the message body.
- **Discord Post** - the message body.
- **Overlay Alert** - the alert message.
- **Webhook Call** - the URL, every header value, and the request body.
- **Set Variable** - the value you assign.

Bot command responses are handled by the separate single-brace engine described below. **Timed messages** (the Timed Messages bot module) send their configured lines verbatim - they do not resolve variables.

## Syntax: `{{variable}}`

Variables are wrapped in **double** curly braces:

```
Hello {{displayName}}, welcome to the stream!
```

Rules:

- The name is letters, digits and underscores - `camelCase` is the convention.
- Dotted paths are allowed: `{{event.type}}`, `{{discord.serverName}}`, `{{var.myCustomVar}}`, `{{event.raw.someField}}`.
- **Single** curly braces (`{name}`) are left untouched by the automation engine. In a **bot command** response, single braces are exactly what you want - see [Bot command variables](#bot-command-variables-single-braces).
- Replacement is done left-to-right in one pass. The resolved value is **not** re-parsed, so a variable whose value happens to contain `{{otherVar}}` will appear literally.

## Quick Start

| Template | Typical output |
|----------|----------------|
| `Welcome {{displayName}}!` | `Welcome Rapha!` |
| `{{username}} cheered {{cheerAmount}} bits!` | `rapha cheered 500 bits!` |
| `Now playing: {{songName}} by {{songArtist}}` | `Now playing: Blinding Lights by The Weeknd` |
| `Stream: {{streamTitle}} ({{category}})` | `Stream: Valorant Ranked (Valorant)` |
| `Uptime: {{uptime}} / {{liveViewerCount}} viewers` | `Uptime: 2h 30m / 1234 viewers` |
| `Shout out to {{var.lastRaider}}!` | `Shout out to someStreamer!` |
| `Order #{{orderNumber}} - {{orderTotal}} {{orderCurrency}}` | `Order #1082 - 42.00 EUR` |

## Resolution Rules

There are three cases, and knowing which applies saves a lot of debugging time.

1. **Known variable, data present** → replaced with the value.
2. **Known variable from a permission-scoped group, data missing** → replaced with an **empty string**. This covers every variable listed under `chat:userinfo`, `events:read` and `spotify:read` below. The rest of the message still renders, which is often why you see weird double-spaces (`"  "` where you expected a value).
3. **Everything else that does not resolve** → **left as-is**, braces and all. That includes typos (`Hello {{unknwn}}!` stays `Hello {{unknwn}}!`) **and** the ungated groups: a `{{channelName}}`, `{{botName}}`, `{{date}}`, `{{sceneName}}`, `{{orderNumber}}`, `{{discord.serverName}}` or `{{var.something}}` with no value behind it stays visible in the output rather than vanishing.

Rule 3 is worth internalising: an **unset custom variable does not disappear** - `{{var.lastRaider}}` will be posted to chat literally until something has written a value into `lastRaider`.

The empty-string rule for the gated groups is what lets you write defensive templates like:

```
Currently playing {{songName}}{{songArtist}}
```

If Spotify isn't connected, nothing renders for those variables. If it is, you get `Blinding LightsThe Weeknd` (you'll want to add a separator - see [Tips](#tips--best-practices)).

## Output Encoding

Automation steps encode every substituted value for the place it lands, so text from a viewer, donor or buyer (a chat message, a donation note) cannot change the shape of what the step sends. Only the values are encoded; the text you type into the template stays exactly as written, and an unresolved placeholder stays literal.

| Step and field | How substituted values are encoded |
|----------------|------------------------------------|
| Chat message, overlay alert, condition, Set Variable | Inserted as they are |
| Discord post message | Markdown punctuation (backslash, asterisk, underscore, tilde, backtick, pipe, brackets, parentheses, angle brackets, `#`, `@`) is backslash-escaped, so a value shows as plain text and cannot form a masked link, formatting or a mention. Your own markdown in the template still works |
| Webhook URL | Percent-encoded as one URL component when the placeholder sits in the path, query or fragment (after the literal `https://host`). A placeholder in the scheme or host part - including a template that is only `{{var.url}}` - is inserted as it is; the [target filter](../features/automations.md#webhook-call-targets) still checks the result |
| Webhook header value | Line breaks and other control characters become spaces |
| Webhook body | With a `Content-Type` header containing `json`, or no `Content-Type` and a body that starts with `{` or `[`: JSON-string-escaped, so put the placeholder inside quotes, e.g. `{"msg": "{{event.raw.message}}"}`. With `application/x-www-form-urlencoded`: percent-encoded. Any other body: inserted as it is |

## Permission Scopes

Every variable belongs to a group, and each group is associated with a permission. The groups matter for two reasons: they tell you which part of Lumio a variable's data comes from, and they decide whether a variable that fails to resolve becomes an empty string (gated groups) or stays literal in the output (ungated groups - see rule 3 above).

| Variable group | Associated permission |
|----------------|-----------------------|
| Channel, Bot, Time, Shopify, OBS, Discord, Custom (`var.*`) | **none** |
| User (`username`, `displayName`, `avatarUrl`, `userId`) | `chat:userinfo` |
| Stream, Channel Status, Follower, Sub, Cheer, Raid, Redemption, Tip, Hype Train, Poll, Prediction, Event metadata | `events:read` |
| Spotify (`songName`, `songArtist`, …) | `spotify:read` |

Automations run under the **account** that owns them, not under the viewer who triggered them, so a variable's value never depends on who typed in chat.

## Variable Reference

### Ungated groups (no associated permission)

#### Channel

| Variable | Description |
|----------|-------------|
| `{{channelName}}` | Display name of the channel. |
| `{{channelUrl}}` | URL to the channel page. |
| `{{platform}}` | Platform slug (`twitch`, `youtube`, `kick`). |

#### Bot

| Variable | Description |
|----------|-------------|
| `{{botName}}` | Bot account's username. |
| `{{commandPrefix}}` | Current command prefix (for example `!`). |

#### Time

| Variable | Description |
|----------|-------------|
| `{{date}}` | Current date in the configured timezone. |
| `{{time}}` | Current time. |
| `{{timestamp}}` | Unix timestamp. |
| `{{timezone}}` | Configured timezone name. |

#### Shopify (from Shopify order events)

| Variable | Description |
|----------|-------------|
| `{{orderNumber}}` | Order number. |
| `{{orderTotal}}` | Order total. |
| `{{orderCurrency}}` | ISO currency code. |
| `{{productName}}` | Product name from the order. |

#### OBS (from the OBS integration)

| Variable | Description |
|----------|-------------|
| `{{sceneName}}` | Current scene. |
| `{{bitrate}}` | Current streaming bitrate. |
| `{{fps}}` | Current frames per second. |
| `{{droppedFrames}}` | Dropped frames counter. |

#### Discord (dotted paths)

| Variable | Description |
|----------|-------------|
| `{{discord.serverName}}` | Discord server display name. |
| `{{discord.channelName}}` | Discord channel name. |
| `{{discord.memberCount}}` | Member count at event time. |

#### Custom variables (`var.*`)

Values written by a **Set Variable** action, or captured by the automation's trigger. A **Keyword trigger** with capture groups exposes them here, and a **Command trigger** fills `{{var.command}}` with the command name and `{{var.args}}` with everything the caller typed after it. There is no hard list - any name under `var.*` looks up the matching entry.

| Variable | Description |
|----------|-------------|
| `{{var.anyName}}` | Value of the named custom variable. If nothing has set it, the placeholder is left in the output unchanged. |

### User group - `chat:userinfo`

Context: info about the user who triggered the event (the viewer who followed, subscribed, sent the bits, ran the command, etc.). When the triggering event carries no user, these resolve to empty strings.

| Variable | Description |
|----------|-------------|
| `{{username}}` | Login / handle. |
| `{{displayName}}` | Display name (may include capitalization / unicode). |
| `{{avatarUrl}}` | Profile picture URL. |
| `{{userId}}` | Platform user ID. |

### Event group - `events:read`

Stream snapshot:

| Variable | Description |
|----------|-------------|
| `{{streamTitle}}` | Current stream title. |
| `{{category}}` | Current category/game. |
| `{{gameName}}` | Legacy alias for `{{category}}` - kept for backward compatibility. |
| `{{viewerCount}}` | Viewer count at event time. |
| `{{uptime}}` | Stream uptime. |
| `{{streamUrl}}` | Link to the live stream. |
| `{{streamPreviewUrl}}` | URL of the preview thumbnail image. |

Channel-status (multi-platform live state):

| Variable | Description |
|----------|-------------|
| `{{isLive}}` | `true` / `false`. |
| `{{liveViewerCount}}`, `{{liveCategory}}`, `{{liveTitle}}`, `{{livePlatform}}` | Current live data aggregated across connected platforms. |

Follower:

| Variable | Description |
|----------|-------------|
| `{{followerName}}` | Display name of the new follower (alias for `{{displayName}}` scoped to follower events). |

Subscription:

| Variable | Description |
|----------|-------------|
| `{{subTier}}` | `Tier 1`, `Tier 2`, `Tier 3`, or the platform equivalent. |
| `{{subMonths}}` | Cumulative subscription months. |
| `{{isGift}}` | `true` / `false`. |
| `{{giftRecipient}}` | Display name of the gift-sub recipient (only when `isGift=true`). |

Cheer / bits:

| Variable | Description |
|----------|-------------|
| `{{cheerAmount}}` | Bits cheered. |
| `{{cheerMessage}}` | Message sent with the cheer. |

A Twitch cheer event also carries `event.raw.cheermote` - the cheer graphic for the total amount - so `{{event.raw.cheermote.color}}` and `{{event.raw.cheermote.urls.dark.animated}}` resolve to its tier colour and image URL. The field is empty when Lumio could not load the channel's cheermotes.

Raid:

| Variable | Description |
|----------|-------------|
| `{{raidViewers}}` | Number of incoming raiders. |
| `{{raidFrom}}` | Name of the raiding channel. |

Channel-point redemption:

| Variable | Description |
|----------|-------------|
| `{{rewardName}}` | Reward title. |
| `{{rewardCost}}` | Channel-point cost. |
| `{{rewardInput}}` | Viewer-supplied text, if the reward requires input. |

Tip / donation:

| Variable | Description |
|----------|-------------|
| `{{tipAmount}}` | Numeric amount. |
| `{{tipCurrency}}` | ISO currency code. |
| `{{tipMessage}}` | Viewer's tip message. |

Hype train:

| Variable | Description |
|----------|-------------|
| `{{hypeTrainLevel}}` | Current level. |
| `{{hypeTrainTotal}}` | Total contributions so far. |
| `{{hypeTrainProgress}}` | Progress toward the next level. |

Poll / prediction:

| Variable | Description |
|----------|-------------|
| `{{pollTitle}}`, `{{pollChoices}}`, `{{pollWinner}}` | Live poll state. |
| `{{predictionTitle}}`, `{{predictionOutcomes}}`, `{{predictionWinner}}` | Live prediction state. |

Event metadata (dotted paths):

| Variable | Description |
|----------|-------------|
| `{{event.type}}` | Event type, e.g. `twitch:follower`, `youtube:superchat`. |
| `{{event.platform}}` | Source platform slug. |
| `{{event.raw.<field>}}` | Any raw field of the source event - useful for platform-specific data not yet surfaced as a first-class variable. |

### Spotify group - `spotify:read`

| Variable | Description |
|----------|-------------|
| `{{songName}}` | Current track title. |
| `{{songTitle}}` | Legacy alias for `{{songName}}`. |
| `{{songArtist}}` | Track artist(s). |
| `{{songAlbum}}` | Album name. |
| `{{songUrl}}` | Spotify track URL. |
| `{{songAlbumArt}}` | Album art image URL. |
| `{{albumArt}}` | Legacy alias for `{{songAlbumArt}}`. |
| `{{songDuration}}` | Track duration. |
| `{{songProgress}}` | Current playback position. |
| `{{isPlaying}}` | `true` / `false`. |
| `{{shuffleState}}` | `off`, `on`, or `smart`. |
| `{{repeatState}}` | `off`, `track`, or `context`. |
| `{{spotifyDevice}}` | Active playback device name. |
| `{{spotifyPlaylist}}` | Active playlist name, if any. |

Spotify must actually be connected and playing for these to have values.

## Bot command variables (single braces)

Bot command responses do **not** use the double-brace engine. In the command editor, set **Response Type** to **Template** and write your **Response Text** with **single** braces. The editor shows the available names inline as a hint.

| Variable | Description |
|----------|-------------|
| `{user}` | Display name of the viewer who ran the command. |
| `{channel}` | Name of the channel the command was used in. |
| `{platform}` | Platform the command came from, e.g. `twitch`. |
| `{count}` | How many times this command has been used. |
| `{uptime}` | Stream uptime, e.g. `2h 30m`. Empty when the stream is offline. |
| `{song}` | Currently playing Spotify track. Requires the **Spotify Now Playing** feature on your plan and a connected Spotify account. |
| `{random:a,b,c}` | Picks one item at random from the comma-separated list. |

Anything else in single braces - a typo, or a name that is not in this list - is replaced with an **empty string**, so a mistyped variable silently disappears from the message rather than showing up literally.

If you need any of the richer variables from the reference above in a chat command, set **Response Type** to **Automation** instead and point the command at an automation whose **Chat Message** action carries the double-brace template.

## Recipes

### Welcome message with username

Bot command, Response Type **Template**:

```
Welcome to the stream, {user}! Enjoy your stay :)
```

The equivalent inside an automation's **Chat Message** action:

```
Welcome to the stream, {{displayName}}! Enjoy your stay :)
```

### Shoutout template

```
Go check out {{var.lastRaider}} at https://twitch.tv/{{var.lastRaider}} — they raided us with {{raidViewers}} viewers!
```

`{{var.lastRaider}}` is whatever value you stored in the custom variable `lastRaider` - typically via a **Set Variable** action earlier in the same automation, on a raid trigger. Until something writes it, the placeholder stays visible in the message.

### Now-playing announcement

In an automation's **Chat Message** action:

```
🎵 Now playing: {{songName}} — {{songArtist}} [{{spotifyDevice}}]
```

When Spotify is paused or disconnected, the fields resolve to empty strings, producing `🎵 Now playing:  -  []` - so use a **Condition** step that only sends the message when `{{isPlaying}}` equals `true`.

For a plain `!song` chat command, the single-brace `{song}` variable is simpler:

```
🎵 Now playing: {song}
```

### Sub announcement

```
{{displayName}} just subscribed at {{subTier}} for {{subMonths}} months! 🎉
```

Pair this with a subscription event trigger, which is what populates the sub variables.

### Tip thank-you (with currency)

```
Thank you {{displayName}} for the {{tipAmount}} {{tipCurrency}} tip! Your message: "{{tipMessage}}"
```

### Reading an uncommon event field

Every event has a `raw` map containing platform-native fields. If Lumio doesn't expose a first-class variable for what you need, reach into `event.raw`:

```
New Kick follow from kick.com/{{event.raw.user_login}}
```

Use this as a fallback; first-class variables should be preferred for portability across platforms.

### Kick event triggers and their raw fields

The automation trigger is the event type as free text, so every Kick type below works as a trigger
without further setup. Kick events keep Kick's original payload in `raw` and add the same top-level
field names Twitch events use, so a template written for Twitch usually reads a Kick event too.

Every Kick event with a viewer behind it carries:

| Raw field | Meaning |
|-----------|---------|
| `user_id` | The viewer's Kick user ID (a string). |
| `user_login` | The viewer's Kick channel slug - the part after `kick.com/`. |
| `user_name` | The viewer's Kick username. |
| `avatarUrl` | Profile picture URL; absent when the viewer has none. |
| `is_anonymous` | `true` for an anonymous gifter. `user_name` is then `AnAnonymousGifter` and there is no `user_id` or `avatarUrl`. |

Per trigger type:

| Trigger | Additional raw fields |
|---------|-----------------------|
| `kick:follower` | - |
| `kick:subscribe` | `cumulative_months`, `expires_at` |
| `kick:resub` | `cumulative_months`, `expires_at` |
| `kick:gift` | `giftCount` (subs in the bundle), `giftRecipients` (usernames), `is_gift`; with exactly one recipient also `recipient_user_id`, `recipient_user_login`, `recipient_user_name`; `gifter_is_anonymous` for an anonymous gifter |
| `kick:kicks` | `kicks` (the amount - a count like Twitch bits, not money), `message`, `kick_gift_name`, `kick_gift_type`, `kick_gift_tier`, `kick_pinned_time_seconds`; for a known gift also `kick_gift_id` (e.g. `rage_quit`), `kick_gift_image.static` / `kick_gift_image.animated` (sticker URLs; `animated` is empty for the four cheapest gifts) and `kick_gift_color` |
| `kick:reward` | `id` (redemption), `status` (`pending`, `accepted` or `rejected`), `user_input`, `redeemed_at`, `reward.id`, `reward.title`, `reward.cost`, `reward.prompt` |
| `kick:reward_status` | Same fields as `kick:reward`. Fires on every status change after the first delivery of a redemption - trigger on it and check `status` to react to _accepted_. |
| `kick:stream_online` | `title`, `started_at` (no category - Kick sends it only through its API) |
| `kick:stream_offline` | `ended_at` |
| `kick:stream_update` | `title`, `category_id`, `category_name`, `language`, `has_mature_content`, `title_changed`, `category_changed`, `language_changed`; `old_title` / `old_category_name` / `old_language` when that field changed. Fires only when something changed - also while you are offline. |

Nested objects use dotted paths, for example `{{event.raw.reward.title}}` for the redeemed reward.

Twitch's `twitch:stream_update` carries the same change fields (`title_changed`, `category_changed`, `language_changed` and the matching `old_*`) plus `tags`, `tags_changed` and `old_tags`. Twitch does not report a tag-only edit, so a tag change shows up with the next title, category or language change. Use `{{event.raw.old_title}}` → `{{event.raw.title}}` to announce a new title.

### YouTube stream triggers and their raw fields

YouTube's go-live and go-offline events work as triggers like their Twitch and Kick counterparts.
They have no viewer behind them, so they carry no `user_*` fields.

| Trigger | Raw fields |
|---------|------------|
| `youtube:stream_online` | `broadcast_id` (the live video's ID), `title`, `started_at` (no category - YouTube's live data has none) |
| `youtube:stream_offline` | `broadcast_id` |

### Random picks

In a **bot command** template, `{random:a,b,c}` picks one of the listed items directly. The automation engine has no `{{random}}` built-in - there, use a **Random** logic node to branch, or a **Set Variable** action to store a value and reference it as `{{var.pickedUser}}` in a later step.

## Tips & Best Practices

- **Always add separators.** Missing data resolves to empty string, so `{{songName}} by {{songArtist}}` becomes ` by ` when Spotify is paused. A small conditional upstream avoids the awkward output.
- **Prefer `{{displayName}}` over `{{username}}`** for user-facing messages - `displayName` preserves capitalization and localized characters; `username` is the raw handle.
- **Use `{{event.raw.*}}` sparingly.** It ties your template to a specific platform's payload. When a field starts mattering to more than one command, request a first-class variable.
- **Custom variables are your escape hatch.** Anything not covered by a built-in (accumulated counters, last caller) can live in `{{var.*}}` and be updated by a **Set Variable** step - but seed it before you reference it, or the placeholder shows up literally.
- **Try it on a quiet channel first.** Neither editor renders a template preview, so the first real output you see is the one your viewers see. Run the automation manually, or point the command at a test channel, before you rely on it live.
- **Legacy aliases exist for compatibility.** `{{songTitle}}` = `{{songName}}`, `{{albumArt}}` = `{{songAlbumArt}}`, `{{gameName}}` = `{{category}}`. Prefer the canonical names in new templates.

## Troubleshooting

### My template output contains a literal `{{name}}`

Two things produce this:

1. **A typo or a name that doesn't exist** - `{{usrname}}` instead of `{{username}}`, or `{{viewerName}}`, which isn't a real variable (use `{{displayName}}`). Cross-check the [Variable Reference](#variable-reference).
2. **An ungated variable with nothing behind it** - the Channel, Bot, Time, Shopify, OBS, Discord and `var.*` groups stay literal rather than collapsing to an empty string. An unset `{{var.something}}` or an `{{sceneName}}` with OBS disconnected will land in chat as-is.

### The output is missing where I expected data

A variable from the `chat:userinfo`, `events:read` or `spotify:read` groups resolved to an empty string. Possible causes, in order:

1. **The variable category isn't populated** for this trigger. A follower event doesn't populate `{{cheerAmount}}` - it's simply absent.
2. **Source feature not connected or idle.** `{{songName}}` needs Spotify connected *and* playing.
3. **Wrong group for the trigger.** `{{displayName}}` needs an event that carries a user; a timer trigger has none.

### Why isn't `{name}` (single braces) working?

Check which surface you are on. Automation actions need **double** braces; bot command responses need **single** braces *and* Response Type set to **Template** - a command left on Response Type **Text** sends its body verbatim, braces and all.

### Can I nest variables?

Not directly. The replacement pass doesn't recurse. If you need composition, pre-compute the value into a custom variable with an automation step, then reference `{{var.composed}}` in the final template.

### It worked once and now resolves to nothing

The Spotify, OBS and stream-snapshot variables read live state. `{{songName}}` is empty whenever nothing is playing, `{{uptime}}` is empty while you are offline, and `{{sceneName}}` stays literal while OBS is disconnected - the template itself is fine.

### `{{event.raw.someField}}` is always empty

The field name doesn't exist in this event's raw payload. Raw fields are platform-native and differ per platform and per event type, so a name that works for a Kick follow won't necessarily exist on a Twitch follow. Watch the **Events** page while the event fires to see what a real payload for that trigger looks like.

## Related Docs

- [Roles & Permissions](./roles-and-permissions.md) - how roles and permissions are organised.
- [Automations](../features/automations.md) - triggers, actions, and the automation builder.
- [Bot Commands](../features/bot-commands.md) - creating and overriding `!commands`.
- [Chat](./chat.md) - how to send chat messages from the dashboard.

---

## User Guide / Bot Modules

Source: https://docs.lumio.vision/user-guide/bot-modules

# Bot Modules

Bot modules automate chat moderation and messaging. Every bot module - including the four that ship with Lumio - is an extension. Lumio provides four built-in modules (link protection, spam protection, word filter, and timed messages), and additional bot modules can be installed from the Extension Store.

## Built-in Modules

The four built-in modules ship with Lumio and are available on every plan. You manage them under **Dashboard > Bot Modules** (in the sidebar under **Tools**).

| Module | What it does |
|--------|--------------|
| Link Protection | Detects URLs in chat messages and applies a whitelist and a blacklist of domains. Action: warn, delete, timeout, or ban, with a configurable timeout duration and warning message. |
| Spam Protection | Detects excessive capitals, excessive symbols, and emote spam. Thresholds cover the caps percentage, the minimum message length before the caps check applies, the maximum emote count, and the symbol percentage. Same four actions as Link Protection. |
| Word Filter | Blocks messages containing banned words, phrases, or regex patterns, with an optional wildcard mode. Same four actions as Link Protection. |
| Timed Messages | Sends rotating messages on a configurable interval (60 seconds and up). Options: send only while you are live, and require a minimum number of chat lines between two messages. |

Each module supports:

- **Exempt roles** - moderators, VIPs, and subscribers can each be exempted from enforcement.
- **Module-specific settings** - thresholds, actions, and messages, as listed above.

## The Bot Modules page

**Dashboard > Bot Modules** lists every bot module installed on the account. Each entry shows the module's icon, name, and description, plus a **Built-in** badge for the four modules that ship with Lumio.

Per entry you get:

- **On/off toggle** - enables or disables the module for the account. The toggle is disabled, and the card dimmed, when the module is unavailable - a tooltip and an inline note say why (not included in your plan, disabled by an administrator, or disabled for your account).
- **Configure** - expands the entry to show the exempt-role selection and the module's current configuration values. This expanded view is read-only.
- **Add Module** - opens the Extension Store filtered to the **Bot Modules** category.

## Installing another bot module

1. Open **Store > Browse Store** from the sidebar, or click **Add Module** on the Bot Modules page.
2. Filter by the **Bot Modules** category, or search for the module by name.
3. Open the module to review its description, version, and developer.
4. Click **Install**. A dialog lists the permissions the module requests and its price if it is not free; confirm with **Install**.
5. The module then appears on **Dashboard > Bot Modules** alongside the built-in ones.

Installed extensions - bot modules included - are also listed under **Store > Installed**, where you can toggle auto-update and uninstall. Built-in modules cannot be uninstalled.

## Module settings, logs, and errors

Each installed bot module has its own settings page with three sections:

- **Configuration** - the module's stored configuration values.
- **Permissions & Triggers** - a placeholder; there are no settings here.
- **Diagnostics** - links to **View Logs** and **View Errors** for that installation.

### Logs

The log view lists the module's recent handler runs, newest first. Each line shows:

- Time
- Log level
- The handler that ran
- The log message

Filter buttons across the top narrow the list to **All**, **DEBUG**, **INFO**, **WARN**, or **ERROR**, and a **Refresh** button re-fetches the list. Logs appear once the module starts processing events.

### Errors

The error view shows only failures. Two counters at the top give the **Total Errors** and the number of **Unique Errors**. Each entry lists the error message, the handler it came from, when it was last seen, and how often it occurred. Click an entry to expand its stack trace.

## Turning a misbehaving module off

If a module is behaving badly - moderating the wrong messages, or posting too often - switch its **on/off toggle** off on **Dashboard > Bot Modules**. The change takes effect without restarting the bot, and the module's configuration is kept, so you can switch it back on once the problem is resolved.

## Plans and permissions

- The four built-in modules are available on every plan.
- Bot modules installed from the Extension Store require a paid plan; they are switched off on the free plan.

| Capability | Permission |
|---|---|
| Open **Dashboard > Bot Modules**, view a module's configuration, logs, and errors | `bot-modules:read` |
| Toggle a module on or off and change its configuration | `bot-modules:edit` |
| Browse the Extension Store | `extension-store:read` |
| Install a module from the store | `extension-store:install` |
| Uninstall a module | `extension-store:uninstall` |

Without `bot-modules:read`, the **Bot Modules** entry does not appear in the sidebar.

---

## User Guide / Channel Status

Source: https://docs.lumio.vision/user-guide/channel-status

# Channel Status

Channel Status is Lumio's always-on awareness of whether you are **live** right now. It drives the live-indicators on your dashboard, gates which background workers are running (most notably the Spotify integration), and keeps API usage down when you're offline.

This guide explains how the live detection works, what the dashboard shows you, and the one case where you might need to intervene manually (Spotify).

## Where to find it

The primary surface is the **channel card grid** on the main **Dashboard** page. Every connected Twitch, YouTube, or Kick channel gets its own card with avatar, channel name, platform name, and a link out to the channel.

Live status is detected for **Twitch, YouTube and Kick**. When one of those is live, its card additionally shows a **Live** badge, a pulsing red dot on the avatar, the viewer count, the stream title, and the category.

## Quick start

Nothing to set up. Once you've connected a platform via **Dashboard > Connections**, Lumio tracks its live status automatically:

1. Go live on the platform as usual.
2. Within seconds (Twitch, Kick) or up to about a minute (YouTube), the dashboard card flips to **Live**. The viewer count follows within a minute on Kick and YouTube.
3. When you end the stream, the card flips back to offline.

The only manual control is the Spotify **Connect** button on **Dashboard > Music** (see below), which is only relevant if you want Spotify active before you actually go live.

## How live detection works

Lumio uses the most efficient signal available on each platform:

| Platform | Detection method | Typical latency |
|---|---|---|
| Twitch | EventSub webhook (`stream.online` / `stream.offline`) | Seconds |
| YouTube | Polling | Up to ~60 seconds |
| Kick | Webhook (`livestream.status.updated`) plus a 60-second poll while live | Seconds; viewer count, title and category refresh every ~60 seconds |

Twitch and Kick are nearly instant because they push events to Lumio the moment you go live. YouTube offers no comparable push mechanism for this, so Lumio polls on a background cadence - roughly once a minute. Going offline is detected the same way.

**Kick in detail.** The webhook carries go-live, stream end and title/category changes. While a Kick channel is live, Lumio also asks Kick's API once a minute for the viewer count, title and category - one call per live channel, none while you are offline. That poll is also a safety net: if the stream-end webhook never arrives, the card flips to offline once Kick has reported the stream as not live **twice in a row** (about two minutes). One failed or "not live" answer is never enough to end a running stream. When the Lumio API starts, or when you connect Kick, Lumio checks the channel once, so a stream that started or ended while no webhook could reach Lumio is picked up right away. Kick reports the category only through its API, so it appears with the first poll, up to a minute after go-live.

### What changes the indicator

The dashboard card switches to **Live** when the backend receives:

- A Twitch EventSub `stream.online` event, **or**
- A YouTube polling response showing a broadcast as live, **or**
- A Kick `livestream.status.updated` webhook with `is_live: true` (or Kick's API reporting the channel as live when Lumio checks it at start).

It switches back to offline when the platform stops reporting the stream as live (EventSub `stream.offline` for Twitch, the poller sees the broadcast ended or disappear for YouTube, and for Kick the `is_live: false` webhook or two consecutive "not live" poll answers).

### What the UI polls

The dashboard itself polls the Lumio API on a **30-second** cadence for the latest cached status. It also listens for **WebSocket events** (`channel:online`, `channel:offline`, `channel:status_update`) so changes appear faster than the 30-second tick when the WebSocket is connected. When the browser tab becomes visible again (e.g. you alt-tab back), it fetches immediately - so switching windows and coming back always gives you a fresh read.

## What you see while live

Per-platform, the live card shows:

- **Channel avatar** with a pulsing red dot indicator.
- **Channel name** and platform name, plus an external-link icon that opens the channel (for a live YouTube broadcast, the link points at the broadcast itself).
- **Live** badge in red.
- **Viewer count**, written out in full (for example `12,345`).
- **Likes** and **total views** for YouTube, when the broadcast reports them.
- **Stream title** (truncated if long).
- **Category / game** (if the platform provides it).

Not every platform reports every field - the category may be blank if you haven't set one, and the viewer count is omitted when the platform doesn't report it. The card hides fields that aren't present.

In the Multichat, the viewer count next to each platform tab is shortened instead (`1.2k`, `15.3k`, `1.4M`), and its display - along with likes and total views - is controlled by the toggles in the chat settings panel.

### Upcoming YouTube broadcasts

YouTube channels also display **upcoming (scheduled) public broadcasts** below the main channel card, and the avatar carries a yellow dot while an upcoming broadcast is pending and nothing is live. Each upcoming broadcast shows a yellow **Upcoming** badge, the broadcast title, the scheduled start date/time when available, and a link to the broadcast. It appears here even if YouTube has not supplied a chat ID yet. When the broadcast goes live, it moves up into the main live card. Upcoming broadcasts that are deleted from YouTube are cleaned up automatically. Unlisted and private broadcasts do not appear through public Streams-tab discovery.

## Why it matters: resource-aware workers

Channel status isn't just cosmetic - the **Spotify worker** keys off it. It only runs while a channel is live (or while manual connect is active). This saves API calls against Spotify and avoids writing track-change events to the database when nobody is watching.

This is why you may notice Spotify "Now Playing" not updating the moment you open the dashboard - it waits until you're live. The Connect button below is the escape hatch.

## Spotify: manual connect

If you need Spotify running **before** you actually go live - for pre-stream testing, a countdown scene that shows the upcoming song, or overlay development - use the **Connect** button.

1. Open **Dashboard > Music** (or the **Popout > Music** page).
2. Click **Connect**. The Spotify worker starts immediately.
3. The button is replaced by a status row showing the remaining time as a countdown, next to a **Disconnect** button.
4. The worker runs for up to **30 minutes**.
5. If you go live during that window, the worker stays up automatically beyond the 30 minutes, following your real live status.
6. If you don't go live, the worker stops when the countdown hits zero.

You can also **Disconnect** manually to stop it early. While a channel is live, the whole control is hidden - the worker is managed for you and there is nothing to switch on.

Manual connect state is synced across browser tabs and popout windows - start it in one tab and the control in another updates immediately without a reload.

## Permissions

Live status and Spotify's manual connect are both governed by the Spotify permissions on your role.

| Capability | Permission |
|---|---|
| View channel status (dashboard cards, Multichat viewer counts) | `spotify:read` |
| See Spotify manual connect status | `spotify:read` |
| Start / stop Spotify manual connect | `spotify:worker` (backend returns 403 otherwise) |

If a 403 is returned for the Spotify worker toggle, the UI surfaces a toast - you likely don't have `spotify:worker` on your role. Ask an admin to grant it, or use a role that includes it. The **Connect** and **Disconnect** buttons are hidden outright for roles without `spotify:worker`. The toast closes after five seconds, or you can click its ✕. Hover over it or move keyboard focus into it to pause the countdown; it resumes with the time left when you leave.

## YouTube broadcast selector in Multichat

When YouTube broadcasts are active (live or upcoming with pre-stream chat), a broadcast dropdown appears next to the YouTube platform tab in the Multichat. A small chevron opens the list:

An upcoming broadcast needs a `liveChatId` before it appears in this dropdown. It may already be visible on the dashboard while the chat ID is still being resolved.

- **All Broadcasts** shows messages from every active broadcast (useful for reviewing history across streams).
- Each broadcast entry shows a status badge (**Live** in red, **Upcoming** in yellow) along with the broadcast title and scheduled start time (for upcoming).
- The dropdown auto-selects the live broadcast when one starts.
- The selection is remembered across page reloads.

When sending a message with YouTube selected, it goes to the currently selected broadcast. If replying to a message, the reply always targets the original message's broadcast regardless of the dropdown selection.

## Tips & best practices

- **Don't poll the dashboard yourself.** The built-in 30-second polling + WebSocket push is enough. Reloading the page doesn't make detection faster.
- **Trust EventSub for Twitch.** If Twitch says you're offline but you just went live, give it ~10 seconds. If it still doesn't flip, check **Dashboard > Connections** for token issues.
- **Use manual Spotify connect sparingly.** It's fine for testing, but leaving it on burns API quota against Spotify. It auto-stops after 30 minutes on purpose.
- **Bookmark the Music popout.** If you use Spotify manual connect routinely (e.g. to warm it up before every stream), the popout URL is shorter to hit than clicking through the dashboard.
- **Keep tokens healthy.** Status detection depends on valid platform OAuth tokens. A failed token refresh = stale status. Token refresh runs automatically, but a "connection needs attention" notification in the bell is a sign to reconnect.

## Troubleshooting

**I'm live but the dashboard still says offline.**

- Twitch: wait 10-15 seconds. If still offline, check **Dashboard > Connections** - your Twitch connection may have lost permissions.
- YouTube: wait up to 60 seconds for the next poll. Refresh the page or alt-tab away and back to force an immediate refetch.
- Kick: the badge depends on Kick delivering its webhooks to Lumio. If it never flips, the webhook URL is probably not set in the Kick developer settings (see [Webhooks](/features/webhooks#kick)); Lumio's check at API start or at the next Kick reconnect still picks the stream up.

**I ended my stream but the dashboard still says live.**

- Same as above - Twitch and Kick should clear in seconds; YouTube takes up to a minute. On Kick, a missed stream-end webhook is corrected by the poll after about two minutes.
- If it persists for more than a couple of minutes, refresh the browser tab.

**Viewer count shows 0 (or is missing).**

- Some platforms report 0 on stream start before viewers arrive.
- When the count isn't reported at all, the UI simply hides the field.

**Spotify shows nothing even though I'm live.**

- Check that Spotify is connected in **Dashboard > Connections**.
- If you're live but there's no currently-playing track on your Spotify account, there's nothing to show.
- If you recently reconnected Spotify, wait 30 seconds for the worker to pick up the new token.

**Manual connect countdown is showing "0:00".**

- Expired. Click **Connect** again to start a new 30-minute window.

**"Connect" button returns a permission error.**

- Your role lacks `spotify:worker`. Ask an admin (or whoever manages roles on the account) to grant it.

## Related docs

- [Connections](/user-guide/connections) - connecting Twitch/YouTube/Kick/Spotify and handling token refresh errors.
- [Music](/user-guide/music) - full Spotify feature overview including the Now Playing widget and overlay integration.
- [Events](/user-guide/events) - the stream-time events that get logged while you're live.
- [Notifications](/user-guide/notifications) - where connection/token issues surface if detection stops working.

---

## User Guide / Tokens

Source: https://docs.lumio.vision/user-guide/tokens

# Tokens

Generate popout tokens for browser sources, dashboards, and other unattended views that need access to your channel without a logged-in browser session. Open **Settings**, select the channel, then choose **Access → Popout Tokens** (`/dashboard/settings/channel/tokens`). A token link is a secret: treat it like a password. [API keys](./api-keys.md) authenticate programmatic API calls; popout tokens authenticate popout views such as OBS browser sources.

## What Are Popout Tokens?

Popout tokens (prefix `lm_pop_`) are secret strings that authenticate a single URL without your browser cookies. By default they never expire, but you can optionally set an expiry time or revoke a token at any point (see [Token Management](#token-management)). They are designed for:

- **Browser sources** - drop a URL with `?token=lm_pop_…` into OBS, no login UI required
- **Stream-deck buttons** - open a popout view directly to a control surface
- **Shared dashboards** - give a moderator read-only access to a single view
- **Remote control overlays** - receive live events on another machine

## Creating a Token

Creating a token opens a **full-screen wizard** over the settings window with three steps. Choose **New Token** in **Access → Popout Tokens** to start:

1. **Identity** - optionally enter a **label** (only for your reference) and choose who the token belongs to. Leaving the assignment on **Yourself** binds the token to you; pick a **member** to attribute its actions to that user instead. Every token is always bound to someone - removing a member assignment later binds the token to you, the person editing it. You can only pick a member whose role has no permission you lack yourself, so only someone holding every permission can assign a token to the account owner.
2. **Permissions** - tick the **permissions** the token may use (e.g. `events:read`, `events:create`, `events:userinfo`, `overlays:read`, `spotify:read`, `spotify:playback`, `chat:read`, `chat:write`, `chat:userinfo`, `chat:ban`, `chat:timeout`, `chat:delete`, `chat:notes`). The `chat:userinfo` / `events:userinfo` scopes are what let a popout open the **user info card** when you click a name (profile, follow status, moderation log); leave them unticked for a display-only browser source. You can only select permissions you hold yourself - ones outside your own access are shown disabled. At least one permission is required before you can continue.
3. **Lifetime** - choose when the token expires (see [Token lifetime](#token-lifetime) below). The default is **Never**.

Click **Create token** on the last step, then **copy the full token immediately** - the secret is shown only once on the final screen. That screen has no close (✕); press **Done** when you have copied the token.

A token can never grant more permissions than the user who creates or edits it. This is enforced on both the create and the edit path (identically on the GraphQL and REST APIs): if you request a permission you do not currently hold, the request is rejected. If the member a token is assigned to loses a permission later, the token stops using it on the next request; it works again if the member gets the permission back.

## Using a Token

Append the token as a `?token=` query parameter to any URL that supports popout authentication:

```
https://lumio.vision/popout/events?token=lm_pop_xxxxxxxxxxxx
```

On the **first load**, the raw token in the URL is exchanged **once, server-side**, for a short-lived **popout session** (a 15-minute `httpOnly` cookie), and the page redirects to the token-less URL. From then on the raw token no longer appears in the address bar, the WebSocket URL, or any network request - WebSocket subscriptions, REST proxy calls, and SSR data all authenticate through the session cookie. The session is refreshed transparently for as long as the token stays valid, so a browser source can stay open indefinitely.

You still only pass the token once in the URL. **Saved URLs keep working:** an existing OBS browser source whose stored URL contains `?token=lm_pop_…` is exchanged automatically on load - no setup breaks.

### Where Popout Tokens Work

Lumio exposes five popout pages plus the overlay route. Popouts live on the dashboard host (`lumio.vision`) and accept `?token=` for popout-token auth. Overlays live on their own host (`overlay.lumio.vision`) and carry their **own** access token, which is not a popout token - you get the complete URL from **Copy Link** on the overlay card.

| URL | Host | What it shows | Recommended permissions |
|-----|------|---------------|-------------------------|
| `/popout/events` | `lumio.vision` | Live event feed (followers, subs, cheers, raids, redemptions, tips) with channel-status indicator | `events:read` (+ `events:userinfo` to open the user info card from event rows) |
| `/popout/test-events` | `lumio.vision` | Test-event catalog and sending confirmation, usable as an OBS dock from 320 px width | `events:create` (required to show the catalog and send) |
| `/popout/chat` | `lumio.vision` | Unified multi-platform chat view with moderation actions | `chat:read` (+ `chat:write` to send, `chat:ban`/`chat:timeout`/`chat:delete` to moderate, `chat:userinfo` to open the user info card from chat rows) |
| `/popout/music` | `lumio.vision` | Spotify "now playing" widget with playback controls | `spotify:read` and `connections:read` for channel status (+ `spotify:playback` to control playback) |
| `/popout/obs` | `lumio.vision` | OBS Remote control panel (scenes, stream/recording state) | `settings:read` |
| `/overlay/{key}` | `overlay.lumio.vision` | Any overlay, rendered as a browser source | _none - the overlay's own access token is already in the URL_ |
| `/overlay/{key}/preview` | `overlay.lumio.vision` | Preview of an overlay inside the dashboard | _same as above_ |

Overlays are intentionally separate: each one has its own access token, minted for the overlay rather than for a person, and revocable on its own from the overlay's menu. Loading `/overlay/{key}` without that token returns _"403 - Access token required"_. See [Overlays](./overlays.md).

The Test-Events popout uses the same searchable catalog as the dashboard side sheet. A popout link must carry `events:create` in its own permission list. If it does not, the page says **This popout link is missing a permission** and sends nothing. A signed-in browser uses the current user's permissions. Tests appear in overlays and dashboard activity, not in the Events popout or stored history. The dashboard **Popouts ▾** menu opens or copies the token-free page URL; create the token under **Tokens** for a delegated OBS dock.

## Browser Source Setup

1. Create the popout token with the permissions you need (for `/popout/events` you only need `events:read`) and **copy the secret on the final screen** - it is never shown again
2. Build the URL yourself: take the popout page you want and append `?token=` plus the secret, e.g. `https://lumio.vision/popout/events?token=lm_pop_…`
3. In OBS: **Add → Browser**, paste the URL
4. Width/height: 400×600 for chat, 600×120 for music, 500×400 for events, or at least 320 px wide for the Test-Events dock (rule of thumb)
5. Custom CSS (optional): `body { background: transparent; }` if the popout doesn't already render transparent
6. Optional: during a season the popout wears the [seasonal look](/user-guide/preferences#popouts-and-obs) of the token's user. Append `&season=off`, `&seasonStrength=subtle` (colours only) or `&seasonMotion=off` (no animations) to change it for this URL only - the final screen of the wizard lists these parameters next to the token

## Token Management

The list groups tokens into **Active**, **Expiring soon**, and **Revoked & expired**. The last group starts collapsed; expand it to inspect or restore a revoked token. Open a token row to see permissions grouped by category, its assigned member, prefix and usage dates, then use its edit, revoke or delete actions. Rows stack their details on a phone or narrow window.

Each token in **Settings → Channel → Access → Popout Tokens** shows an **always-visible status line** - **Never expires**, **Expires on {date}**, **Expired on {date}**, or **Revoked on {date}** - alongside a badge that flags a token that is **Expired**, **Revoked**, or **Expiring soon** (within 7 days of its expiry). Each card also shows the assigned member - or **Unknown member** when your role cannot resolve member names (`members:read`) - plus when the token was created and last used. Clicking the pencil icon opens the token in the same three-step wizard, where you can jump straight to any step:

- **Edit** - change label, assigned member, or permissions any time; **Save** is available on every step and only submits the fields you actually changed.
- **Set an expiry** - on the **Lifetime** step, pick a preset or a custom date (see [Token lifetime](#token-lifetime)); the token stops working automatically after that moment. Choose **Never** to make the token non-expiring again. An already-expired token can be pushed back into the future here - its status updates accordingly.
- **Revoke** - on the **Lifetime** step, mark the token revoked without deleting it; all popout URLs using it stop working immediately. A revoked token can be **restored** later from the same step (its secret stays valid).
- **Delete** - permanently remove the token (the trash icon on the card). Unlike revoke, a deleted token cannot be restored; deletion is confirmed in a separate dialog.

### Token lifetime

The **Lifetime** step offers presets - **In 7 days**, **In 30 days**, **In 90 days**, **In 1 year**, **Never**, and **Custom date** - with **Never** as the default. A finite preset expires at the **end of that day in your browser's timezone** (not at an arbitrary minute), and **Custom date** opens a date picker for any future day. Only the resulting absolute moment is stored, never a relative "7 days" rule, so the expiry does not shift if you edit the token later. When creating a token you cannot pick a date in the past; when editing, a back-dated expiry is allowed and acts as a soft-revoke.

Expiry and revocation are enforced on every request by the backend resolver - for both the raw popout token and the short-lived session it is exchanged for on load (the OBS session cookie). An expired or revoked token is rejected exactly like an invalid one, without disclosing which state it is in. A popout that is already open notices within about 30 seconds: its live connection is checked again and closed once the token is revoked, expired or deleted.

**Assigned member leaves** - a token assigned to a member stops working once that member is no longer part of the account. When you remove the member (or they leave), the tokens assigned to them are deleted, and any of their popouts that are still open close within about 30 seconds. Tokens bound to other members are not affected.

**Audit** - actions performed via a popout token are attributed in the audit log to the member the token is bound to (the creator, unless you picked someone else).

## Security Notes

- A popout token is a **bearer credential** - anyone with the URL has the same access. Treat it like a password.
- On load the raw token is swapped for a short-lived session cookie and dropped from the live URL and WebSocket URL, so it no longer lingers where a screen share or proxy log can catch it mid-stream. The URL you **store** (in OBS, a bookmark, a stream-deck button) still contains the raw token, though - so the storage points below still matter.
- URLs are visible in browser history, screen shares and OBS scene exports. Use a member assignment + minimum-permission set so a leaked token can't be abused.
- Tokens assigned to a member are removed automatically when that member leaves the team. A token bound to you keeps working when someone else who used it leaves - revoke it yourself in that case, and revoke any token immediately if you suspect a leak.
- Never paste a popout token into a public chat, ticket, or screenshot.

## API

| Type | Endpoint | Permission |
|------|----------|------------|
| GraphQL Query | `popoutTokens` | `tokens:read` |
| GraphQL Query | `myPermissions` | _any authenticated_ - used by popout pages to know what they can render |
| GraphQL Mutation | `createPopoutToken(input)` | `tokens:create` |
| GraphQL Mutation | `updatePopoutToken(id, input)` | `tokens:edit` |
| GraphQL Mutation | `deletePopoutToken(id)` | `tokens:delete` |
| REST | `GET /v1/tokens` | `tokens:read` |
| REST | `GET /v1/tokens/me` | _any authenticated_ - returns the current caller's resolved permission set |
| REST | `POST /v1/tokens` | `tokens:create` |
| REST | `PATCH /v1/tokens/{id}` | `tokens:edit` |
| REST | `DELETE /v1/tokens/{id}` | `tokens:delete` |

---

## User Guide / API Keys

Source: https://docs.lumio.vision/user-guide/api-keys

# API Keys

Create keys for programmatic access to the Lumio API and the `lumio` CLI. Open **Settings**, select the channel, then choose **Access → API Keys** (`/dashboard/settings/channel/api-keys`). This area holds **Personal keys** tied to your membership and **Service keys** that outlive it.

## Two kinds of key

Both kinds are bearer credentials that authenticate REST and GraphQL requests, carry an explicit permission set, and are shown in full **only once** when created. They differ in who owns them and what happens when a member leaves.

The **Which key for what?** chooser explains both kinds and starts creation. Below it, **Personal keys** and **Service keys** are tabs with counts. Expand a row to see its permissions grouped by category, creation and last-use details, and the actions your role allows. Expired keys are marked in the list. On a narrow window, each row stacks its details beneath the name.

| | Personal key | Service key |
|---|---|---|
| Prefix | `lm_usr_…` | `lm_svc_…` |
| Owned by | You, within the active account | The account |
| Bound to a member | Yes - the member who created it | No member identity at all |
| Survives member departure | **No** - stops working when you leave | **Yes** - keeps working after its creator leaves |
| Best for | Your own scripts, notebooks, the CLI | CI/CD pipelines, servers, long-lived integrations |

Both sections live in the same area and share the same access gate: the `feature:apikeys` feature must be enabled for your plan, and each action is guarded by the `apikeys:*` permission family - `apikeys:read` to view keys, `apikeys:create` to create, `apikeys:edit` to rename **or regenerate**, and `apikeys:delete` to revoke. If an action is missing, your role is lacking the matching permission or the feature is off for your plan.

## A Pro-plan feature

Creating and renaming API keys requires the **Pro** plan - `feature:apikeys` is enabled on Pro and locked on the Free plan.

**Downgrading never strands a live key.** If your account moves off Pro, any keys you already created **keep working** - the credential is not revoked. So that you are never locked out of a live credential, the API Keys area stays reachable in a **locked state**: you can still **view and revoke** your existing keys, but **Create**, **Rename** and **Regenerate** are disabled with an upgrade hint until you return to Pro. This mirrors the API itself: `apikeys:read` and `apikeys:delete` stay available on a plan-locked account, while `apikeys:create` and `apikeys:edit` (which also gates regenerate) are rejected on both the GraphQL and REST endpoints.

**Finding keys after a downgrade.** If your channel still has live keys, **API Keys** remains in the settings list with a lock. It shows the existing keys and lets you revoke them; creation and editing stay disabled. The **Subscription** area also links to it. Without live keys, the area is hidden when the plan lacks the feature. A direct link to `/dashboard/settings/channel/api-keys` opens the same area.

## Personal keys (`lm_usr_…`)

A personal key is bound to **you within the current account**. Use it for your own scripts and for signing in to the `lumio` CLI.

- **Member-bound lifetime.** A personal key stops authenticating the moment you are no longer a member of the account. If you leave - or an admin removes you - your personal keys for that account are purged and can no longer be used. This is the deliberate contrast with service keys below.
- **Create** - click **Create API key**, give it a **Name**, optionally set an **Expires** date (leave it empty for no expiry), and tick the **permissions** the key may carry. The picker lists the full permission registry, grouped by category with a search box; scopes you do not currently hold are shown disabled. A personal key can additionally carry the **user-scoped** permissions (the Ideas Hub family), since it acts as you.
- **Rename** - the pencil icon changes the display name only; the key material, its permissions, and its expiry are fixed once minted.
- **Regenerate** - the circular-arrows icon rotates the key's secret in place. The name, permissions and expiry stay the same, but the **old secret stops working immediately** and a brand-new key is shown **once**. A confirmation step names the key and warns that anything still using the old secret breaks until you update it. Use it when a key leaks - you recover without a support ticket and without losing the key's configuration.
- **Revoke** - the trash icon deletes the key. Any script using it stops working immediately, and this cannot be undone.

## Service keys (`lm_svc_…`)

A service key is **owned by the account, not by you**. It carries no member identity, so it keeps working even after the member who created it leaves the team - which is exactly what you want for a deploy bot, a server, or a scheduled job that must not break when someone offboards.

- **Survives member departure.** Revoke a service key manually once it is no longer needed - it will not stop on its own when its creator leaves. A card whose creator has since left the account is labelled *Created by a member who has left the account*; the key itself keeps working.
- **Create** - while signed in with an interactive session, click **Create service key**, give it a **Name**, optionally set an **Expires** date, and tick the **permissions** from the same grouped, searchable picker. You can grant only permissions you hold. Because a service key carries **no member identity**, it offers only account-scoped permissions - the user-scoped (Ideas Hub) family is not shown, unlike the personal-key picker.
- **Rename** - changes the display name only; permissions, key material, and expiry are immutable once minted.
- **Regenerate** - with an interactive sign-in session, rotates the key's secret in place (name, permissions and expiry unchanged). You must still hold every scope on the key. The **old secret stops working immediately** and the new key is shown **once**, behind a confirmation step that warns every consumer using the old key will break. Rotate a leaked deploy key without recreating and re-scoping it.
- **Revoke** - deletes the key. Any server or automation using it stops working immediately, and this cannot be undone.

Service key lifecycle actions are recorded in the [audit log](./audit-log.md) as account-scoped events (`account:service_key_created`, `account:service_key_updated`, `account:service_key_revoked`).

## Developer keys (`lm_dev_…`)

Developer keys are managed separately under **Settings → You → Developer → Developer keys** (`/dashboard/settings/developer/keys`), because they are a developer credential rather than a channel key. They are the key `lumio deploy` and CI pipelines use to publish extensions, and they behave differently from personal and service keys:

- **Bound to a developer identity, not an account.** A developer key is owned by either your **developer profile** or a **developer team** - never an account and never a member. Like a service key it keeps working after the member who minted it leaves a team.
- **Not tied to your plan.** Eligibility is *approved-developer status* - an approved developer profile or membership of a developer team - **not** the Pro plan. Free-tier developers can create developer keys even when the `feature:apikeys` page above is Pro-only.
- **Scoped to `extension-dev:*` only.** The scope picker offers only the extension-developer family - `read`, `create`, `edit`, `delete`, `publish`, `analytics`, `payouts`. A developer key can never carry an ordinary account scope (such as `chat:ban`).
- **Profile vs. team.** When creating a key you choose an **Owner**: your own developer profile, or any team where you hold the `team-secrets:edit` right. Teams you belong to without that right are not offered - the backend enforces the same rule. You can see every key across your profile and your teams, but can only rename or revoke a team's keys when you hold `team-secrets:edit` for that team.
- **Create / rename / revoke** work exactly like the other kinds: the full key is shown **once** on creation, rename changes the display name only, and revoke stops the key immediately.

Developer key lifecycle actions are recorded in the [audit log](./audit-log.md) as user-scoped events (`user:developer_api_key_created`, `user:developer_api_key_updated`, `user:developer_api_key_revoked`).

## The one-time reveal

When you create either kind of key, the full secret is shown **once**, on the creation dialog's final screen, with a **Copy** button. Copy it before pressing **Done** - Lumio stores only a hash of the key, so it can never be shown again. The card afterwards shows only the key's short prefix (for example `lm_svc_ab…`), never the secret.

**Regenerating** a key reveals its new secret exactly the same way - once, with a **Copy** button - and the previous secret is invalid from that moment on. So if you lose a secret you no longer have to revoke and recreate the key: **Regenerate** it instead, keeping the same name, permissions and expiry.

## What scopes a key can carry

The picker renders the account's full permission registry - the same catalogue used by the role editor - grouped by category with a search box, rather than a short curated list. This lets a key do everything the channel or user behind it can, which is the whole point of an API key.

- **Personal keys** offer account-scoped permissions **and** the user-scoped Ideas Hub family (`ideas:*`), because a personal key acts as the member who created it.
- **Service keys** offer account-scoped permissions **only** - they have no member identity, so user-scoped permissions would be meaningless.

A small set of scopes is **never assignable to any key**, regardless of what its creator holds, because a bearer credential that can carry them is too dangerous:

- `apikeys:create` and `apikeys:edit` - a key that can mint or manage other keys would outlive the human it belongs to.
- `tokens:create` - minting popout tokens.
- `account:delete` - deleting the account a key deploys to.

These are the only exclusions; everything else in the registry is offered. The scope list a picker offers is fetched live from the backend (`apiKeyAssignablePermissions`), so it always matches what the API will actually accept - the picker and the API can never drift.

## Permission subset limit

The picker only lets you select permissions **you currently hold**. A permission outside your own access is shown disabled, and the backend enforces the same rule on both the GraphQL and REST APIs - a request for a permission the creator does not hold is rejected. A key can therefore never grant more access than the person who minted it.

A personal key also follows your role **after** creation. If your role loses a permission - for example you are moved from Administrator to Viewer - the key stops using that permission at once. The permission stays on the key and works again if you get it back. Service keys have no member behind them and keep their full scope.

Permissions are **immutable after creation**: renaming a key changes its display name only, never its scopes. To change what a key can do, revoke it and create a new one with the set you want.

## Using a key

Send the key as a bearer token on the `Authorization` header of any REST or GraphQL request:

```
Authorization: Bearer lm_svc_xxxxxxxxxxxx
```

The same header works for a personal `lm_usr_…` key. The `lumio` CLI stores your personal key for you after `lumio login`. See the [REST API](../api-reference/rest-api.md) and [GraphQL](../api-reference/graphql.md) references for endpoints, and [Auth](/features/auth) for how the request is authenticated.

## Security notes

- An API key is a **bearer credential** - anyone holding it has the access it carries. Treat it like a password.
- Grant the **minimum permissions** the integration needs, and set an **expiry** where the key only needs to be short-lived.
- **Revoke immediately** if a key leaks or an integration is retired. For service keys, revoke on offboarding as part of your checklist - they do not expire on member departure.
- Never paste a key into a public chat, ticket, screenshot, or committed source file.

---

## User Guide / Audit Log

Source: https://docs.lumio.vision/user-guide/audit-log

# Audit Log

Lumio has two audit views in the web dashboard: **My Activity** for your own
security history and **Account Audit Log** for account-wide operational events.
Both views are read-only, show timestamps in your selected timezone, and use the same table controls
for filtering, pagination, and row details.

For the backend readers and event catalog behind these pages, see the
[Audit Log feature reference](../features/audit-log.md).

## Where to find it

| View | Sidebar path | URL | Who can open it |
|------|--------------|-----|-----------------|
| **My Activity** | **Settings → You → Security → Activity** | `/dashboard/settings/security/activity` | Any signed-in user |
| **Account Audit Log** | **Settings → Channel → Control → Audit log** | `/dashboard/settings/channel/audit-log` | Account members with `audit-log:read` |

**My Activity** is self-only. It does not use account RBAC and it does not show
other members' activity, even when you are an Owner or Administrator.

**Account Audit Log** is account-scoped. It is the **Audit log** tab of the
[channel settings](./channel-settings.md); the tab is visible only to members whose
active account role grants `audit-log:read`, and the tab's route is protected by
the same permission. Owner and Administrator hold it by default;
Moderator does not.

## My Activity

The **My Activity** page shows personal security events tied to your Lumio user:

- Sign-ins and failed sign-ins.
- OAuth grants.
- Personal API-key lifecycle: creating or revoking one of your own `lm_usr_*`
  API keys.
- Two-factor setup, authenticator app and passkey additions/removals, recovery-code use and changes, password and sign-in-method changes, data exports, and deletion requests.

Rows are keyed to your user identity, not to the active account. Switching
accounts does not turn this into an account-wide log, and a popout, overlay,
widget, or extension token cannot read it.

## Account Audit Log

The **Account Audit Log** page shows tenant-level events for the active account:

- Role creation, updates, deletion, and permission changes.
- Member role assignments, with the acting user shown in the **Actor** column.
- Channel connections added or removed.
- GDPR erasure rows written for account-scoped data cleanup.

The page never shows another account's rows. If you belong to multiple accounts,
use the account switcher first, then open **Settings → Channel → Audit log** for the account
you want to inspect.

## Filtering

Both pages have a filter panel above the table:

| Filter | Effect |
|--------|--------|
| **Event type** | Narrows the table to one exact event type. The list only contains event types that belong to the current view's scope. |
| **From** | Shows events on or after the selected day in your timezone. |
| **To** | Shows events on or before the selected day in your timezone. |

Changing a filter applies it immediately and returns the table to the first page.

## Table

Events are shown newest first. Each row includes:

- **Time** - the event timestamp in your selected timezone; expanded details also show UTC.
- **Event** - a readable label for the audit event type.
- **Actor** - account view only; the acting user's ID prefix when the row has an actor.
- **IP address** - the captured client IP; shows **Unknown** ("Unbekannt" in
  German) when none was captured.
- **Device** - the device, browser and operating system read from the captured
  user agent (e.g. "Chrome 141 · macOS"), as text without an icon. It never shows a
  raw or bogus value and never guesses: a user agent it cannot read - absent, a
  non-browser client, or junk - shows **Unknown**, and a known browser with an
  unreadable operating system still shows the browser (e.g. "Chrome 141 ·
  Unknown").
- **Location** - city and country when GeoIP enrichment is enabled and resolved.
- **Details** - expands the row.

Click a row to expand its actor, session, involved channels, exact UTC time,
raw JSON (with **Copy**), and user-agent. In Streamer Mode the IP is partly
covered, the location shows as `••••••••`, the user-agent is hidden, and raw
JSON starts closed; each row has its own **Eye** to reveal the IP and the
location. Rows older than
12 months are labelled **Anonymized**; rows older than 24 months
are deleted (GDPR-erasure records after 36 months).

Select rows across pages to **Export selection**, or export the current filter
or all rows as CSV or JSON. The account export requires `audit-log:read`; the
personal export is self-only. CSV values are escaped for spreadsheet use. A
selected export accepts at most 1,000 event IDs.

## Pagination

Each page loads 50 events. Use **Previous** and **Next** below the table to move
through older or newer pages. The footer shows the current page number and the
total number of matching events for the active filter.

## Related

- [Roles & Permissions](./roles-and-permissions.md) - grant `audit-log:read` to account roles.
- [Audit Log feature reference](../features/audit-log.md) - scoped readers, permissions, API fields, and event catalog.
- [REST API](../api-reference/rest-api.md#audit-log) and [GraphQL API](../api-reference/graphql.md#audit-log) - protocol details for `GET /v1/me/audit-log`, `GET /v1/account/audit-log`, `myAuditLog`, and `accountAuditLog`.

---

## User Guide / Developer Limits

Source: https://docs.lumio.vision/user-guide/developer-limits

# Developer Limits

Open **Settings → You → Developer → Limits** (`/dashboard/settings/developer/limits`) to see the resource limits that apply to your developer account and its extensions. The area is in the settings window, whether you currently have a channel selected or not.

## Viewing Limits

The area has three tabs, plus a **Request increase** button in its header that starts a request for any configurable limit:

- **Developer / Team** - the developer-level limits that apply as defaults to all your extensions
- **Extensions** - a table of your extensions with their resolved sound limits and a **Request increase** button per row
- **Requests** - your limit increase requests, with a badge showing how many are still open

### Limit Categories

| Category | Limits | Configurable |
|----------|--------|:---:|
| Bundled Sounds | Sounds per extension, file size per sound, total sound storage | Yes |
| Extension Bundle | Files per version, file size, total bundle size | No |
| Runtime | Uploads per install, upload size | No |
| Store Listing | Screenshots, screenshot size, icon size | No |

Each category card is badged **Configurable** or **Fixed**. Configurable limits can be increased via a request and carry a source label - **Default**, **Developer override** or **Extension override** - showing where the current value comes from. Fixed limits apply equally to all developers and cannot be requested.

## Requesting a Limit Increase

The request wizard runs in four steps:

1. **Select Scope** - **Team / Developer account** (applies to all your extensions) or **Specific extension** (then pick one from the list)
2. **Select Limits** - tick one or more of the configurable limits; each shows its current value
3. **Enter Values** - pick a preset for each selected limit or switch to **Custom** and type a number. The requested value must be higher than the current one. Add a reason of at least 20 characters.
4. **Confirmation** - review the scope, every current → requested pair and your reason, then **Submit Request**

Selecting several limits in one pass submits one request per limit.

## Request Status

Each request goes through a review process:

| Status | Meaning |
|--------|---------|
| Open | Submitted, waiting for admin review |
| In Review | An admin is reviewing the request |
| Approved | Approved - the limit is applied automatically |
| Rejected | Rejected - check the review notes for details |

The **Requests** tab splits them into **Open** (which covers both Open and In Review), **Approved** and **Rejected**, each with a count. Click a request to expand your reason, any review notes, and the full timeline of who moved it to which status and when.

---

## User Guide / Developer Payouts

Source: https://docs.lumio.vision/user-guide/developer-payouts

# Developer Payouts

Extension developers are paid their revenue share through **Extensions → Payouts** (`/dashboard/extensions/payouts`). The page is visible to approved developers with the `extension-dev:payouts` permission while the `extension_development` feature is on. It shows your balance, lets you choose a payout method and request a payout, and lists the credit notes of your payouts.

## Before your first payout

A payout needs three things:

1. **A verified developer identity.** Submit the form under **Extensions → Verification** and wait for the review.
2. **Your tax details.** Every payout is documented by a self-billed credit note (*Gutschrift*) that Lumio issues on your behalf, and its VAT depends on these details. Which ones you need depends on your country:

   | You are | You need |
   |---------|----------|
   | In Germany, small business (§ 19 UStG) | Tax number (Steuernummer) or VAT ID, and "Small business: Yes" |
   | In Germany, charging VAT | Tax number or VAT ID, and "Small business: No" — 19 % VAT is added on top of your revenue share |
   | In another EU country | VAT ID |
   | Outside the EU | Nothing |

3. **A payout method** (PayPal or SEPA bank transfer; Stripe Connect is not available yet).

## Tax details

The verification form asks for the tax details in step 2 (**Business and tax data**). The small-business question appears only when the country is `DE`; "Not answered" leaves it open. After you submitted the form, the **Tax details** card on the verification page keeps them editable in every status, including after approval. Saving does not reset the review and never changes a credit note that was already issued. The tax number and the VAT ID take at most 50 characters each.

## Requesting a payout

**Request payout** pays out your whole current balance with the saved method after a confirmation. If it cannot be booked, the page names the reason and nothing is paid out:

| Message | What to do |
|---------|------------|
| Payouts require a verified developer identity | Complete the verification, then request again |
| The credit note needs your tax number or VAT ID / your small-business answer / your VAT ID | Follow the link to the **Tax details** card, complete them, then request again |
| Payouts are unavailable right now because Lumio cannot issue credit notes yet | Lumio's own invoicing data is not configured. Try again later |

## After the request

The payout appears in your payout history as **Pending**:

- **Stripe and PayPal** are sent automatically within about 15 minutes. A Stripe payout is then **Completed**. A PayPal payout is **Processing** until PayPal confirms it.
- **SEPA bank transfers** are made by Lumio's team, and the payout is **Completed** once the transfer is recorded.
- If the provider refuses the payout, it is **Failed**. Your balance is credited back, the credit note is cancelled, and you can request again.

You can have one open payout at a time.

In addition, Lumio pays out your balance automatically once per calendar month when it reaches the minimum for your payout method, unless you already had a payout that month. See [Developer Payouts](../features/developer-payouts.md) for the details.

## Credit notes

The **Credit notes** section lists every credit note and cancellation, newest first, 20 at a time (**Load more** shows older ones). Each row shows:

- the number (`GS-<year>-<6 digits>`) and whether it is a **Credit note** or a **Cancellation** — a cancellation carries negative amounts and the reason (payout failed, your objection, correction); a cancelled credit note is marked **Cancelled**;
- the issue date and the service period (dates in Europe/Berlin);
- the VAT treatment and, once it was mailed, the date you got it by e-mail;
- the gross amount, which streamer mode hides.

**PDF** downloads the document as issued. Right after a payout the PDF is still being generated: the row then says **Document is being generated** instead of offering a download. You also receive every PDF by e-mail.

If Lumio credited you a balance from an earlier developer profile (you came back with a claim code), the next credit notes show that amount as its own first line, "earned through an earlier developer profile", with the date it was released. A payout smaller than that amount uses part of it; the rest appears on the next note.

To object to a credit note, contact Lumio support. An operator records the objection and, if needed, issues a corrected note; the original is never changed. See [Developer Credit Notes](../features/developer-credit-notes.md) for numbering, VAT and retention.

---

## User Guide / Notifications

Source: https://docs.lumio.vision/user-guide/notifications

# Notifications

Notifications are how Lumio nudges you about things that need your attention: pending account invites, someone mentioning you on the Ideas Hub, a recap when a stream ends, and developer-programme events. They live in a dropdown under the bell icon in the dashboard's top bar - no inbox, no separate page, just a quick glance and an inline action.

## Where to find it

The **bell icon** sits in the top-right corner of the dashboard, right next to the Streamer Mode shield toggle. (Your account switcher and avatar live in the sidebar, not next to the bell.) If you have unread notifications, a small badge shows the count (`1`, `2`, … up to `99+`). Click the bell to open the dropdown.

If there's no badge and the dropdown says **No notifications yet.**, there's genuinely nothing - the dropdown doesn't hide anything you haven't dismissed.

## Quick start

1. Click the bell icon in the top-right.
2. Opening the dropdown marks all unread notifications as read and clears the badge, including unread items older than the ten shown here. Items that were unread stay highlighted until you close the dropdown.
3. Read the titles and messages in your dashboard language. If a translation is unavailable, Lumio shows the notification's stored text.
4. If a notification has buttons, click **Accept** or **Decline** to act on an invite in the bell, or **View** / **Review** to open the related page.

That's the quick path for acting on notifications. For controlling how and where notifications are delivered, see [Notification Preferences](#notification-preferences) below.

## The bell dropdown in depth

When you open it, you see:

- A header with the title **Notifications** and a bin (**Delete all notifications**) whenever the list isn't empty.
- The most recent **10 notifications**, ordered newest first.
- Each row shows: **title**, optional **message** (lighter text), **timestamp** (localized to your browser), and - if the notification is actionable - one or more **action buttons**.
- A scrollable list: scroll inside the dropdown to see the full ten.

The dropdown closes when you click outside it, or when you click the bell again. Any other open bell in the dashboard clears its badge at the same time.

## Polling and freshness

The bell polls for notifications every **30 seconds** in the background, even when the dropdown is closed. That means:

- A new notification can take up to 30 seconds to appear after the backend creates it.
- The badge stays roughly in sync without any manual refresh.
- Polling runs silently; if a request fails (network blip, API restart), the UI just keeps the last-known state and tries again 30 seconds later.

If the badge shows unread notifications, opening the dropdown refreshes the list before marking them read. Otherwise, reload the page for a fresh view; the next polling cycle is at most 30 seconds away.

## Notification types

Notifications today include:

- **Account invites** - Someone invited you to join their account. These carry **Accept** and **Decline** action buttons. If the inviter cancels before you act, the entry turns into an "invitation was revoked" notice.
- **@mention in an idea** - Someone mentioned you in a comment on the Ideas Hub. A **View** button takes you straight to the idea.
- **Stream summary** - A recap for the account owner after one of your streams ends, delivered in the bell and (by default) as an email with a viewer chart. Sessions shorter than five minutes are skipped, so test streams don't generate one.
- **Developer programme events** - The outcome of your developer application, extension lifecycle events (created, version submitted / approved / rejected / published, extension suspended), extension access grants, tester invitations, and developer-team invites and membership changes. A team invite addressed to you has **Accept** and **Decline** buttons.

Titles, messages and action labels appear in the dashboard's UI language when translations are available. A notification with no matching translation, or one missing a value needed for its text, shows its stored title or message instead. User-written content, such as review notes or feedback, stays in the language in which it was written.

Platform connection problems are *not* delivered through the bell. A failed token refresh surfaces as a banner at the top of the dashboard instead - see [Connections](/user-guide/connections).

## Notification Preferences

Open **Settings → You → Notifications** (`/dashboard/settings/notifications`) to control how each notification type is delivered to you.

Preferences are tied to your user account, not to a channel - they are available no matter which entry is selected in the account switcher, including your personal profile, and one setting applies across all your channels.

Each category is its own section with an **In the app** and an **Email** switch per type:

| Category | Notices | Configurable |
|---|---|:---:|
| Security | New sign-in, 2FA on/off, authenticator app or passkey added or removed, recovery code used or regenerated, password or sign-in method changed, failed attempts | No |
| Account & channels | Invite; role change, removal, support identity check | Invite: no; others: yes |
| Data & privacy | Export ready, profile deletion scheduled, channel dissolution scheduled, reminded or cancelled | No |
| Stream | Stream summary, connection needs reconnection | Yes |
| Billing (channel owner) | Invoice paid, payment failed, plan changed, cancellation receipt | Payment failure and cancellation receipt: no; others: yes |
| Ideas Hub | @Mentions | Yes |

For every configurable type you can choose one of four options:

| Setting | What happens |
|---------|-------------|
| Off | No notification of any kind is sent |
| In-App | A notification appears in the bell dropdown only |
| Email | An email is sent, with no bell-dropdown entry |
| In-App + Email | A notification appears in the bell dropdown **and** an email is sent |

Defaults vary by type. Security and required privacy notices use **In-App + Email**. New invoices also default to **In-App + Email**. The matrix shows each type's current choice.

Locked rows show a padlock and an **Always on** tag, and always deliver in both channels. They include invites, security notices, export readiness, deletion scheduling, payment failures and cancellation receipts.

Changes take effect immediately; there is no save button.

### What language and timezone are my emails in?

Emails are written in **your** language and show dates in **your** timezone - not the language of whoever triggered them. This follows the **Language**, **Timezone** and **Date format** settings you pick under **Settings → Appearance → Region & Language**:

- If you chose a specific **Language** (English or German), your emails use it.
- If you left **Language** on **Automatic**, emails follow the language your browser last used on Lumio. If you have never opened Lumio in a browser, they default to English.
- Dates and times in an email use your **Timezone** choice first, then the last timezone your browser reported, then UTC. Numeric dates follow your **Date format**; written weekday and month names follow your language. The stream summary's heading uses your time format for its time range.

You do not set this separately for email; it reuses your display preferences. For emails that go to a channel's **owner** (the stream summary and the *reconnect required* alert), it is the owner's language and timezone that apply.

## Actions

Actionable notifications have one or more buttons below the message. **View**, **Review** and similar buttons open a page. Invite buttons act in the bell:

- **Accept** - adds you as a member of the inviting account, switches your active account to it, and reloads the dashboard.
- **Decline** - deletes the invite, so the link in it can no longer be used.
- **Accept a developer-team invite** - joins the team and opens its dashboard page.
- **Decline a developer-team invite** - removes an unused single-use invite. A shared or already-used invite stays available for others. If the invite has already gone, the bell simply clears the action.

Clicking an invite action disables both buttons while the server processes the request. If it fails (e.g. the invite expired or you are already a member), an error message appears at the bottom right and the buttons re-enable. You can retry or open the invitation link.

Once a notification has been **acted on**, the buttons disappear. The notification stays in your list (now read and acted) so you have a trail of what happened.

## Retention

Read notifications are deleted automatically 90 days after they arrived. Unread notifications stay until you read or delete them.

## Permissions

Notifications are always scoped to **you as a user**, not to an account. That means:

- Switching accounts does not change what you see in the bell - your pending invites, mentions, etc. are yours.
- No RBAC permission is required to view or interact with your own notifications; the backend only checks that the notification belongs to you.
- Notifications are private to your own signed-in session. A popout token cannot read them or act on them, even though it belongs to the same user.

| Capability | Required Permission |
|---|---|
| See your own notifications | (none - tied to your user) |
| Open the bell to mark all as read | (none - your own) |
| Delete all | (none - your own) |
| Execute an action button | (none - accepting or declining an invite is a user-level decision, validated against the invite itself) |

## Tips & best practices

- **Clear invites promptly.** Accept or decline them rather than letting them pile up. Declining an account invite removes it. Declining a developer-team invite removes it only when it is unused and single-use; a shared link can still be used by others.
- **Watch the dashboard banners for connection problems.** A platform whose token refresh failed shows up as a banner, not a bell notification. Click through to **Connections** and reconnect.
- **Don't rely on notifications for real-time events.** Chat messages, follows, subs, etc. flow through the WebSocket event pipeline, not the notification bell. Use **Dashboard > Events** or the overlay Event List for stream-time activity.
- **Open the bell to review new notices.** Opening clears the unread badge; notifications remain in the list until you delete them or they expire.

## Troubleshooting

**Badge shows a number but the dropdown contains no unread items.** The dropdown shows the 10 most recent notifications regardless of read state, while the badge counts every unread one. Older unread items may be outside the visible ten; opening the bell marks those as read too and clears the badge.

**I accepted an invite but nothing happened.** Accepting switches your active account to the one you joined and reloads the dashboard. If it didn't, check **Dashboard > Members** for your new membership and switch via the account switcher. The bell notification stays (acted state) as a receipt.

**Invite action buttons are disabled and stuck.** The request is in flight. Wait a few seconds; if they stay disabled, the action likely failed - refresh the page and the updated state will load via the next poll.

**The bell doesn't appear at all.** You're probably looking at a page outside the authenticated dashboard (e.g. `/overlay/...`, `/login`), or at a fullscreen editor page that hides the top bar. The bell is part of the dashboard shell and only renders when you're signed in.

**I want to disable or reduce notifications.** Open **Settings → Notifications** and set configurable types to Off, In-App (no email), or Email (no bell entry). Locked notices cannot be disabled.

**New notification didn't appear for ~30 seconds.** Expected. Polling is on a 30-second cadence. Reload the page to fetch immediately.

## Related docs

- [Members](/user-guide/members) - sending and managing invites, which is where most of the invite notifications originate.
- [Connections](/user-guide/connections) - reconnecting a platform after a token refresh failure.
- [Roles and Permissions](/user-guide/roles-and-permissions) - understanding the actions behind notification buttons.
- [Ideas Hub](/user-guide/ideas-hub) - @mentions in idea comments that trigger mention notifications.

---

## User Guide / Billing & Subscription

Source: https://docs.lumio.vision/user-guide/billing

# Billing & Subscription

Upgrade your channel to a paid plan, download invoices, and manage the subscription.

## Where To Find It

Open **Settings** at the bottom of the dashboard sidebar, select the channel you own, then choose an area under **Subscription**:

- **Subscription** (`/dashboard/settings/channel/subscription`) - see the active channel's plan and billing cadence, compare plans, start checkout, or request cancellation.
- **Invoices** (`/dashboard/settings/channel/billing`) - see invoices, download PDFs, and open the Stripe Customer Portal to update payment details.

These areas appear only for the owner of the selected channel. A direct short link opens the settings window over the dashboard home; a non-owner sees **No access**. Switch to a channel you own before opening either area.

If billing (Stripe) is not set up on this Lumio installation, the **Subscription** area still shows your current plan with its limits and every plan card, Free included. Only what needs Stripe is switched off: the upgrade buttons, switching to Free and cancelling. A line above the plan cards says "Payments are not set up in this environment." The **Invoices** area shows the note "Billing is not set up in this environment." instead of invoices. Platform admins additionally see that the Stripe keys (`LUMIO__STRIPE__*`) are missing.

## Plans At A Glance

Lumio has two plans: **Free** and **Pro**.

| Limit | Free | Pro |
|-------|------|-----|
| Overlays | 1 | 5 |
| Widgets | 3 | 20 |
| Storage | 100 MB | 1 GB |
| Upload size per file | 10 MB | 50 MB |
| Integrations | 2 | 10 |
| Channel data (chat, events, chatter profiles, moderation) | 365 days (1 year) | 1095 days (3 years) |
| Accounts you can own | 1 | 3 |
| Sounds | 10 | 50 |
| Sound file size / sound storage | 5 MB / 100 MB | 20 MB / 1 GB |

Prices are listed on the **Subscription** page and include VAT. Pro is billed in EUR; both monthly and yearly billing are available (yearly is cheaper per month, and the toggle shows the saving as a percentage).

The plan card itself lists overlays, storage, integrations and how long channel data is kept ("1 year of channel data" on Free, "3 years of channel data" on Pro; a window that is not a whole number of years is shown in days). A muted line under it names what that covers: chat, events, chatter and moderation data. Stream reports do not count against the window: they stay until you [dissolve the channel](./channel-settings.md#danger-zone--dissolve-the-channel). Stream-history curves have separate detail windows: 60-second samples for 90 days and 5-minute samples for 12 months; older history uses the 1-hour rollup. The list is followed by the plan's feature list (automations, bot modules, Copyright Manager, …). Feature availability per plan is shown on every card, so you can compare before you upgrade.

## Picking A Plan

1. Open **Settings → Channel → Subscription**.
2. Compare the plan cards. The plan you are currently on is highlighted.
3. Pick **Monthly** or **Yearly** with the interval toggle.
4. Tick the checkbox above the plan cards (see [Right of withdrawal](#right-of-withdrawal) below). It starts unticked, and the **Switch to …** buttons stay disabled until you tick it.
5. Click **Switch to …** on the plan you want.
6. You are redirected to **Stripe Checkout** - a secure, Stripe-hosted page. Enter your card or other payment method and confirm.
7. On success you land back on `/dashboard?billing=success`. Your new plan is active within seconds.

If you close the Stripe page without paying, you come back to `/dashboard?billing=cancelled` and nothing changes.

### Right Of Withdrawal

As a consumer in the EU you have a 14-day right of withdrawal. Lumio starts your plan as soon as you pay, so before every plan checkout you confirm that in a separate checkbox above the plan cards:

> I expressly request that Lumio starts providing the service immediately, before the 14-day withdrawal period ends. I understand that my right of withdrawal lapses once Lumio has fully performed the contract, and that if I withdraw, I pay a pro-rata amount for the service provided up to that point.

The **Withdrawal information** link next to it opens the withdrawal section of the [terms of use](https://lumio.vision/legal/terms#withdrawal-information) in a new window. The checkbox is required: if you press a **Switch to …** button without ticking it, a message under the box asks you to tick it and no checkout starts. It is shown in your dashboard language (German or English) and never comes pre-ticked. After payment you get an order confirmation by e-mail that repeats the declaration you ticked, with the full withdrawal information and the terms of use.

A renewal of the same subscription needs no new tick; every plan change goes through the checkout again and asks again.

### Starting With Free First

A new channel always starts on Free, during onboarding and in the **Create New Account** wizard (`/account/new`) alike. Paid plans are shown there but cannot be picked: onboarding shows an "Available after Free setup" hint, the wizard a note that you switch to a paid plan afterwards under **Subscription** (or, without Stripe, that payments are not set up). Once your Free channel exists, open **Settings → Channel → Subscription** and upgrade from there - Stripe Checkout links the subscription to the existing channel automatically.

## Managing Your Subscription

Go to **Settings → Channel → Subscription → Invoices** and click **Open customer portal** (or **Payment details at Stripe** in the header). The Stripe Customer Portal opens in a new tab, where you can:

- Update your payment method
- Switch between monthly and yearly billing
- View all past invoices (not just the most recent)
- Download receipts as PDF
- Cancel the subscription

Stripe sends subscription and payment updates back to Lumio. Refresh the page if a recent portal action is not visible yet.

### Cancelling

Choose **Verträge hier kündigen** in **Subscription** to open the plan cancellation dialog, or use the public `/cancel` page from the footer. You can request an ordinary cancellation at the end of the paid period or an extraordinary cancellation with a reason and requested time. The dialog lets you check the receipt address and print the confirmation. See [Withdrawal & Cancellation](/user-guide/withdrawal-and-cancellation) for the signed-out flow and paid extension subscriptions.

For an ordinary cancellation accepted by Stripe, you keep plan access until the paid period ends and the account then moves to Free. Older chat, event, chatter and moderation data follow Free-tier retention at the next sweep; review overlays and storage above Free-tier limits. An extraordinary request waits for operator review and does not change the Stripe subscription automatically. Lumio records and confirms the request even if Stripe needs a retry.

### Re-subscribing

If you cancelled and are now back on Free, just go through **Subscription → Upgrade** again. Your existing Stripe customer is reused, so your payment method is remembered.

## Invoices

The **Invoices** area lists your 20 most recent invoices with date, amount, status, and a PDF download link. For the full history, open the Stripe Customer Portal.

Invoices are generated by Stripe on every successful payment (and on failed ones with status `open`). Lumio does not issue its own invoices - the Stripe invoice is the legal document.

## Coupons

Coupons are created by Lumio staff for custom deals, beta rewards and partner offers. The **Subscription** page has no coupon field - a coupon reaches your checkout because Lumio applies it to the checkout session that is created for you, so you see the discounted price on the Stripe Checkout page itself.

A coupon is **valid** if all of these are true: it exists in Stripe, it is marked active, it has not expired, and it has redemptions remaining. If a coupon you were given does not show up as a discount on the Stripe page, contact whoever issued it.

## What Happens When A Payment Fails

- Stripe automatically retries the payment a few times over the following days.
- Lumio sends the channel owner an in-app and email payment-failure notice; Stripe may also email about the payment.
- The subscription stays active during the retry window - you are not immediately downgraded.
- If all retries fail, Stripe cancels the subscription. Lumio then downgrades the account to Free on the next webhook.

Update your card in the Stripe Customer Portal as soon as possible to avoid interruption.

## Permissions

Two account permissions cover billing:

| Permission | What it lets you do |
|------------|----------------------|
| `plan:read` | See the current plan and its limits |
| `plan:edit` | Change the plan / manage the subscription |

Only the **Owner** role holds these by default. The subscription and invoice areas additionally check that you own the active channel.

The **Invoices** area (invoices + Stripe portal) is **owner-only**: a non-owner opening `/dashboard/settings/channel/billing` sees **No access**. Financial data is restricted to the channel owner.

## Troubleshooting

**"Billing is not set up in this environment" / "Payments are not set up in this environment"**
This Lumio installation has no Stripe connection, so there is nothing to buy or pay. Your plan and Free stay usable. On lumio.vision, contact Lumio support; on your own installation, a platform admin sets the `LUMIO__STRIPE__*` keys.

**"Stripe price ID not configured for this plan"**
That plan has no price configured for the interval you picked. Try the other interval, and let Lumio support know.

**"No Stripe customer found for this account"**
The account has never had a paid subscription, so there is no Stripe customer yet. Go through the Subscription page and complete a checkout - the customer is created at that point.

**"No active subscription to cancel"**
The account is already on Free or the subscription was already cancelled on Stripe's side. Nothing to do.

**Checkout redirected me back but my plan didn't change**
The plan change happens when Stripe posts a webhook to Lumio, not when the browser redirects. It normally takes 2–5 seconds. Refresh the Subscription page - if the plan still shows Free after a minute, the webhook may have failed. Contact support and include your checkout session ID from the URL.

**My coupon did not show up on the Stripe page**
The coupon may have expired, been deactivated, or reached its redemption limit. Contact whoever issued it.

**I cannot open the Invoices area even though I am a member**
The Invoices area is owner-only. A non-owner opening its short link sees **No access**. Ask the account owner to download invoices for you, or ask them to transfer ownership if you are taking over billing.

---

## User Guide / Withdrawal & Cancellation

Source: https://docs.lumio.vision/user-guide/withdrawal-and-cancellation

# Withdrawal & Cancellation

## Withdraw from a contract

Open [Vertrag widerrufen](https://lumio.vision/withdraw) from the site footer. The page uses the legal layout and works while signed out. Enter your name, the email address for the receipt, and which plan or paid extension purchase you mean. If you are signed in, Lumio prefills your name and email address and groups eligible contracts by every channel you may manage; **Other contract** lets you describe a contract yourself. You can also start from **Vertrag widerrufen** beside a contract under **Settings → Channel → Invoices**, or from an installed paid extension's store page. A signed-out withdrawal requires a Cloudflare Turnstile check; a signed-in withdrawal does not, including **Other contract**.

Review the repeated details, then submit. The confirmation shows the time of receipt in Europe/Berlin and a case reference; you can print it. Lumio emails the receipt to the address you entered. A declaration enters the operator queue for review. Any refund is handled manually.

## Cancel a subscription

Open [Verträge hier kündigen](https://lumio.vision/cancel) from the footer. The page uses the legal layout and itself contains the **Jetzt kündigen** confirmation button. If signed in, select a plan or paid extension subscription from contracts grouped by every channel you may manage; already cancelled subscriptions are disabled. You can choose **Other contract** and enter a description. A signed-out cancellation and a signed-in **Other contract** cancellation both require a Cloudflare Turnstile check. A signed-in cancellation of a listed contract does not.

Choose ordinary cancellation for the end of the current paid period, or extraordinary cancellation with a reason and requested time. Check the receipt address and submit. The confirmation shows the receipt time and case reference and can be printed. An ordinary signed-in cancellation is sent to Stripe for period-end cancellation; an extraordinary or public request is reviewed by an operator. Submission records your request even when a Stripe change is still pending.

For a plan, **Settings → Channel → Subscription** also has a **Verträge hier kündigen** button. Its dialog uses the same fields and offers a printable receipt. The consequences of moving to Free remain visible on the Subscription page. See [Billing & Subscription](/user-guide/billing) for invoices and payment settings.

---

## User Guide / Ideas Hub

Source: https://docs.lumio.vision/user-guide/ideas-hub

# Ideas Hub

The Ideas Hub is where you can share feature requests and feedback directly with the Lumio team - and vote on suggestions from other community members. It is open to all registered users and, depending on configuration, to unauthenticated visitors as well.

## Where to Find It

- **Dashboard** → **Hub** → **Ideas** (`/hub/ideas`) - accessible when logged in to any account.
- **Public site** (`/ideas`) - may be open for browsing without a login (when the public flag is enabled by the Lumio team).
- **Feed** - subscribe at `/ideas/feed.xml` to follow new ideas in your feed reader.

## Browsing Ideas

The main ideas page shows all submitted ideas. You can narrow the list using the controls at the top:

- **Status filter** - show only `Open`, `Planned`, `In Progress`, `In Testing`, `Completed`, or `Closed` ideas.
- **Category filter** - show ideas in a specific category.
- **Search** - type to filter by title or description.
- **Sort** - order by **Newest**, **Most Voted** (net score, upvotes minus downvotes), **Most Discussed** (comment count), or **Recently Updated**.

Your filter and sort choices are written into the page URL, so you can bookmark or share a filtered view.

Each idea card shows the category badge, a status badge, the title, a short description excerpt, up to three tags, the author and creation date, vote counts, and the comment count. The list loads more ideas automatically as you scroll - there is no pager.

## Statuses

| Status | Meaning |
|--------|---------|
| Open | Accepting votes and comments |
| Planned | Acknowledged and on the roadmap |
| In Progress | Being actively worked on |
| In Testing | Feature built, being tested before release |
| Completed | Feature shipped |
| Closed | Declined or no longer active |

`Completed` and `Closed` ideas are read-only: voting, commenting, and editing are all switched off for them.

## Creating an Idea

To submit a new idea, click the **Share your idea...** box at the top of the list. A full-screen, three-step wizard opens:

| Step | Fields | Required | Notes |
|------|--------|:--------:|-------|
| 1 | Title, Category | Yes | Title is capped at 200 characters; pick one of the categories the Lumio team configured |
| 2 | Description | No | A rich-text editor with formatting buttons - you style text directly, you do not write Markdown |
| 3 | Tags | No | Type to search existing tags, or click the `+` suggestion to create a new one |

Finish with **Submit Idea**. The idea appears in the list with `Open` status and a vote count of zero.

> You need to be logged in to submit an idea. Anonymous visitors can browse and read but cannot create.

## Voting

Each idea has two vote buttons - thumbs-up (upvote) and thumbs-down (downvote). Click either button to cast your vote. Your active vote is highlighted. Click the same button again or the other button to change or remove your vote.

- You can only have one vote per idea at a time.
- Removing a vote is done by clicking your active vote button again.
- Ideas with status `Completed` or `Closed` no longer accept votes; the page shows a notice instead of the buttons.

> Voting requires an account login.

## Commenting

Open an idea by clicking its title to go to the detail page. A comment field appears below the idea content.

**Posting a comment:** type your message in the rich-text field and click **Comment**. The editor gives you formatting buttons - you do not write Markdown.

**Replying to a comment:** click the **Reply** button under any comment. A reply composer slides in from the bottom of the screen. Replies nest up to three levels deep; below that, further replies attach at the deepest level.

**Editing your comment:** click the **Edit** (pencil) icon on your own comment. The body becomes an editable field; save with the **Save** button.

**Deleting your comment:** click the **Delete** (trash) icon on your own comment. A confirmation prompt appears, and your comment is removed for good. If someone has replied to it, the replies stay and your comment shows as **This post was deleted.** - without its text, your name, votes or a reply button.

**Deleting your idea:** if other people have commented on it, their comments stay and the idea shows as deleted, without its title, description or your name. Your own comments under it go, except those someone replied to. A deleted idea is titled **Deleted idea** and carries the note **This post was deleted.**; its comments stay readable, but it takes no more votes, comments or edits. It stays in the idea list with the same placeholder and is left out of the feed. Without comments by others, the idea is removed completely. The same applies to your ideas and comments when you [delete your profile](./privacy-and-export.md#delete-your-profile).

Like votes, commenting is closed once an idea reaches `Completed` or `Closed`.

## @Mentions in Comments

When writing a comment, type `@` to mention other users who have already interacted with the idea. An autocomplete dropdown appears showing matching participants - the idea author, users who voted, and previous commenters - filtered by whatever you type after `@`.

- Select a name from the dropdown to insert a highlighted mention into your comment.
- Mentioned users receive a notification in their bell dropdown and, depending on their notification preferences, an email as well.
- Mentions render as highlighted `@Name` text in the posted comment.

Only participants of the idea appear in the autocomplete - you cannot @mention arbitrary users, and a mention that slips past the dropdown is dropped when the comment is saved. Mentioning yourself sends no notification. Mentions work in comments and comment edits only; the idea description field has no mention autocomplete.

> @mentions require a login. The autocomplete dropdown is not shown to anonymous visitors.

## Sharing an Idea

Every idea has a public page you can link to directly. On an idea's detail page, click the **Share** button in the action bar to copy the idea's public URL (`/ideas/{id}`) to your clipboard - the button briefly shows **Link copied** to confirm.

Anyone with the link can open the public idea page to read the idea along with its comments and timeline, without signing in (when the Ideas Hub public pages are enabled by the Lumio team). Visitors still need to sign in to vote or comment. The **Share** button appears on both the dashboard detail page and the public idea page.

## Editing Your Idea

On your own idea's detail page, click the **Edit** button. The same three-step wizard opens, pre-filled, and you can update:

- Title and Category (step 1)
- Description (step 2)
- Tags (step 3)

Finish with **Save Changes**. Changes to the title, description, or category are recorded as timeline entries. Tag changes are saved but are not recorded on the timeline.

> You can only edit ideas you submitted. Editing other users' ideas requires a moderation role. The **Edit** button disappears once an idea reaches `Completed` or `Closed`.

## Timeline

The detail page for each idea shows a timeline of status changes and edits, between the idea body and the comments. This gives you a clear history of how the idea has progressed - when it was submitted, when it moved from Open to Planned, and when the title, description, or category was updated. Entries are listed newest first; the five most recent are shown, with a **Load more** control for the rest.

## Tags

When submitting or editing an idea, start typing in the **Tags** field to search existing tags. If the tag you want does not exist yet, click the `+` entry at the top of the suggestion list to create it. Tags are shared across all ideas and are stored in lowercase, so `Overlays` and `overlays` are the same tag. An idea can carry up to 20 tags.

## Feed

Subscribe to the Atom feed at `/ideas/feed.xml` to track new ideas without visiting the site. The feed contains the 50 most recently created ideas regardless of status (deleted ideas are left out), and each entry links to that idea's public page, carries its category and status, and summarises its vote and comment counts. The feed is served only while the public Ideas Hub pages are enabled by the Lumio team.

## Troubleshooting

### "I can't see the Ideas Hub"

The dashboard Ideas Hub requires the `system:ideas_hub` feature flag to be enabled by the Lumio team. If **Ideas** is not visible under **Hub** in the sidebar, the feature may be temporarily unavailable.

The public pages (`/ideas`, `/ideas/{id}`, and the feed) additionally require `system:ideas_hub_public`. With that flag off, the public pages return "not found" even though the dashboard hub still works for logged-in users.

### "I can't submit an idea or vote"

Creating ideas and voting requires a login. If you are already logged in and the buttons are still disabled, your account may have the Restricted user role, which can read ideas and comments but cannot submit, vote, or comment. Contact the Lumio team.

Votes and comments are also closed on ideas with status `Completed` or `Closed` - that applies to everyone, whatever your role.

### "The submit button is greyed out"

The first step needs **both** a **Title** and a **Category** before it will let you continue, and the title has to be 200 characters or shorter. Description and tags are optional.

### "My comment disappeared but I didn't delete it"

Comments can be removed by Lumio moderators. Deletion is permanent. Replies underneath a deleted comment stay; the deleted comment itself shows as deleted, without its text or its author.

## Related

- [Ideas (Admin)](../admin/ideas.md) - moderation, categories, and tag management
- [Ideas Hub feature doc](../features/ideas-hub.md) - architecture, voting model, WebSocket channels

---

## User Guide / Stream History

Source: https://docs.lumio.vision/user-guide/stream-history

# Stream History

Stream History records running values during a stream and final figures after
it ends. Every time you go live, Lumio records the run as a **session** and
turns it into a **report** - viewer curves, follower and subscriber growth,
chat, emote and GIF totals, donations, and a per-platform breakdown. If you multistream, one session covers all the platforms
you broadcast to at once, and each platform's own title and numbers are kept
separate.

This guide covers the webapp surface. For how the data is collected and the API
behind it, see the [Stream History feature reference](../features/stream-history.md).

## Where to find it

Open **Dashboard > Stream > History** from the sidebar. The nav item appears when
the `feature:stream_history` feature is enabled for your account and your role
holds the `history:read` permission. Stream History is a baseline feature - it is
enabled on every plan, not a paid unlock.

The **Dashboard home** shows recent sessions in its timeline, a 12-month stream
calendar, and a **View all history** link into this page. With `history:read`,
its offline metrics compare Today, 7 days or 30 days with the preceding period;
while live, the **Now** card shows sampled viewer and support figures. The home
history areas use `feature:stream_history` and `history:read`. The full list,
filters, and reports live here on the History page.

## The history list

The top of **Dashboard → Stream → History** summarizes the filtered sessions: stream count and duration, average and highest peak viewers, follower growth, messages, and estimated revenue when you have `history:revenue-read`. A currency switch beside revenue uses your display currency. Amounts are estimates; the assumptions behind them are in [Channel settings → History](./channel-settings.md).

If a connected YouTube channel has not granted the optional Analytics revenue permission, the history list shows one announcement that you can dismiss for that account. Reconnect YouTube and leave Google's revenue checkbox selected to use its figures. The announcement is separate from the persistent hints on the revenue area.

The **Streaming activity** calendar covers the last 371 days in your timezone. Each day shows its stream count and duration; hover, focus, or tap it for that day's streams, titles, platforms, times, peaks, and follower counts. Select a day to filter the list to it; select it again to clear that day. The calendar retains the full year even when the list has a shorter date range, and dims days outside that range.

A sticky toolbar combines search, platform, category, stream type, and date range. The date picker has quick choices for 7, 30, and 90 days, this year, or all time. Its arrangement follows the width of the content area beside the sidebar: wide content keeps the controls on one line; medium content puts search, platform, category, and type on the first line, then date range, result count, sorting, **Export**, and sort direction on the second. In narrow content, including a phone or a tablet with the sidebar open, search sits beside **Filter (n)**, which opens the other controls in a dialog. The result count includes total hours (for example, **44 streams · 162 h**), and sorting shows **Sort: Date** with a separate direction button. Active filters appear as removable chips. Search, filters, and sorting live in the URL (`q`, `platform`, `category`, `type`, `from`, `to`, `sort`, `dir`), so you can bookmark a view. An older link with a `page` parameter still works: the parameter is ignored and the list starts at the top. Returning from a report restores the same list view, including on a phone: the same filters, the same number of loaded streams (up to 200), and the scroll position of the stream you opened. Above 200 loaded streams, the list starts at the top again.

Sessions appear in a sortable table while the list card has at least about 46 rem of space beside the sidebar; at narrower content widths they become cards with their main numbers. Table columns depend on that content width. As it narrows, Chatters, Revenue, Subs, Average viewers, and Viewer trend disappear in that order. The **Viewer trend** column draws a line over a soft area with a dot at the peak; a live stream instead has a red dot at its latest sample. Each row shows its start and end time, or start time and **now** while live. When a stream ends on a later day, the end time carries its date as well (for example **22:10 – 07.10., 02:15**). Estimated amounts in the revenue column, month summary, and overview tiles carry `≈`. Select a column header to sort by it; selecting it again flips the direction. Every number column sorts, including Subs / Members and Revenue. Revenue sorting and the **Revenue** sort option need permission to see revenue and use the amounts shown in the list currency. Date sorting groups rows by month with totals for the **whole filtered set**. A live session has a live badge; the list refreshes while streams run. The list starts with your 25 most recent streams (in the chosen sort order) and loads 25 more as you scroll towards the end, on desktop and on a phone alike. A line under the list shows how many are loaded, for example **25 of 132 streams**, and **All 132 streams loaded** at the end. The **Load more** button under the list loads the next 25 without scrolling, for keyboard and screen-reader use, and screen readers announce each loaded batch. Changing a filter, the search, the sorting, the date range, or a heatmap day starts again with the first 25 and scrolls back to the top of the list. If loading more fails, the rows already loaded stay and a **Try again** row appears at the bottom. **Export** always covers every stream that matches the filters, not only the loaded ones. You can select a row or card to open its report.

While a stream runs, its peak and average viewers, duration, messages,
followers, paid Subs or Members, gifted Subs, unique chatters and available
revenue are running values marked **so far**. The viewer trend follows the
minute samples. YouTube subscriber growth appears **after the stream**, not as
zero while live. If a value has no sample yet or its chat calculation is
unavailable, the list shows **—** with an explanation instead of zero.

The list's **Export** menu is headed **Filtered list · n streams**. **CSV (table)** downloads a ZIP of `streams.csv` (one row per stream), `months.csv`, and `totals.csv`; **JSON** downloads all fields in a machine-readable form. Both cover the currently filtered set, up to 5,000 sessions. The menu notes that amounts use the selected currency and the ECB rate for each stream day. Without `history:revenue-read`, it says revenue is omitted. With that permission, Streamer Mode adds a **Contains amounts** warning: downloaded files can contain amounts even when they are masked on screen.

The page shows a layout-shaped skeleton while its first data load runs, with phone cards on small screens. Later filter and sort changes keep the current rows in place and show a progress bar; loading more streams shows three placeholder rows at the bottom of the list. An empty account and a filtered view with no matches have separate empty states.

## The report page

The report starts with the session title, platforms, date, duration, and category. Next to **Export** and **Share** in that header, a currency switch sets your display currency; anyone who can open the report sees it, because it is a personal setting. Changing it updates every amount on the page: the revenue card and the donation, Super Chat and Super Sticker values in the strip. Four headline cards show peak viewers, average viewers, messages, and follower growth with small trends. The remaining metrics sit in a compact strip; a metric with no activity is left out, except each platform's own counter: Bits for Twitch, KICKs for Kick, and Super Chats and Super Stickers for YouTube appear with 0 whenever that platform was part of the stream. Donations and Super Chat and Super Sticker values appear in your display currency, converted at the ECB rate of the stream date. When an amount was converted, a small **≈ from …** line under it shows the original amounts, for example `≈ from €1.49`. When no rate exists for a currency, the value keeps its original amounts, listed side by side if viewers paid in several currencies, and is marked **No exchange rate — original amount**. Older sessions recorded before currencies were kept show the value marked **Currency unknown**. Streamer Mode masks these values and their original amounts. On desktop, the report uses a wider grid; on phones, cards stack. A Back link returns to the filtered list on either screen size.

During a stream, duration runs continuously. Peak and average viewers,
messages, follower growth, paid Subs or Members, gifted Subs, chatters,
platform comparison, stream-table figures and top lists show running values
**so far**. Sample-based figures update about every 60 seconds without a page
reload. Chat counters can trail incoming messages by another 30 seconds while
Lumio waits for late chat writes. A value that cannot be calculated yet shows
**—** and a hint, not a zero. YouTube subscriber gain appears **after the
stream**; it is calculated from the subscriber-count difference at the end.
Final figures replace the running ones after the session is finalized.

The **Streams** table lists the streams in start order. Select a column header (platform, title, category, start, duration, peak, average viewers, messages, or chatters) to sort by it; selecting it again flips the direction. Text columns start from A to Z, number columns from the highest value. Missing values stay at the end. The sort is not saved and also works on a shared report.

When a session crosses midnight in your time zone, every time in its report carries its day and month (for example **07.10., 01:30**): KPI and chart tooltips, chart axes, moments, ad breaks, the stream table and chat insights. A session within one day shows plain times, because the header already names the date.

Under a stream row, the **Streams** table can show more detail:

- **Categories:** when the category changed during the stream, a timeline such as `19:15 Just Chatting → 20:02 Hollow Knight`. A stream with a single category shows it only in the **Category** column.
- **Tags:** the stream tags as chips (Twitch and Kick; YouTube has none).
- **Shared Chat** (Twitch): in **Whole session**, the stream-table row gives a one-line **Sum of all channels** peak and average. The **Shared Chat · whole session** card gives partner details once: channel, messages, viewers and participation times. The sum's double-counting hint sits below the chart. In **My channel**, your own values stay separate. Unknown names appear as **Unknown channel**; platform channel IDs are never shown.

Long lists wrap, also on a phone. Streams recorded before these values were collected show what is known; partner viewers stay empty for them.

The main viewer chart combines the total with platform lines, peak and median markers, and Twitch ad-break bands. During a Twitch Shared Chat, **Whole session** shows **Sum of all channels** and one line per channel, while **My channel** keeps your own viewer curve and markers. A partner line runs only while that channel was in the session. Follower and sub charts share its time grid. You can zoom into the viewer, follower and sub charts together: drag across a chart to zoom to that stretch, or hold Ctrl (⌘ on a Mac) and scroll, or pinch on a trackpad, to zoom around the pointer; a plain scroll keeps scrolling the page. While zoomed, the y axes follow the visible stretch and each chart shows **Reset zoom** (with the visible range where there is room); a double-click on a chart resets it as well. Hovering a chart, or tapping it on a phone, shows the crosshair line, the points and the tooltip box in that chart only; the other charts and the KPI trend lines stay still. Each chart names its series with legend chips in the line colours. A chip hides or reveals that series in every chart of the report at once, and its chips on the other cards show it struck through too. Follower, sub and message totals only ever rise: when one platform's stream ends a minute before another's, its last count stays in the total. The viewer total counts the platforms that are live at that minute. YouTube reports no individual subscriptions, so its subscriber gain is counted once at stream end: it is part of the follower figure on the card but not of the curve, and a line under the chart names it. While the session is still live, that gain does not exist yet: YouTube has no line in the follower chart or its legend, the total is the sum of the other platforms, and the line under the chart reads **YouTube subscribers come after the stream**. A YouTube-only live session shows no follower chart and no trend line at all; the follower card says once, in its chart area, that the subscribers come after the stream, and the KPI tile reads **after the stream**. A platform comparison appears for multistreams; a **Moments** panel highlights peak, low, median, and strongest follower rise. The report also shows the platform stream table, up to 10 top chatters, up to 20 emotes if the finalized report contains them, and up to 9 GIFs in a 3 × 3 grid. A report with only 10 frozen emote entries stays at 10. Hover over an emote or GIF tile, or tap it on a phone, to open a larger card with the full name or caption, a bigger image, the provider and how often it was used; for newer reports an emote card also shows its ID, whether it is animated and its channel. With reduced animations, a GIF in the card plays only after you press **Play**. Shared reports show the same cards. With `chat:userinfo` and Multichat on your plan, selecting a top chatter opens the same user info card as in Chat and Events; on a shared report and in older reports without platform user ids, the list is static. A chatter whose data was erased on request keeps their place and count but shows as **Deleted user**, without an avatar and without a user card; the same applies to the posters and postings under **Links**, **Commands** and **Keywords**. KPI trend lines mark the peak for viewers and messages and the latest point for follower growth. Hover over a KPI trend line, or tap and drag along it on a phone, to see the time and value of each step: viewers at that time, messages per minute, and followers gained since the start (with ≈ for YouTube subscribers). Only the trend line under the pointer shows its line, point and box; the other trend lines and the charts stay still. This also works on a shared report.

**Chat bots are not counted.** Messages from accounts with the Twitch or Kick bot badge, from known chat bots (such as Nightbot or Fossabot) and from the channel's own bot account are left out of the message count, the messages-per-minute trend, unique chatters, the per-platform figures, the top chatters and the emote and GIF figures, in the report, the list and on a shared report. YouTube has no bot badge, so YouTube bots are recognised only from the known-bot list. Under the **Messages** card, a muted note such as **excl. 42 bot messages** says how many were left out; hover over it for what counts as a bot. The note follows the running chat count while a session is live. It is missing when no bot wrote, when the live chat calculation is unavailable, and for older sessions whose chat log was already gone when bot filtering arrived. Events and viewer counts are never affected. The full definition is in [Stream History](../features/stream-history.md#bot-messages).

### Chat insights: links, commands, keywords, announcements, pins and AutoMod

The card also has **Announcements** and **Pins** tabs. Announcements list the
time, colour and sender; pins list the sender and the person who pinned,
planned and actual duration, changes and the end reason. People show avatar,
name and a bot marker. Times observed from Twitch's pin polling are marked
**≈**. For sessions begun before these lists were captured, the tab says
**Not captured for this stream**. No message text is frozen in the report:
you see it while the chat message or retained pin event has it, then **Text
no longer stored**. Announcements count in the usual message and chatter
figures and keyword insights.

Below the stream table, the **Chat insights** card has three tabs for chat analysis. **Links** lists the links posted in chat; **Commands** lists the chat commands viewers typed, starting with `!` or `#` (`!discord` and `#discord` are separate rows). **Keywords** lists every term tracked under [Channel settings → Keywords](./channel-settings.md#keywords), including terms with zero hits; its tab count is the number of terms that came up. Links and Commands show their entry counts. Every link or command is one row, however often it was posted, with the time it first appeared, how often it was posted, the top three posters with their counts plus **+N more**, and, for commands, how many different people used it, a **Lumio command** chip when it matches one of your enabled bot commands, and the three most common arguments (**no arguments** when nothing followed the command). **By time** sorts rows by first appearance, **Most used** by count; each tab keeps its own choice. On a wide card, the **First** and **Count** column headers sort as well: selecting the active one flips the direction (newest first, or least used first). The card shows 10 rows, and **Show all** expands the rest in place.

Links and Keywords include chat bots, marked with a dashed **BOT** chip. Commands count viewers only; messages from bots are left out. **Times** opens a row: a strip across the session marks every posting (bot postings in grey), and hovering over the strip shows the time and the poster below it and moves the KPI trend lines to that time. Under the strip, the first 15 postings are listed with time, platform and name (for commands also what was typed); **show all** lists the rest. Lumio keeps the first 100 postings of each link, command or keyword, so a busier one says **First 100 of N**.

On the dashboard, selecting a link opens the external-link warning before it opens in a new tab. With `chat:userinfo` and Multichat on your plan, selecting a name opens the user info card. A session without links or commands says so; for older streams whose chat log was already gone, the tab says **Not available for older streams**. The full extraction rules are in [Stream History](../features/stream-history.md#links-and-commands).

#### AutoMod log

For a Twitch session, members with both `history:read` and `chat:automod-read` see a fourth **AutoMod · n** tab. It lists messages Twitch held for review, including messages later allowed, denied or expired. The tab is private to the signed-in dashboard: it is absent from share links, exports and popouts. It is read from the AutoMod log when opened, rather than stored in the finalized report.

Each row shows the hold time (hover for date and seconds), sender avatar, display name and @login (initials when no avatar is available; no badges in this tab), held text with flagged spans, reason, outcome, who decided and whether in Lumio or on twitch.tv, and waiting time. A name opens the user card when you have `chat:userinfo` and Multichat. Links in held text cannot be clicked. Reasons include a blocked link, a blocked term and an AutoMod category with level. Outcomes are **Open**, **Allowed**, **Denied** and **Expired**. An expired hold with no moderator or waiting time means nobody decided before it expired; **Expired · on twitch.tv** means Twitch reported the expiry.

Filter chips show counts for each outcome. Choose **Oldest first** or **Newest first**, or select the **Time** column heading to reverse the order. The footer shows how many messages are displayed out of the matching total; **Load more** fetches up to 100 more at a time. An empty session says AutoMod held no messages. **Not available for older streams** means the session has no Twitch broadcast or its log is outside chat retention. A load error offers **Try again**.

Each entry, its held text, flagged spans and term text included, is deleted once the hold is older than the account's chat retention window (Free 365 days, Pro 1,095 days), for every outcome, including allowed messages. **Text not stored** means the message exceeded the storage size limit. Twitch emotes and Cheers in the held text show as images with the Cheer amount; 7TV, BTTV and FFZ emotes use the connected channels' emote sets. The sender's avatar is the one Lumio knew at hold time. An erasure your channel instructs deletes that participant's rows in your channel; holds after it are logged again. An objection made to Lumio does not change the log. See [Data & Privacy](./privacy-and-export.md).

**Follower and sub labels depend on scope.** Twitch and Kick use Followers and Subs; YouTube uses Subscribers and Members. A mixed session uses **Followers & Subscribers** and **Subs & Members**. In German, paid subscriptions are **Subs** and YouTube followers are **Abonnenten**; YouTube's rounded subscriber counts carry an approximate marker (`≈`). Twitch tier counts stay separate from YouTube memberships. Prime is shown separately and does not count as a new paid sub.

### Estimated revenue and ads

With `history:revenue-read`, the revenue card shows an estimated total and per-hour average. The total, an **in EUR**-style label naming its currency, and the **Change assumptions** link sit above the itemized breakdown; the currency itself is set in the report header. When several platforms have revenue items, tabs show **All** plus the applicable **Twitch**, **YouTube**, and **Kick** views. **All** has one summary row per platform; selecting a row opens that platform's tab. Donations belong to no platform and appear only under **All**. Each platform tab lists its items and a **Total** for that platform when the amounts can be summed in one currency. A single-platform stream shows its itemized rows without tabs. The card keeps the same height while you switch tabs. Streamer Mode masks the grand total, platform totals, item amounts, and unit prices in this card.

The card also shows any amounts that cannot be converted. Twitch tiers, Prime, Bits, Kick subs and KICKs use fixed USD values; their shares, ad CPMs and ad-free viewer shares are editable. YouTube memberships use the level prices you enter; an unknown level uses the cheapest entered level (`assumed_lowest_level`), and without any level price memberships remain unpriced. Membership milestones count as paid months. Without the revenue permission, the card shows Twitch sub tiers as counts only. The assumptions live in [Channel settings → History](./channel-settings.md#history--revenue-assumptions) (`/dashboard/settings/channel/history`); **Change assumptions** opens that tab. With `history:revenue-edit` you set payout currency, shares, ad assumptions and YouTube levels there; with `history:revenue-read` alone the tab is read only. The revenue is an estimate, not a platform payout or tax statement.

Twitch and Kick ad breaks appear in the report with break count, automatic/manual split, total and average time, minutes per hour, estimated impressions, and viewer change after a break. Their ad revenue lines use viewer spots from each break, minus ad-free viewers, × your CPM and share. Until you enter a CPM, the line contributes no money. YouTube has no ad-break feed: its ad line uses sampled viewer-hours and your mid-rolls-per-hour assumption, with no pre-rolls; without a mid-roll rate there is no line.

For YouTube, the card names the source **Lumio estimate** until YouTube Analytics figures arrive, normally **2–3 days after the stream**. With figures it says **Estimated revenue according to YouTube Analytics**, marks them **provisional** or **final**, and shows their fetch date. The Analytics lines for ads, Premium and other transactions replace the YouTube ad, membership, Super Chat and Super Sticker estimates in the total; they are never added to them. The card shows one of three specific hints when needed: reconnect YouTube with the revenue checkbox selected, the channel is outside the YouTube Partner Program, or enable the YouTube Analytics API in your Google app. The last hint links to the [setup guide](/getting-started/oauth-setup#youtube-analytics-api). These hints do not appear as connection-card alerts. Everyone with `history:revenue-read` can see the Analytics amounts; the connection dialog says so before authorization.

Amounts use your **display currency** (or a currency selected in the report) at the ECB reference rate for the stream's UTC date. A weekend or holiday uses the latest available rate within seven days. Tooltips show the original amount, rate, and rate date. If a rate is unavailable, Lumio keeps the original currency, marks that amount unconvertible, and excludes it from converted totals and averages. ECB reference rates are not bank settlement rates.

## Sharing a report

With `history:share`, **Share** opens a dialog. On the left you choose how long the link is valid (1 hour to 30 days; 7 days by default) and which sections a public viewer receives: core report data (viewers, growth and moments) is always present; chat and ads are on by default. Top chatters, **Links**, **Commands** and **Keywords** are grouped under **Shows viewer names publicly** and are off by default: Links shows who posted a link and when, Commands also shows what viewers typed after the command, and Keywords shows who posted a tracked term and when, so switch them on only when you want that public. Revenue is off by default. On the right, under the link preview, you set an optional password, the link currency, and whether downloads are allowed, and you manage the active links. **Close** and **Create & copy link** stay visible at the bottom of the dialog, even on a phone where its content scrolls. Revenue sharing also requires `history:revenue-read`. The preview lists the sections without showing amounts.

**Create & copy link** puts the new URL on your clipboard. Active links show their expiry and contents and can be extended or revoked. Lumio stores only a token prefix: you can copy a full URL again only for a link created while this dialog remains open. A password is needed to open a protected link, and the password is never part of its URL.

Even when you share revenue, the public link and its download show **only the Lumio estimate** for YouTube. They do not include Analytics figures or totals calculated from them.

## Viewing a shared report

A link opens a public, read-only report at `/share/history/{token}` in its own layout. It shows the channel and expiry only after access is granted, only the sections the owner shared (the **Chat insights** card appears only with **Links**, **Commands** or **Keywords** shared, with a tab for each one that is; there, links are plain text that cannot be clicked and names do not open a card), and a download action only when export was allowed. When revenue is shared, the page labels its currency, ECB rate date, and estimated items. A link that has expired or was revoked, and an unknown link, all show the same **This link is no longer available** page: it asks the viewer to request a new link from the person who shared it, links to the Lumio home page, and never asks for a password, even when the link had one. A still-active protected link shows the password page instead; a wrong password shows an **Incorrect password** message on the field. Neither page reveals a **title, date, channel, or expiry**. If a link expires while someone has the report open, their next download switches the page to the "no longer available" page. A connection or server problem shows a separate error with **Try again**. The social preview is the same neutral text for protected, expired, revoked, and unknown links. Every state includes the standard Lumio footer with legal and privacy links. The page asks for cookie consent: avatars, emotes, GIFs and Bits graphics come from other services (Twitch, Kick, YouTube, 7TV, BetterTTV, FrankerFaceZ, GIPHY), so they appear only after the visitor allows **Functional** cookies. Until then the report shows initials, emote names and a **GIF** label instead, and the emote and GIF cards do not open. Your own report in the dashboard always shows them. The header has a theme switcher (light, dark, or system; system by default) and a language switcher (English or German) on every state, including the password page. Both choices are remembered in that browser. Switching the language on an unlocked report keeps it open and shows the report, dates, and numbers in the new language; downloads then use that language too. The public page has no dashboard seasonal decoration.

## Exporting a report

When a share link is created, **Announcements** and **Pins** are separate
sections under the viewer-name disclosure choices and are off by default.
Only selected sections appear on the public report and its export. A report
CSV ZIP includes `announcements.csv` and `pins.csv` for present lists; PDF,
TXT and JSON include the same information when allowed.

With `history:export`, **Export** downloads a finalized report as PDF, CSV, TXT, or JSON. The menu names the currency in use and sends your language and timezone. Live sessions cannot be exported.

The private report and filtered-list export menus warn that the downloaded file may include YouTube Analytics revenue. After download, the file is outside Lumio's control. A public export uses only the Lumio estimate.

The PDF has up to four designed A4 pages: **Overview**, **Timeline**, **Revenue & Ads**, and **Chat & Streams**. Empty sections and their pages are omitted; long tables continue with repeated headings. Pages carry a header, footer, and page number. TXT follows the same sections. CSV is a ZIP of report sheets, including revenue and ad breaks where available; when the report has links, commands or keywords, the **Chat & Streams** page and the TXT carry their tables, and the ZIP adds `links.csv`, `link_posts.csv`, `commands.csv`, `command_posts.csv`, `keywords.csv` and `keyword_posts.csv` for lists present in the report; JSON keeps API field names. The report exports use English or German labels where applicable. Times in the PDF and TXT follow the same rule as the report page: plain times for a session within one day of your timezone, and day plus month (for example **07.10. 01:30**) on every time once the session crosses midnight. A public download includes only the sections that link permits, and revenue requires the owner to share it.

## Twitch Shared Chat in history

The **Shared Chat** filter offers **All**, **With Shared Chat** and **Without
Shared Chat** when your history includes Twitch streams. It filters the list,
summary figures, trend, calendar heatmap and list export together. The choice
appears as a removable chip and remains in the URL. A live stream enters
**With** as soon as its session begins. A Twitch icon and up to three channel
avatars mark a matching list row; the host comes first with a crown, then your
channel and the partners.

For a report with Shared Chat, choose **My channel** (the default) or **Whole
session** near its header. The same switch appears on the Dashboard's **This
stream** card while the session runs. This choice affects only the current
view; list totals and exports keep your own-channel figures. **My channel**
counts messages, chatters and insights from your room, even while partners are
present. **Whole session** adds partner activity by channel. Its chart has the
sum area and one line per channel with a legend; a channel that leaves keeps
its earlier line. The Shared Chat card shows the partner breakdown once. Your
Subs, Bits, gifts, ads and tips remain your own channel's revenue in either
view. Shared report links and stream-summary emails show My channel.

The timeline marks the exact start, joins, leaves and end from Twitch session
events. It stays available after a report is finalized. Older reports without
those events show a minute-sample reconstruction labelled **From minute
samples (± 1 min)**. A stream whose chat log is already gone may still show
**Including partner chat** on an old frozen message total; otherwise Lumio
recomputes the own-channel count from retained chat.

### Zuschauerzahlen im Shared Chat

Lumio currently uses Twitch's Helix `viewer_count` as each channel's own
viewer count during Shared Chat. A live comparison has not verified that
assumption. Twitch [describes a separate individual count](https://blog.twitch.tv/en/2024/12/05/shared-viewership), while its API and EventSub do not expose the unique Shared Viewership metric. **Sum of all channels** adds channel counts and can count
people watching several channels more than once; the report explains this
under the chart.

## Streamer Mode on History

Streamer Mode replaces on-screen money amounts, unit prices, share URLs, token prefixes, and link passwords with placeholders. Shared Chat rows never display platform channel IDs, so there is no ID to mask there. An individual eye control can reveal a field; **Copy** still copies the actual new share URL without showing it on screen. Exported files can still contain authorized amounts, so check a file before showing it to viewers.

Titles, categories, channel and chatter names, counts, and the internal session ID in the page URL or filename remain visible. Stream titles and names are already public; counts are the point of an analytics report. A session ID alone does not grant access to the report. Share tokens and passwords do grant access, which is why they are masked.

## Stream summary email

After a stream ends and its session is finalized, Lumio emails the **account
owner** a summary with average viewers, peak viewers, and live time. Where a
previous completed stream exists, the viewer figures show the change from it.
A sentence lists follower, subscriber/member, and chat-message counts, plus
other non-zero stream activity. A chart shows viewer and chat trends; a platform
table breaks out average and peak viewers. The email links to the full report,
where the detailed charts and top lists remain available. Streams shorter than
**5 minutes** are skipped.

You control this under **Settings → Notifications**, on the **Stream summary**
row in the **Stream** category:

- **Off** - no summary at all.
- **In-App** - a dashboard notification, no email.
- **Email** - the summary email only, no dashboard notification.
- **In-App + Email** - both (the default).

## Permissions at a glance

| Permission | What it unlocks in the webapp |
|-----------|-------------------------------|
| `history:read` | The History nav item, the session list, and reports |
| `history:share` | The Share button and share-link management |
| `history:export` | Exporting a report's data |
| `history:delete` | Deleting a stored session through the API |
| `history:revenue-read` | Estimated amounts in the list, overview, report, and exports; option to share revenue |
| `history:revenue-edit` | Editing revenue assumptions in Channel settings → History |
| `history:keywords-edit` | Adding, changing and removing tracked terms in Channel settings → Keywords |

Owner and Administrator hold all seven by default, including `history:revenue-read` and `history:revenue-edit`. Moderator holds `history:read` and `history:export`.

---

## User Guide / Public Stats

Source: https://docs.lumio.vision/user-guide/public-stats

# Public Stats

Public Stats at `https://stats.lumio.vision` shows public channel and stream
statistics without a Lumio login. You can browse rankings, games, emotes and
partners, search for a channel, or open a channel's page and recent streams.
Some pages include data for channels that do not use Lumio.

## Channel and stream pages

A channel page shows the current profile, aggregate figures, recent streams,
active broadcaster-marked ad panels and trends where data is available. It
links to `/{channel}/history` for earlier profile values, removed panels and
earlier panel artwork. A stream page shows the stream's public figures and can
show a chatter leaderboard only when the broadcaster enabled it. The history
route and stream pages remain accessible by link but are not indexed by search
engines.

The channel URL uses the current handle as its canonical address. An older
handle can still resolve, but search engines are directed to the current one.
YouTube and Kick channel pages remain available and are not indexed; Twitch
channel pages can be indexed. A broadcaster's opt-out removes the channel from
public reads and the sitemap.

## Search visibility

The production home page, ranking pages, Games, Emotes and Partners may appear
in search results. The sitemap lists those pages and eligible Twitch channel
pages with a stream in the last 12 months. It contains no stream pages, profile
or panel change history, search-result pages or personal watchlists. Search
engines can take time to refresh an old result after a page changes or is
removed.

Staging and other non-production Stats hosts are excluded from indexing. The
site's footer states that Lumio Stats is independent of Twitch, YouTube and
Kick, and links to Lumio's legal pages.

## Sharing and privacy

Page links have share images. Channel images show the current channel identity
and aggregate figures, without chatter names, profile text or change history.
An unknown or opted-out channel receives a generic image. Third-party apps may
keep their own copy of a preview after the Lumio page changes.

If you own a connected channel, you can manage its visibility from the
dashboard's [channel settings](./channel-settings.md). A broadcaster without a
Lumio account can opt out using the verified `!optout` command in their own
channel chat. See [Public Stats](../features/public-stats.md) for the data and
API rules behind these pages.

---

## User Guide / Streamer Mode

Source: https://docs.lumio.vision/user-guide/streamer-mode

# Streamer Mode

Streamer Mode hides sensitive data across your Lumio dashboard - platform IDs, email addresses, credential hints, and similar identifiers are replaced with dots (`••••••••`). This keeps private information off-screen while you show your dashboard on a live stream.

## Where to find it

There are three ways to toggle Streamer Mode:

1. **Header icon** - The **Shield** icon next to the notification bell in the top bar. One click toggles it on or off, and the icon is highlighted while it is active. The top bar is hidden on the full-screen pages (Chat, Events, and the overlay editor), so use one of the options below from there.
2. **Settings page** - Go to **Dashboard > Settings**. **Streamer Mode** is the first section, with an **Off** / **On** switch.
3. **Popout settings** - In the chat, events, and music popouts, open the gear icon and scroll to the **Streamer Mode** row in the settings panel.

Your choice is saved to your user account, so it follows you to a new browser or device the next time you sign in. Tabs and popout windows already open in the same browser pick up the change immediately.

Streamer Mode belongs to **you**, not to a channel. It is available no matter which entry is selected in the account switcher, including your personal profile, and the same value applies to every channel you switch to.

## What gets masked

When Streamer Mode is active, the following data is replaced with dots:

| Location | Data hidden |
|----------|-------------|
| **Connections** | Platform channel IDs (Twitch, YouTube, Kick) |
| **Credentials** | Client ID hints in the credentials list; the Client ID and Client Secret input fields in the setup wizard |
| **Bot connections** | Bot username |
| **StreamElements** | Token hints and the token input field |
| **Profile** | Your email address (both the header and the email input field) and platform provider account IDs |
| **Accounts** | Provider account IDs shown in the login-assignment picker |
| **Audit log / Activity** | The IP address (partly, e.g. `203.•••.•••.7`), the location (city and country), the user agent, and the raw event JSON, which starts closed. Each row has its own Eye. **Anonymised** and **—** stay visible because they reveal nothing |
| **Sessions** | The IP address and the location of every session, in the table and in the stacked rows. **Unknown** stays visible |
| **Security overview** | The place in the **Failed sign-ins** tile ("Latest date · place · device") and in the **Sessions** tile ("… longest device, city"). The rest of the sentence stays; the Eye reveals only the place and does not open the tile's area |
| **Sign-in & 2FA** | Your email address in the **Email & password** row in every state (active, link pending, change pending, confirmed), in every step of the set-up dialog, and in its address field. The field stays an email field, so a password manager still saves the address as your user name |
| **Members, tokens, extension teams** | Other people's email addresses: an invite without a display name in the channel's member list, a member without a display name in a token's assignment, and the address under each member of an extension team |
| **User info card** | The platform user ID in the card header (opened from the chat and the event feed) |
| **Stream History** | On-screen revenue and donation amounts, unit prices, share URLs, token prefixes, and share-link passwords |
| **Dashboard home and Events** | Money, Bits and KICKs in activity rows (including tests), the live **Now** card, the Events feed and the Events popout |
| **Billing** | Invoice amounts in the invoice list |
| **Extension payouts** | Revenue balance, total earned and pending payout, the connected Stripe account ID, and the PayPal email, IBAN, BIC and account holder fields |
| **Extension analytics** | The revenue figure |

Public list prices stay visible: plan prices on the subscription page and in the account wizard, extension prices in the store, in the install dialog and in your own extension list, because anyone can see them on the public site. The user info card keeps its own public event detail; money, Bits and KICKs in feed rows and on the dashboard home are masked until you reveal them.

Public information like stream titles, channel and chatter names, counts, and avatars remains visible. A Shared Chat source without a known name appears as **Unknown channel**; the report never displays its platform channel ID in either mode. Stream History session IDs remain visible in page URLs and export filenames because an ID alone does not grant report access. Downloads can contain authorized amounts even while the dashboard masks them, and the CSV/JSON exports of the audit log, the activity, and the sessions contain the full IP addresses and locations: a file does not appear on stream.

The value is not merely blurred: it is swapped out for a placeholder, so the real value is not sitting in the page where a screen reader or a viewer could pull it out.

## Revealing individual fields

Each masked field has an **Eye** icon next to it - for input fields, inside the field on the right. Click the icon to temporarily reveal that specific value (the icon switches to **EyeOff**). Click again to mask it again. Revealing a field does not turn off Streamer Mode - only that one field becomes visible.

Password fields are always masked with the same Eye control, whether or not Streamer Mode is on.

## Permissions

Streamer Mode is a personal user preference - no RBAC permission is required. Every user can toggle it on their own account regardless of their role.

## Tips

- **Toggle it before going live.** The Shield icon in the top bar is the fastest way - one click, no page navigation needed.
- **Popout windows follow automatically.** If you toggle Streamer Mode in the main dashboard, open popout windows (chat, events, music) update immediately.
- **Credential setup is safe.** The setup wizard for app credentials and the StreamElements token field mask their inputs while Streamer Mode is active, so you can enter Client IDs and secrets on stream without exposing them.
- **Revealing is per-field.** You can temporarily reveal one ID without exposing everything else. The Eye toggle only affects the field you click.

---

## User Guide / Cookie Preferences

Source: https://docs.lumio.vision/user-guide/cookie-preferences

# Cookie Preferences

Lumio asks for your consent before setting non-essential cookies. The consent dialog opens by itself on your first visit; afterwards you can reopen it from the round cookie button in the bottom-right corner (tooltip: **Cookie settings**).

## Categories

| Category | Required | Examples |
|---|---|---|
| **Essential** | Always on | Login and refresh tokens, pop-out session, language and other preference mirrors, Cloudflare security, Auth.js login cookies on the ID app |
| **Functional** | Opt-in | Platform integrations (Twitch, YouTube, Kick, Discord), UI preferences, Sentry error tracking |
| **Statistics** | Opt-in | Anonymous product analytics (PostHog, when enabled) |
| **Marketing** | Opt-in | Reserved for future advertising integrations, currently unused |

Only Essential is on by default - functional, statistics and marketing start switched off until you accept them.

## Preference cookies

Lumio uses four necessary preference cookies for display settings:

| Cookie | Category | Purpose |
|---|---|---|
| `locale` | Essential | Mirrors your selected UI language so server-rendered pages load the right message catalog. |
| `lumio-tz` | Essential | Mirrors your resolved timezone so server-rendered pages can format times in the same zone as the dashboard. |
| `lumio-season` | Essential | Mirrors your [Appearance](/user-guide/preferences#seasonal-look) settings (seasonal look, strength, animations, creature switches, closed seasonal banners) so the dashboard paints the right look before it has loaded. |
| `lumio-motion` | Essential | Mirrors your [Animations in Lumio](/user-guide/preferences#animations-in-lumio) setting (System, Reduced, Off) so the dashboard starts without unwanted motion before it has loaded. |

These cookies are preference state, not tracking. They are set from your [Region & Language](/user-guide/preferences) and Appearance settings and from the language switcher. The cookie-clearing dialog lists them under **Preferences** so you can remove them from the browser; your signed-in user preferences remain stored on your user profile and can repopulate the mirrors after the next dashboard render.

A shared web or sign-in link with a valid `?lang=en` or `?lang=de` can also set the `locale` cookie when your browser does not have one yet. It leaves an existing cookie unchanged. See [Language](/user-guide/preferences#language).

## How to change

Open the dialog via the cookie button. The first view offers **Essential only**, **Accept all** and **Customize**.

Pick **Customize** to switch the three optional categories individually, then confirm with **Save preferences**. Each category can be expanded to list the cookies and browser-storage keys it covers, with their purpose and duration.

Your choice is stored in your browser and read again on every page load, so it applies to new tabs and later visits in the same browser.

## Revoking

Reopen the dialog and choose **Essential only** - statistics, functional and marketing cookies stop being set from that point on. Necessary preference cookies such as `locale`, `lumio-tz`, `lumio-season` and `lumio-motion` may still be set because they are required for rendering.

Cookies that were already set are not removed by that choice. To clear them, use the **Cookies** link in the page footer (see below).

## Clearing cookies and dashboard data

The **Cookies** link in the page footer opens the **Manage Cookies** dialog. Select one or more categories and confirm with **Clear**:

| Category | What it clears |
|---|---|
| **Authentication** | `lumio-token`, `lumio-refresh`, `lumio-popout-token`, `lumio-popout-origin`. These cookies are httpOnly, so the dialog cannot count them and shows only an **httpOnly** badge. Clearing them signs you out in this browser and ends pop-out sessions opened in this browser; an OBS browser source is a separate browser and is not affected. |
| **Preferences** | The four preference cookies above, plus the theme and sidebar state stored in this browser. Your profile settings stay on your user profile and repopulate the cookies on the next dashboard visit. |
| **Dashboard data in this browser** | What the dashboard keeps in this browser's local storage: chat filters, keyword tabs, chat platform selections, chat alert settings, the viewer-list toggle, event filters, pop-out display settings, recent emotes and colours, and the emote cache. Chat filters, keyword tabs and alert settings saved only on this device are lost. The dialog shows how many entries are present. |

Some entries are never cleared by the dialog: **streamer mode** stays as it is (clearing it would switch streamer mode off without notice and could reveal private data on stream), your **cookie consent choice** is changed only in the consent dialog, and developer preview settings stay untouched.

The Auth.js login cookies of the ID app (`id.lumio.vision`) belong to that site; this dialog cannot read or clear them and does not list them.

## Where the dialog appears

The consent dialog and its floating button are shown on Lumio's public pages - the marketing site, the legal section and the login flow.

They are deliberately suppressed on the dashboard (`/dashboard`, `/account`, `/hub`) and on OBS browser-source routes (`/overlay/…`, `/popout/…`), where a consent dialog would cover a live capture. Your stored choice still applies on those routes - only the dialog itself is hidden. To change it while you are in the dashboard, open a public page such as `/legal/cookies` and use the cookie button there. The footer **Cookies** link for clearing cookies is available everywhere.

## Public Stats site

The public Lumio Stats site (`stats.lumio.vision`) runs the same consent stack: the banner opens on the first visit, the floating cookie button reopens it, and your choice is remembered in that browser. Your consent choice is stored in your browser's local storage, and - like the rest of Lumio - the site uses the essential `locale` cookie to remember your language. No non-essential script (analytics, error tracking, embedded clips) runs before you accept. Emotes, avatars and panel artwork load from the Stats site itself, so they show without a consent choice; GIPHY GIFs wait for the **Functional** category, as on the share pages of `lumio.vision`. Legal and cookie-policy links from that site point back to the main Lumio site (`lumio.vision/legal/…`).

---

## User Guide / Legal Pages

Source: https://docs.lumio.vision/user-guide/legal-pages

# Legal Pages

Lumio's legal section lives under `/legal` with six pages:

| Slug | Purpose |
|---|---|
| `/legal/imprint` | Provider information (§5 TMG). |
| `/legal/privacy` | Data processing and storage policy. |
| `/legal/terms` | Terms of service. |
| `/legal/cookies` | Which cookies + browser storage we use. |
| `/legal/security` | Security practices and contact. |
| `/legal/faq` | Common legal questions. |

The overview at `/legal` shows the six legal texts and a separate **Contracts and contact** group with the contact, withdrawal, cancellation and abuse report forms. The abuse report appears when the public copyright directory is enabled. Every page is available in English and German, and the forms work without signing in.

## Navigating

The legal pages and forms share one header, navigation and footer. The Lumio logo links back to the overview; the header includes theme and language controls and a route back to Lumio. Signed-in visitors can return to the dashboard.

- **Desktop** - navigation under the header separates the legal texts from the forms. Content pages have an **On this page** table of contents where applicable.
- **Mobile** - a breadcrumb sits under the header, and the menu opens a drawer for the legal texts and forms.

Content pages carry a *last updated* badge under the title. The overview itself has no table of contents.

## Reporting copyright abuse

[/legal/abuse](https://lumio.vision/legal/abuse) lets you report a song for abuse or copyright concerns when Lumio's public copyright directory is enabled. Enter the song and artist, your name and email address, and the reason. A Spotify track ID and an HTTP(S) proof link are optional. Lumio prefills your name and email when you are signed in. Complete the Cloudflare Turnstile check and submit the report. A successful submission enters an operator review queue; it does not immediately block the song. The form accepts at most five reports per IP address per hour.

## Contact form

[/legal/contact](https://lumio.vision/legal/contact) hosts the contact form in the shared legal layout. The site footer also links to it. It needs no account; when you are signed in, Lumio prefills your name and email address. The page lists other ways to reach Lumio.

| Field | Notes |
|---|---|
| Your name | Optional, up to 100 characters. |
| Your e-mail address | Required. Lumio replies to this address. |
| Subject | General question, Privacy and your data, Legal, Billing or Other. |
| Message | Required, up to 5,000 characters. |

A Cloudflare Turnstile check protects the form. Usually nothing is visible except the line *Protected by Cloudflare Turnstile*; when a challenge is needed, a checkbox unfolds above the **Send message** button. Lumio forwards the message by e-mail to its support inbox and does not store it. The form accepts at most five messages per hour from one IP address. Field errors appear by the affected field; send and security errors appear by the form action in the page language.

The [withdrawal and cancellation guide](/user-guide/withdrawal-and-cancellation) explains the other two forms in this layout.

## Editing

Legal pages are authored in MDX, one file per language. Each page carries its own last-updated date inside its content file, so the text and the date shown in the badge change together. See [MDX Content Pipeline](../developer-guide/mdx-content.md) for the technical details.

---

## API Reference / REST API

Source: https://docs.lumio.vision/api-reference/rest-api

# REST API

## Contract declarations

All declaration endpoints have GraphQL twins at `POST /v1/gql`. JSON fields are `snake_case`. Public requests are rate limited (10 per IP per hour, 200 per hour globally) and require a Turnstile token with action `withdraw` or `cancel`. Repeating a `client_request_id` for the same declaration returns the first receipt. Reusing a `client_request_id` for a different declaration (another user, channel, kind, contract or purchase, or another e-mail address on the public forms) returns `409 IDEMPOTENCY_KEY_REUSED` and no receipt.

| Method and path | Request or filter | Guard and result |
|---|---|---|
| `POST /v1/withdrawals` | `name`, `email`, `contract_reference`; optional `message`, `locale`, `turnstile_token`, `client_request_id` | Public withdrawal; receipt with `status: open`. |
| `POST /v1/cancellations` | `name`, `email`, `contract_reference`; optional `kind`, `reason`, `effective`, `effective_date`, `locale`, `turnstile_token`, `client_request_id` | Public cancellation; receipt with `status: open`. |
| `POST /v1/billing/withdrawal` | `contract` (`plan`, `extension_purchase`, `other`); optional `extension_purchase_id`, `contract_reference`, `message`, `name`, `receipt_email`, `client_request_id`, `account_id` | Interactive session. `plan` needs `plan:edit`; `extension_purchase` needs `extension-store:uninstall` in the target channel; `other` needs only the session. |
| `GET /v1/billing/withdrawable-contracts` | — | Interactive session; eligible plan and paid extension contracts across manageable channels. |
| `GET /v1/billing/cancellable-contracts` | — | Interactive session; plan and extension subscriptions across manageable channels, including cancellation state. |
| `POST /v1/billing/cancel` | Optional `kind`, `reason`, `effective`, `effective_date`, `receipt_email`, `name`, `client_request_id`, `account_id` | `plan:edit` in the target channel and interactive session; stores a plan cancellation declaration. |
| `POST /v1/extension-purchases/{id}/cancel` | Optional `kind`, `reason`, `effective`, `effective_date`, `name`, `receipt_email`, `client_request_id`, `account_id` | `extension-store:uninstall` in the target channel and interactive session; that channel must own the active subscription purchase. |
| `GET /v1/admin/contract-declarations` | `status` (`open` default, `processed`, `rejected`, `all`), `kind` (`withdrawal`, `cancellation`), `first` (1–100, default 50), `after` | Admin `contract-declarations:read`; oldest first, `items` and `next_cursor`. |
| `GET /v1/admin/contract-declarations/{id}` | — | Admin `contract-declarations:read`; one case. |
| `POST /v1/admin/contract-declarations/{id}/close` | `status` (`processed` or `rejected`); optional `note`, `refund_reference`, `stripe_applied` | Admin `contract-declarations:edit` and interactive session; no automatic refund. |
| `POST /v1/admin/contract-declarations/{id}/match` | `account_id`, `contract` (`plan` or `extension_purchase`), optional `extension_purchase_id` | Admin `contract-declarations:edit` and interactive session; match an open public case. |
| `POST /v1/admin/contract-declarations/{id}/retention` | `retain_until` (`YYYY-MM-DD`, later than the current date) | Admin `contract-declarations:edit` and interactive session. |

`kind` is `ordinary` by default or `extraordinary`, which requires `reason`. `effective` is `period_end` for ordinary cancellation or `immediate` by default for extraordinary cancellation; `date` needs `effective_date` (`YYYY-MM-DD`, today or later). Each `ContractOption` in the two list responses includes `account_id` and `account_name` as well as the plan or extension details; the active channel comes first, then other manageable channels by switcher name. Omit `account_id` on a signed-in write to use the active channel, or pass a listed option's `account_id` to check permission in that channel without switching the active channel. `account_id` is ignored for a withdrawal with `contract: other`. A declaration receipt carries `id`, eight-character `reference`, `kind`, `status`, `received_at`, `receipt_email`, and nullable `period_end`. Plan cancellation also returns `declaration_id` and the same case reference and status. An ordinary signed-in cancellation can be `processed` once Stripe accepts it; an outstanding Stripe operation still returns success with `open` and is retried. Extraordinary and public cancellations remain `open` for operator review.

A missing permission in the target channel returns 403; a foreign extension purchase returns `404 PURCHASE_NOT_FOUND`; an already cancelled subscription returns `409 SUBSCRIPTION_ALREADY_CANCELLED`. Public validation and Turnstile failures return 400, rate limits 429, and a storage outage 503 `TRY_AGAIN`. Admin actions return `409 DECLARATION_CLOSED` for an already closed case. See [Withdrawal & Cancellation](/features/contract-declarations).

## Abuse reports

`POST /v1/abuse-reports` is public and accepts `song_name`, `artist`, `reporter_name`, `reporter_email` and `reason`. Optional fields are `spotify_track_id`, `proof_url` (HTTP or HTTPS) and `turnstile_token`. A Turnstile token for action `abuse` is required when verification is enabled. The response is `201` with `data: { "id": "..." }`; the report enters the admin queue without immediately blocking the song. The limit is five reports per IP address per hour and 100 reports per hour globally.

Validation and Turnstile errors return 400 with `MISSING_SONG_NAME`, `MISSING_ARTIST`, `MISSING_REPORTER_NAME`, `INVALID_EMAIL`, `MISSING_REASON`, `INVALID_PROOF_URL`, `INVALID_SPOTIFY_TRACK_ID`, `TURNSTILE_REQUIRED` or `TURNSTILE_FAILED`. Rate limiting returns `429 RATE_LIMITED`; an unavailable verification or storage dependency returns `503 TRY_AGAIN`. The [GraphQL mutation](/api-reference/graphql#abuse-reports) uses the same fields, checks and codes in `camelCase`.

## Developer balance release (admin)

GraphQL twins: `adminReleaseFundsAndDeleteUser` / `adminReleaseFundsAndDeleteDeveloper` ([GraphQL](./graphql.md#developer-balance-release-admin)), with the same guard, validation, errors and audit events.

| Method and path | Request body | Guard and result |
|---|---|---|
| `POST /v1/admin/users/{id}/release-funds-delete` | `request_reference` (1–64 characters), `reason` (1–500 characters) | Admin `developer-funds:release-deletion` **and** `users:delete`, interactive session; releases the user's developer balance as a liability, then deletes the user like `DELETE /v1/admin/users/{id}`. |
| `POST /v1/admin/developers/{id}/release-funds-delete` | as above | Admin `developer-funds:release-deletion` **and** `developer-verification:edit`, interactive session; releases the balance, then deletes the profile like `DELETE /v1/admin/developers/{id}`. |

The response `data` is `{ deleted, released_balance_id, amount, currency, release_case, mail_sent, claim_code }`. A release is only possible when the balance cannot be paid out (`release_case` `not_verified` or `no_payout_method`); a payable balance returns `409 DEVELOPER_FUNDS_PAYABLE`, an in-flight payout `409 DEVELOPER_FUNDS_OUTSTANDING`. `claim_code` is set only when the release mail could not be sent. Invalid input returns `400 INVALID_REQUEST_REFERENCE` or `400 INVALID_RELEASE_REASON`.

### Settling a released balance

GraphQL twins: `adminStartReleasedBalanceClaim` / `adminSettleReleasedBalance` ([GraphQL](./graphql.md#settling-a-released-balance)), with the same guard, validation, errors and audit events. The claim code goes only in the request body.

| Method and path | Request body | Guard and result |
|---|---|---|
| `POST /v1/admin/released-balances/claim` | `claim_code` | Admin `developer-funds:settle`, interactive session; records that the person presented the code (`claim_started_at`, set once). `data`: `{ released_balance_id, amount, currency, release_case, released_at, claim_started_at, newly_started }`. |
| `POST /v1/admin/released-balances/settle` | `claim_code`, `developer_id` | Admin `developer-funds:settle`, interactive session; credits the amount to the verified profile `developer_id` and marks the record settled. `data`: `{ released_balance_id, amount, currency, developer_id, settled_at, new_balance }`. |

Errors: `400 INVALID_CLAIM_CODE`, `403 DEVELOPER_VERIFICATION_REQUIRED` (the profile's identity is not verified), `404 RELEASED_BALANCE_NOT_FOUND` or developer profile not found, `409 RELEASED_BALANCE_SETTLED`.

## Profile security and data routes

All paths below use the `/v1/` prefix. JSON fields use `snake_case`. Public sign-in routes have rate limits; profile routes require the caller's interactive session unless a narrower guard is stated. A fresh **step-up** is a successful identity confirmation recorded on that session within the last ten minutes. Where 2FA is enabled, step-up accepts a passkey, authenticator app code or recovery code.

| Method and path | Purpose |
|---|---|
| `GET /v1/auth/turnstile-config` | Public runtime Turnstile site key and widget requirement. |
| `POST /v1/auth/register` | Email/password registration; gives the same check-your-inbox response for existing addresses. |
| `POST /v1/auth/register/resend` | Resend a registration confirmation. |
| `POST /v1/auth/email/verify` | Confirm a link after a user clicks **Confirm**; never signs the user in. Public: works signed out, on another device and for every registration. A bearer is optional and only tells "same profile" (`same_profile: true`) from another signed-in profile (403 `LINK_OTHER_PROFILE`); an expired or revoked bearer counts as signed out. |
| `POST /v1/auth/password/login` | Email/password sign-in; may return `mfa_required`, `mfa_token` and `mfa_methods` instead of tokens. |
| `POST /v1/auth/authorize` | PKCE authorization; when a second step is needed, returns `mfa_required`, `mfa_token` and `mfa_methods` (`passkey` and/or `totp`) instead of a code. |
| `POST /v1/auth/password/reset` | Request a reset link without disclosing account existence. |
| `POST /v1/auth/password/reset/complete` | Set the password, end prior sessions, then continue sign-in and 2FA if enabled. |
| `POST /v1/auth/mfa/verify` | Complete the pending 2FA challenge with an app/recovery code or passkey assertion before tokens or a PKCE code are issued. |
| `POST /v1/auth/passkey/options` | Get a public, IP-limited passkey sign-in challenge. |
| `POST /v1/auth/passkey/verify` | Sign in with a passkey; the passkey also completes 2FA. |
| `POST /v1/auth/mfa/passkey/options` | Get a challenge for the profile named by a pending `mfa_token`. |
| `POST /v1/auth/step-up/passkey/options` | Get a challenge to confirm a session or a 2FA change. |
| `POST /v1/auth/step-up/passkey` | Confirm the interactive session with a passkey. |
| `POST /v1/auth/step-up/oauth` | Confirm with an already linked platform account; requires an interactive session. |
| `POST /v1/auth/step-up/password` | Confirm with the email password when 2FA is off. |
| `POST /v1/auth/step-up/mfa` | Confirm with an app code, recovery code or passkey assertion. |

Registration, password reset, resend, dashboard email setup and the [contact form](#contact-form) use a server-verified Turnstile token. Password login requires it after repeated failures or suspicion. The API checks the token action and the exact ID-app or web-app hostname. Login can proceed through its temporary lockout path if Turnstile cannot answer; other protected actions fail closed.

| Method and path | Purpose |
|---|---|
| `GET /v1/users/me/email-login` | Current email sign-in and pending-link state. |
| `POST /v1/users/me/email-login` | Request or resend the setup link; fresh step-up and Turnstile. |
| `POST /v1/users/me/email-login/change` | Request confirmation of a replacement address. |
| `POST /v1/users/me/email-login/password` | Set the password after address confirmation. |
| `DELETE /v1/users/me/email-login/pending` | Cancel a pending setup or address change. |
| `DELETE /v1/users/me/email-login` | Remove email sign-in; fresh step-up and at least one other sign-in method required. |
| `POST /v1/users/me/password` | Change the password using the current password. |
| `DELETE /v1/users/me/email` | Remove a profile email that came from a platform sign-in. The email sign-in address answers `409 EMAIL_FROM_SIGN_IN`; change or remove the email sign-in instead. |
| `GET /v1/users/me/mfa` | 2FA status, recovery-code count, trusted devices and `factors` (apps and passkeys). |
| `POST /v1/users/me/mfa/setup` | Begin setup; requires fresh step-up. |
| `POST /v1/users/me/mfa/setup/confirm` | Check an authenticator code and return ten recovery codes. |
| `POST /v1/users/me/mfa/enable` | Finish setup; requires fresh step-up. |
| `POST /v1/users/me/mfa/disable` | Turn off all methods with a valid second factor. |
| `POST /v1/users/me/mfa/recovery-codes` | Replace all unused recovery codes after a second-factor check. |
| `PATCH /v1/users/me/mfa/factors/{id}` | Rename an app or passkey (`label`, 1–40 characters). |
| `DELETE /v1/users/me/mfa/factors/{id}` | Remove an app or passkey with another second factor; passkeys return `credential_id` for the WebAuthn Signal API. |
| `POST /v1/users/me/passkeys/options` | Begin registration; first-method response includes ten recovery codes. |
| `POST /v1/users/me/passkeys` | Finish registration; the first method requires `recovery_codes_stored: true`. |
| `DELETE /v1/users/me/mfa/trusted-devices/{id}` | Revoke one trusted device. |
| `DELETE /v1/users/me/mfa/trusted-devices` | Revoke every trusted device. |
| `GET /v1/users/me/step-up` | Available confirmation methods (`mfa_methods`) and freshness. Each entry of `connections` carries `connected_at` (RFC 3339) and `last_used_at` (RFC 3339, last platform sign-in or step-up through that connection; `null` when unknown). |
| `GET /v1/users/me/support-code` | Current hourly support code; interactive session only. |
| `GET /v1/users/me/flagged-connections` | Sign-in, channel and bot connections that need reconnecting. |

`POST /v1/auth/link` requires fresh step-up when adding a platform sign-in, except a reconnect to the same provider account. `DELETE /v1/login-connections/{id}` requires it before removing a connection. Both reject operations that would leave the user with no sign-in method. A 403 `STEP_UP_REQUIRED` tells the dashboard to reopen its confirmation dialog.

| Method and path | Purpose |
|---|---|
| `GET /v1/users/me/data-exports` | List the caller's export requests. |
| `POST /v1/users/me/data-exports` | Request `user` or `user_channels` data; one active export per model and one request per model per 24 hours. |
| `POST /v1/users/me/data-exports/{id}/cancel` | Cancel an own export while it is `pending` or `running`; no step-up. The row becomes `cancelled` and does not count towards the 24-hour limit as long as it had not started yet; once the job had started it (`running`), it counts, so a new request answers `429 EXPORT_COOLDOWN`. Another user's export returns `404 NOT_FOUND`, a finished one `409 EXPORT_NOT_CANCELLABLE`. GraphQL: `cancelDataExport`. |
| `POST /v1/users/me/data-exports/{id}/download-link` | Issue a five-minute signed link after fresh step-up. |
| `GET /v1/data-exports/{id}/download` | Stream the ZIP using that signed link; intentionally REST-only. |

An export row carries `status` (`pending`, `running`, `ready`, `failed`, `expired`, `cancelled`) and `progress_percent` (0–100 while the archive is built, only ever rising; `null` while `pending`).

`GET /v1/users/me` lists each membership in `accounts[]` with `platforms`: the distinct platforms of that channel's connections (channel connections, not sign-ins) in the order `twitch`, `youtube`, `kick`, then the rest alphabetically. A connection waiting for a reconnect counts, a removed one does not; no connection gives `[]`. Same values and order as GraphQL `AccountMembership.platforms`.

| Method and path | Purpose |
|---|---|
| `POST /v1/users/me/deletion` | Schedule deletion after the chosen grace period, or delete at once; fresh step-up. See below. |
| `DELETE /v1/users/me/deletion` | Cancel scheduled deletion, possible until the date. Response `{ "scheduled_for": null, "deleted": false }`. `409 DELETION_IN_PROGRESS` ("The deletion is already running") once the date has passed, `409 NO_DELETION_SCHEDULED` when nothing is scheduled. |
| `GET /v1/me/audit-log/export` | Export personal activity as CSV or JSON. |
| `GET /v1/account/audit-log/export` | Export account activity; requires account `audit-log:read`. |

Audit exports accept the current filter or up to 1,000 selected `ids`. Their file responses are REST-only.

`POST /v1/users/me/deletion` takes an optional JSON body `{ "grace_days": 0 | 7 | 30 }`. No body or no `grace_days` means 30. Any other value returns `400 INVALID_GRACE` ("grace_days must be 0, 7 or 30"); a malformed body returns `400`. The response is `{ "scheduled_for": string | null, "deleted": bool, "closing_payout_cents": number | null }`. `grace_days: 0` deletes the profile at once through the same path as the daily job (export files, uploaded avatar, the user row and with it every session, `system:user_deleted` with `self_service: true`) and answers `{ "scheduled_for": null, "deleted": true }`. Every value needs a fresh step-up (`403 STEP_UP_REQUIRED`). The grace period is stored per profile (`users.deletion_grace_days`); the reminder mail goes out 7 days before the end of a 30-day period and 1 day before the end of a 7-day period. GraphQL: `scheduleProfileDeletion(graceDays: Int)`, identical codes.

Owning channels blocks scheduling with `409 OWNS_CHANNELS`, unless **every** owned channel is already scheduled for dissolution on or before the profile deletion date (`dissolution_scheduled_for <= scheduled_for`). `grace_days: 0` still requires owning no channel at all. A developer revenue balance above 0 is paid out with a grace period of 7 or 30 days: the request creates the closing payout for the whole balance, even below the minimum payout amount, and returns its amount in `closing_payout_cents` (`null` when nothing was owed). Scheduling fails with `409 DEVELOPER_FUNDS_OUTSTANDING` ("The developer profile still has a revenue balance or a payout in progress. It can be deleted once Lumio has paid it out") while a payout is `pending` or `processing`, with `grace_days: 0` while any money is owed, and when the balance cannot be paid out (no payout method, no verified developer identity); nothing is paid out or scheduled then. The closing payout carries its self-billed credit note like every payout, so incomplete tax details answer `422 TAX_DETAILS_REQUIRED` and an incomplete `[billing.issuer]` `503 CREDIT_NOTE_ISSUER_NOT_CONFIGURED` (same texts as `POST /v1/developer/payouts/request`), again without a payout or a schedule. `DELETE /v1/admin/users/{id}` and `DELETE /v1/admin/developers/{id}` answer the same code while money is owed. A due deletion is held by the job until the profile is paid out and retried every run. Revenue that arrives while the deletion is scheduled is paid out with `POST /v1/developer/payouts/request` `{ "closing": true }`. The daily job dissolves due channels first and deletes due profiles in the same run.

`GET /v1/users/me` `accounts[]` (`AccountMembershipResponse`) and `GET /v1/accounts/{id}` (`AccountResponse`) carry `dissolution_scheduled_for`: an ISO-8601 timestamp while the channel is scheduled for dissolution, otherwise `null`. Same value as GraphQL `dissolutionScheduledFor`. The dashboard reads it from the membership list for the dissolution banner and the account-switcher label.

Both also carry `identity`, the channel's resolved name and picture (`source_kind`, `source_connection_id`, `source_platform`, `name`, `avatar_url`); see [Channel name and picture](#channel-name-and-picture). The membership's `account_name` is the same name. `owner_avatar_url` on the membership is deprecated and equals `identity.avatar_url`.

| Method and path | Purpose and guard |
|---|---|
| `POST /v1/admin/users/{id}/mfa/reset` | Reset a user's 2FA with a mandatory reason; admin `users:edit`. |
| `POST /v1/admin/users/{id}/support-code/reveal` | Reveal the current support code; admin `support:verify`, audited. |
| `POST /v1/admin/users/{id}/support-code/check` | Check a code; admin `support:verify`, limited to five attempts per profile per ten minutes and audited. |
| `GET /v1/admin/users/{id}/support-code/checks` | Recent checks; admin `support:verify`. |

Lumio exposes a RESTful API. Most resource endpoints wrap their payload in a HATEOAS envelope.

## Base URLs

| Environment | URL |
|-------------|-----|
| Production         | `https://api.lumio.vision/v1` |
| Production Preview | `https://lumio.api.prod.zaflun.dev/v1` |
| Staging            | `https://lumio.api.staging.zaflun.dev/v1` |

## Response Format

A single resource is returned in an envelope whose `_links.self` is a **string** URL, not a link object:

```json
{
  "data": { "id": "…", "name": "…" },
  "_links": { "self": "https://api.lumio.vision/v1/overlays/123" }
}
```

A paginated collection adds `_meta` and the navigation links, omitting `prev`/`next` at the ends of the range:

```json
{
  "data": [ … ],
  "_links": {
    "self":  "/v1/events?page=2&limit=25",
    "first": "/v1/events?page=1&limit=25",
    "prev":  "/v1/events?page=1&limit=25",
    "next":  "/v1/events?page=3&limit=25",
    "last":  "/v1/events?page=4&limit=25"
  },
  "_meta": { "total": 100, "page": 2, "limit": 25, "pages": 4 }
}
```

`GET /v1/events` and `GET /v1/chat/history` count at most 10 000 matching rows. When more match, `_meta.total` is `10000` and `_meta` adds `"total_capped": true` (show it as "10 000+"); `pages` covers the capped total, and a page past it returns an empty `data` array. Without `from`, both read only the 30 days before `to` (or now). Pass an explicit `from` to reach older history.

Not every endpoint uses the envelope - action endpoints (playback control, toggles, deletes) commonly return a bare body such as `{"success": true}`, and webhook receivers return platform-mandated shapes. Request and response bodies use **snake_case**.

## Error Format

Errors return a flat body with a stable machine-readable `error` code:

```json
{ "error": "VALIDATION_ERROR", "message": "expires_at cannot be in the past" }
```

An optional `details` object is present only when the handler supplies one. When an error says how long to wait (`details.retry_after_secs`, e.g. `RATE_LIMITED`, `AVATAR_BUSY`), the response also carries the same value as a `Retry-After` header.

A missing permission returns `{ "error": "FORBIDDEN", "message": "Missing permission: chat:ban" }` — the same message, character for character, that GraphQL returns with `extensions.code: "FORBIDDEN"`.

| `error` | HTTP | Meaning |
|---------|------|---------|
| `BAD_REQUEST` | 400 | Malformed request |
| `VALIDATION_ERROR` | 400 | Request body failed validation |
| `UNAUTHORIZED` | 401 | No or invalid credential |
| `FORBIDDEN` | 403 | Authenticated but missing the required `resource:action` |
| `PLAN_LIMIT_REACHED` | 403 | The account's plan quota for this resource is exhausted |
| `FEATURE_DISABLED` | 403 | The feature flag gating this endpoint is off for the account |
| `NOT_FOUND` | 404 | Resource does not exist or is not visible to the caller |
| `CONFLICT` | 409 | Conflicts with current state (duplicate slug, live session, …) |
| `BILLING_DISABLED` | 409 | Billing (Stripe) is not set up on this deployment (`stripe.enabled = false`); message `Billing is not enabled` |
| `WRONG_PLATFORM_ACCOUNT` | 409 | A channel reconnect came back with a different platform account than the connected one; nothing was changed. `details.signed_in_as` names that account (login, else display name — never a token or ID) when the platform reported it. See [Connections](../features/connections.md#reconnecting-with-a-different-account) |
| `ADMIN_MFA_REQUIRED` | 403 | The caller holds admin grants but has no 2FA factor (authenticator app or passkey), so every admin endpoint refuses them. Message: `Admin access requires two-factor authentication. Turn on an authenticator app or a passkey in Settings › Security`. See [Admin panel → Two-factor authentication](../admin/admin-roles.md#two-factor-authentication-required) |
| `CHANNEL_DISSOLVING` | 403 | The channel is scheduled for dissolution and suspended until then; `details.dissolution_scheduled_for` names the date. See [Channels being dissolved](#channels-being-dissolved) |
| `AVATAR_BUSY` | 503 | Picture upload only: all decode slots for profile and channel pictures are taken; retry after `Retry-After` seconds. See [`POST /users/me/avatar`](#post-usersmeavatar) |
| `RATE_LIMIT_EXCEEDED` | 429 | Per-auth-context rate limit exceeded (see [Authentication](./authentication.md#rate-limits)), or Spotify throttled an upstream request (see [Spotify](../features/spotify.md#error-handling)) |
| `DATABASE_ERROR`, `REDIS_ERROR`, `INTERNAL_SERVER_ERROR` | 500 | Server-side failure |

4xx `message` values are user-facing and returned verbatim. 5xx messages are scrubbed to a generic string (`An internal server error occurred`, `An internal database error occurred`, `An internal cache error occurred`) so no internal detail leaks; the full message is logged server-side only. GraphQL returns the identical `error` code and `message` for the same failure.

When Spotify throttles a read or playback, queue, device, or playlist action under `/v1/spotify/*`, the response is HTTP `429` with `error: "RATE_LIMIT_EXCEEDED"`, `message: "Spotify rate limit reached. Try again shortly."`, `details.retry_after_secs`, and a `Retry-After` header containing the same number of seconds (at least 1). The wait is supplied by Spotify. It is separate from Lumio's per-auth-context API rate limit. The [GraphQL Spotify operations](./graphql.md#errors) carry the same code and message with `extensions.retryAfterSecs`.

## Interactive Documentation

- **Swagger UI** - `/v1/swagger-ui/` when `docs.swagger_ui` is enabled in config
- **OpenAPI spec** - `/v1/api-doc/openapi.json` (served with Swagger UI) or `/v1/openapi.json` when `docs.openapi_json` is enabled

Both are config-gated so a deployment can lock them down. The generated spec covers the endpoints that carry `utoipa` annotations.

| `[docs]` key | `default.toml` (dev, staging) | `production.toml` | ENV override |
|---|---|---|---|
| `swagger_ui` | `true` | **`false`** | `LUMIO__DOCS__SWAGGER_UI` |
| `openapi_json` | `true` | `true` (inherited) | `LUMIO__DOCS__OPENAPI_JSON` |

Production (`api.lumio.vision`) does not serve the interactive Swagger UI: it is an unauthenticated HTML/JS page on the API origin, so it stays off there. The raw spec at `/v1/openapi.json` stays available for SDK generators. Enabling `swagger_ui` implies `openapi_json` at runtime. The Swagger UI assets are compiled in from the checksum-pinned `utoipa-swagger-ui-vendored` crate (`vendored` feature) — the build never downloads them, so `SWAGGER_UI_DOWNLOAD_URL` has no effect.

### Spec completeness policy

The spec is hand-enumerated in `apps/api/src/openapi.rs`, so historically live routes could silently drift out of it. A build-time test (`openapi::completeness`) now enforces that **every route module wired into the live router is either registered in the spec or on a documented exclusion allowlist** (`SPEC_EXCLUDED_MODULES`, with a per-module reason) - so the spec is a trustworthy completeness oracle for everything **not** on that list. The intentional exclusions are:

- **`internal_extension_handlers`** - internal service-to-service endpoint (the V8 bot-module/automation workers fetch handler code), not a consumer-facing API operation.
- **`webhooks_payments`** - inbound Stripe Connect / PayPal payout webhooks; a provider-called receiver, not a callable consumer operation.
- **`/.well-known/security.txt`** - a static RFC 9116 resource, not a JSON API operation.

The `sounds`, `widgets`, and `history` modules were previously excluded as an annotation gap; their handlers are now annotated and present in the spec. The entire extension / developer-portal / marketplace / payout surface has since graduated into the spec (ZAF-1107): `developer_teams`, `developer_applications`, `developer_store_profiles`, `developer_verifications`, `admin_developer_applications`, `admin_developer_teams`, `developer_extensions` (Developer Extensions - manage your extensions, versions, secrets, testers, analytics, payouts, and limit requests), `extension_actions`, `extension_purchases`, `extension_bundles`, `extension_storage`, `extension_uploads`, `extension_access` (Extension Access - overlay access grants and shared access links), `extension_reviews` (Extension Reviews - admin extension review queue and moderation), `extension_store` (Extension Store - browse, install, review, and serve store assets), `extension_functions` (Extension Functions - invoke extension query/mutate/execute functions), `bot_module_extensions` (Bot Module Extensions - bot-module extension configuration and control), `automation_nodes`, `stripe_connect`, and `marketplace` (Marketplace - public extension store browsing, listings, reviews, featured, categories). Only the two internal modules above (`internal_extension_handlers`, `webhooks_payments`) remain deliberately excluded, because they are not public consumer operations.

Treat this page and the feature docs as authoritative for the excluded surfaces above.

## Endpoints Overview

All paths are under `/v1`. Request and response bodies use **snake_case**. Permissions use the `resource:action` format.

| Resource group | Path prefix | Description |
|----------------|-------------|-------------|
| Auth | `/v1/auth` | Token exchange, refresh, logout, OAuth link/authorize, popout-token exchange |
| Users | `/v1/users/me` | Current-user profile, login connections, sessions |
| Contact | `/v1/contact` | Public contact form: forwards a message to the Lumio inbox by e-mail, nothing stored (see [Contact form](#contact-form)) |
| Accounts | `/v1/accounts` | Create/dissolve/leave accounts, channel name and picture, member invites, login assignments |
| Login Connections | `/v1/login-connections/{id}` | Delete a login connection by UUID; `PUT /v1/login-connections/{id}/reconnect-flag` clears its reconnect prompt |
| Members & Invites | `/v1/accounts/{id}/members`, `/v1/invites` | Team management |
| Roles | `/v1/roles` | RBAC role CRUD and permission catalog |
| Tokens | `/v1/tokens`, `/v1/api-keys` | Popout token and user API key management. `POST /v1/tokens` **requires a first-party session** (logged-in user or the user's own API key; ZAF-1017/ZAF-469) - a popout/overlay/widget/extension token is rejected with `403 FORBIDDEN`, and an omitted `user_id` binds to the **creator**. `PATCH /v1/tokens/{id}` with `"user_id": null` (unassign) binds the token to the **editor**, under the same first-party gate - a popout token is always bound to an explicit user and an unbound token never resolves (ZAF-1922). An explicit `user_id` (on create, or reassigned via `PATCH`) must be an account member whose role does not exceed the caller's own permissions; the owner counts as holding every account permission (ZAF-1740 A1). It accepts an optional `expires_at` (RFC3339) to set the token lifetime at creation - `null`/absent = never expires; a past value is rejected with `VALIDATION_ERROR` "expires_at cannot be in the past", identical to GraphQL `createPopoutToken` (the `PATCH` update path still allows a back-dated `expires_at` as a soft-revoke). The `/v1/api-keys` routes are also first-party gated (see [API Keys](#api-keys)). `/tokens/me` returns the caller's **effective** permissions - a scoped API key or popout token reports its own scope capped to its bound member's current role (ZAF-2430) and a logged-in user reports their account-role permissions; identical to GraphQL `myPermissions`, and never the `["*"]` wildcard. |
| Overlays | `/v1/overlays` | Overlay configuration CRUD |
| Sounds | `/v1/sounds` | Sound library management, upload, playback control, and streaming |
| Widgets | `/v1/widgets` | Widget instance CRUD, access management, and duplication |
| Setting Presets | `/v1/setting-presets` | Named snapshots of chat/events/music display settings, keyed `(user, account)`. Create/edit/delete are scoped to the user + active account (no RBAC, fail-closed on membership); sharing with your account is gated `presets:share`. Reads work with a popout token (own presets only); writes require a first-party session. Gated by `feature:setting_presets` |
| Uploads | `/v1/uploads` | File uploads (multipart) and presigned download URLs |
| Chat | `/v1/chat/*` | History (filter by platform, user, date, keyword `search`, YouTube `live_chat_id`), merged messages+events timeline (`/v1/chat/history/merged`), send, moderate, user profiles, user name-completion search, notes, raid/poll/prediction |
| Events | `/v1/events` | Event history, single event, emit/test |
| Emotes | `/v1/emotes` | Channel and user emote fetching |
| YouTube Memberships | `/v1/youtube/memberships/tiers`, `/v1/admin/privacy/youtube/member/{id}` | Read observed YouTube member-tier badges (account-scoped); GDPR-Art-17 erasure of a member on one channel's instruction (`account_id`, `instruction_reference` and `initiated_by` = `channel` | `subject` query parameters, all required): Lumio's member cache across every account and the member's chat data in that account only (system_admin only) - see [Member Badges](../features/memberships.md) |
| Storage Erasure | `/v1/admin/storage/orphaned-extension-uploads/sweep` | `POST` with `{"apply": false}` (default, dry run: counts extension upload files no `extension_uploads` row references) or `{"apply": true}` (queues them for deletion, audit `system:orphaned_storage_swept`); returns `applied`, `extensions_scanned`, `extensions_failed`, `orphaned_objects`, `queued_objects` (`admin:privacy-erase`). Mirrors GraphQL `adminSweepOrphanedExtensionUploads` |
| Chat Privacy | `/v1/admin/privacy/chat/erase` | `POST` `{account_id, instruction_reference, reason, initiated_by, lumio_user_id}` or `{account_id, instruction_reference, reason, initiated_by, platform, user_id}`: GDPR-Art-17 erasure of a data subject in the one instructing account - chat messages, `platform_users` row, moderator notes, AutoMod log, moderation-log rows targeting them, bot-list entry, stream-history entries (announcements and pins included) and still-open AutoMod held-queue messages (events stay); records them in the account's `account_chatter_suppressions` with `initiated_by` (required: `channel` when the channel initiated the erasure, `subject` when the person asked for it); a `subject` entry is never downgraded by a later `channel` erasure, and its errors are `initiated_by is required` / `initiated_by must be one of: channel, subject`. Other accounts are not touched. Afterwards the channel owner gets a confirmation e-mail (counts and a case number from `case_id`, never the person). `reason` (why the subject is erased, trimmed, at most 500 characters) is required and goes into the audit event; errors `reason is required` / `reason must be at most 500 characters`, as on `records/erase`. 404 for an unknown account (`admin:privacy-erase`; only support operators call it). Returns `{account_id, case_id, deleted_message_count, deleted_platform_user_count, deleted_user_note_count, deleted_automod_message_count, deleted_automod_moderation_log_count, deleted_moderation_log_count, scrubbed_history_session_count, deleted_account_bot_count, removed_held_queue_entry_count, suppressed}`. Mirrors GraphQL `eraseChatSubjectData` |
| Chat Privacy | `/v1/admin/privacy/chat/erase/withdraw` | `POST` `{account_id, platform, user_id, instruction_reference}` (all required): withdraws one channel's erasure instruction for one chatter - deletes the chatter's row in that account's `account_chatter_suppressions`, so the channel's stream reports frozen from then on name the chatter again. What the erasure deleted or blanked stays gone; other channels and the global `chatter_suppressions` list are not touched. Validation and error texts as the objection plus `account_id is required` / `instruction_reference is required`; 404 `Account not found` for an unknown account and `no channel erasure is recorded for this chatter` without an entry; only an erasure the channel initiated can be withdrawn - an entry the person asked for (and every entry recorded before the initiator was stored) is a 409 `this erasure was requested by the person, not initiated by the channel; it cannot be withdrawn on the channel's instruction` and stays (`admin:privacy-erase-withdraw`). Audit `privacy:channel_suppression_withdrawn` on success only (system scope, without the user id). Returns `{account_id, platform, suppressed}` (`suppressed` is `false`). Mirrors GraphQL `withdrawChannelChatterSuppression` |
| Chat Privacy | `/v1/admin/privacy/lumio/erase` | `POST` `{platform, user_id, login?, instruction_reference, reason}`: erasure of a person on Lumio's own surfaces only - an `erasure` entry in the global `chatter_suppressions` list (Lumio Stats leaderboard) and, on YouTube, Lumio's member cache across every account. No channel's chat, profiles, logs or reports are touched. Idempotent; validation and error texts as the objection plus `instruction_reference is required` and, for the required `reason` (trimmed, at most 500 characters, in the audit event), `reason is required` / `reason must be at most 500 characters` (`admin:privacy-erase`; only support operators call it). Returns `{platform, suppressed, erased_key_count}`. Mirrors GraphQL `eraseChatSubjectAtLumio` |
| Chat Privacy | `/v1/admin/privacy/records/erase` | `POST` `{kind, account_id, instruction_reference, reason, record_id?, created_at?, session_id?, platform?, user_id?, login?}`: erasure of **one record** in one channel on that channel's instruction. `kind` is `chat_message` (`record_id` + `created_at`, matched within ±1 s; also removes the message's text copy from the moderation log), `user_note`, `moderation_log`, `automod_log` (also its `automod_allow` / `automod_deny` moderation-log rows and a still-open held-queue entry), `bot_list` (each by `record_id`) or `stream_report` (`session_id` + `platform` + `user_id`, optional Twitch/Kick `login`: the person's entries in that report's top chatters, links, commands and keywords, and their slots in its announcements and pins, keep place and counts and lose the identity). `account_id`, `instruction_reference` and `reason` (at most 500 characters) are required. A record of another account is `404 Record not found`, like a missing one; an unknown account is `404 Account not found`; a stream report that is not finalized yet is `409`. No suppression entry is written. Errors: `kind must be one of: …`, `account_id is required`, `instruction_reference is required`, `reason is required`, `reason must be at most 500 characters`, `record_id is required`, `created_at is required for a chat_message`, `session_id is required for a stream_report`, plus the objection's chatter errors (`admin:privacy-erase`). Returns `{account_id, case_id, kind, deleted_record_count, moderation_log_text_removed_count, deleted_moderation_log_count, held_queue_entry_removed, scrubbed_entry_count}`. Mirrors GraphQL `eraseChatRecord` |
| Chat Privacy | `/v1/admin/privacy/chat/objections` | `POST` `{platform, user_id, login?}` records a chatter's GDPR-Art-21 objection in the global `chatter_suppressions`: the public Stats leaderboard masks the chatter on read, also on streams published earlier; channel reports, exports, share links and AutoMod logs are not affected; nothing is erased; idempotent (`admin:privacy-objection-create`). Returns `{platform, suppressed, reason}`. Mirrors GraphQL `addChatterObjection` |
| Chat Privacy | `/v1/admin/privacy/chat/objections/{platform}/{user_id}` | `DELETE` lifts the objection; the public Stats leaderboard names the chatter again; 404 when none is recorded, 400 for an erasure entry (`admin:privacy-objection-delete`). Mirrors GraphQL `removeChatterObjection` |
| YouTube Streams | `/v1/youtube/active-streams` | Live and upcoming YouTube broadcasts with a resolved `live_chat_id` (reads the YouTube worker's Redis cache; an upcoming broadcast without a chat ID can still appear in dashboard channel status) |
| Connections | `/v1/connections` | App credentials and channel OAuth flow |
| Bot Connections | `/v1/bot-connections`, `/v1/bot-status`, `/v1/bot-toggle`, `/v1/bot-rejoin` | Custom bot identity OAuth and control. `GET /v1/bot-connections/discord/authorize` (`bot-connections:create`, `feature:bots`, session-only) returns the verified Discord server invite of the global Lumio bot; Discord completes on the unified callback (`POST /v1/connections/oauth/discord/exchange`), never on `POST /v1/bot-connections/discord/exchange` |
| Bot Commands | `/v1/bot-commands` | Cross-platform command CRUD and global overrides |
| Bot Modules | `/v1/bot-modules` | Moderation module configs (link/spam/word/timed), extension bot module kill switch |
| Bot Module Triggers | `/v1/internal/bot-modules` | Internal trigger resolution, handler-bundle feed and handler-result actions for the bots and the Bot Module Worker (System key with `bots:internal`) |
| Extension Handler Feeds | `/v1/internal/{bot-modules,automation-nodes}/handlers` | Internal handler-code bundle + context feed for the workers' InstallRegistry (System key with `bots:internal`) |
| Automations | `/v1/automations` | Visual automation CRUD and manual execution |
| Automation Extension Nodes | `/v1/automation/extension-nodes`, `/v1/automation/webhooks` | Extension node listing and webhook receiver |
| Channel Status | `/v1/channel-status`, `/v1/channels/schedule`, `/v1/spotify/manual-connect` | Live status and the stream plan of the connected channels (`?from=&to=`, default now…+30 days, at most 60 days; both `connections:read`), Spotify manual polling (`spotify:read`) |
| Spotify | `/v1/spotify/*` | State, playback, queue, devices, playlists, search |
| Copyright | `/v1/copyright/*` | Safe/blocked songs, playlist imports, community voting |
| Notifications | `/v1/notifications` | In-app notifications, actions, and delivery preferences |
| Ideas Hub | `/v1/ideas` | Community ideas, votes, comments, @mention autocomplete, categories, tags. Moderation actions live on the same paths and are gated on the `ideas:moderate_*` admin permissions |
| OBS | `/v1/integrations/obs`, `/v1/obs-remote/*` | OBS config + remote stream/recording/scene control |
| SE Tokens | `/v1/se-tokens` | StreamElements JWT token storage |
| Discord Guilds | `GET /v1/discord-guilds`, `DELETE /v1/discord-guilds/{guild_id}` | List the account's Discord servers (`bot-connections:read`; fields as GraphQL `discordGuildConnections`, incl. `bot_removed` and `missing_permissions`) and disconnect one (`bot-connections:delete`, returns `{ success }`). Connecting a server is the Discord branch of the bot connections above |
| Abuse Reports | `/v1/abuse-reports` | User-submitted abuse reports |
| Webhooks | `/v1/webhooks/*` | Platform webhooks (Twitch, YouTube, Kick, Shopify, Stripe) |
| Billing | `/v1/billing/*` | Stripe checkout/portal/status/invoices/coupon; resolved account limits (`account-limits`). `POST /checkout`, `POST /portal` and `POST /cancel` are **session-only** - an API key gets `403` (see [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces)). `GET /status` carries `billing_enabled`; when it is `false` (no Stripe on this deployment), checkout, portal, cancel, invoices and coupon validation answer `409 BILLING_DISABLED` after their auth check, while `GET /status` itself still succeeds. `POST /checkout` requires `accept_withdrawal_waiver: true` in its body (the buyer ticked the withdrawal-waiver checkbox); a missing or `false` value answers `400 VALIDATION_ERROR` "You must accept the withdrawal waiver (accept_withdrawal_waiver) before checkout" before any Stripe call. `POST /portal` opens the customer portal without plan changes (see [Billing → Withdrawal waiver and order confirmation](../features/billing.md#withdrawal-waiver-and-order-confirmation)) |
| Playlists | `/v1/playlists`, `/v1/playlists/{id}` | Read-only system-curated playlists. Public, gated by `feature:copyright_detection` (`403` when off), see [Copyright → Public REST endpoints](../features/copyright.md#public-rest-endpoints) |
| Songs | `/v1/songs`, `/v1/songs/check`, `/v1/songs/sitemap`, `/v1/songs/{id}` | Read-only global song metadata, copyright status and the sitemap id enumeration (`after`, `limit` ≤ 5000). Public, gated by `feature:copyright_detection` (`403` when off) |
| Platforms | `/v1/platforms/metadata` | Static platform metadata (name, icon, features, scopes) |
| Features | `/v1/features/enabled`, `/v1/providers/enabled` | Public feature/provider flag reads |
| Extension Bundles | `/v1/extension-bundles` | Serve extension bundle files (JS, CSS, assets) |
| Extension Version Files | `/v1/extensions/{id}/versions/{version}/files` | List files in an extension version bundle |
| Extension Uploads | `/v1/extensions/{id}/uploads` | Upload/serve files from extension editors (icons, images) |
| Fonts | `/v1/fonts/{family}/css`, `/v1/fonts/{family}/{weight}.woff2` | DSGVO-compliant font proxy (CSS + woff2). Public scope, no auth, permissive CORS. Inputs are allowlist-validated on both routes (`400` otherwise): `family` is 1–64 characters of `A-Z a-z 0-9`, space, `+` or `-`; a weight is a multiple of 100 between 100 and 900 (on `/css`, invalid `weights` entries are ignored and duplicates collapse, `400` when none remain); `display` is one of `auto`, `block`, `swap`, `fallback`, `optional` (default `swap`). Responses carry `X-Content-Type-Options: nosniff` |
| Developer Applications | `/v1/developer/application` | Submit and view developer applications |
| Developer Verification | `/v1/developer/verification` | Submit and view own KYC verification (self-service) |
| Developer Credit Notes | `/v1/developer/credit-notes`, `/v1/admin/credit-notes`, `/v1/admin/developer-payouts` | Self-billed credit notes (Gutschrift) of developer payouts: own list and PDF; operator payout list and settlement (mark paid / failed); operator list, PDF and cancellation |
| Developer Limits | `/v1/developer/limits` | View resolved limits and request increases |
| Developer Teams | `/v1/developer/teams` | Team CRUD, members, invites, roles, permissions |
| Developer Store Profiles | `/v1/developer/profiles/{slug}`, `/v1/developer/teams/{slug}/profile` | Public developer and team profile pages |
| Admin Developer Applications | `/v1/admin/developer-applications` | Review, approve, reject developer applications |
| Admin Limit Requests | `/v1/admin/limit-requests`, `/v1/admin/developers/{id}/limit-requests` | Review developer limit increase requests |
| Admin Extension Limits | `/v1/admin/extensions/{id}/limits` | Set per-extension limit overrides |
| Admin Extension Purchases | `/v1/admin/extension-purchases/undelivered` | `GET ?first=&after=`: paid extension checkouts without delivery (still `completed`, never installed, older than 1 h), newest first. Returns `{items, next_cursor}`; each item has `id`, `extension_id`, `extension_name`, `account_id`, `account_name` (the four are `null` once deleted), `stripe_checkout_session_id`, `stripe_payment_id`, `amount` (cents), `currency`, `undelivered_reason` (`detached`, `not_installable`, `install_failed`, `refund_failed` or `null`) and `created_at`. `first` is 1-100 (default 50); `after` is the previous page's `next_cursor`. Admin `extension-purchases:read`; twin of GraphQL `adminUndeliveredExtensionPurchases`. See [Admin › Extension Purchases](../admin/extension-purchases.md) |
| Overlay Folders | `/v1/overlay-folders` | Overlay folder CRUD and move |
| Overlay Shared Links | `/v1/overlay-shared-links` | Time-limited shared overlay links (`lm_share_*`) |
| Channel Connections | `/v1/connections/channel`, `/v1/connections/status`, `/v1/connections/credential-modes`, `/v1/connections/oauth/{platform}/exchange`, `/v1/channel-connections/{id}/reconnect-flag` | Channel OAuth, reconnect prompts, the channel list (`/channel` - each row carries `channel_name` the display name (may be localized) and `channel_login` the URL-safe login/handle; GraphQL parity `channelConnections.channelLogin`, ZAF-1461; plus `missing_scopes` - the required base scopes the stored grant lacks, `[]` when nothing is missing or the grant was never recorded (`scopes` is `null`), a non-empty list means reconnect; GraphQL parity `channelConnections.missingScopes`, same `connections:read` guard as `scopes`), the per-platform status overview (`/status` - health-aware `is_connected` + `reconnect_required` + `expires_at`, plus the acting user's personal login-grant health `login_connected` + `login_reconnect_required` reported separately from the channel (ZAF-1045, GraphQL parity `connectionStatuses`), `connections:read`), the credential mode per `(platform, kind)` (`/credential-modes` - `platform`, `kind` `"channel"`/`"bot"`, `mode` `"system"`/`"account"`, `system_configured`; twin of GraphQL `platformCredentialModes`, `connections:read` + `feature:connections`), and the **unified OAuth exchange** (`/oauth/{platform}/exchange` - the single web-host callback shared by the channel, account-bot and admin global-bot system flows; redeems the structured state handle, dispatches on `kind`, binds `channel` / `bot` handles to the session of the user who started the authorize step (re-checking account access + the connect permission; the admin `global_bot` handle needs no session), and validates `return_to` fail-closed against `[web, admin]`). The channel and bot `authorize` steps are **session-only** - see [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces); `?include=follower_count` fills the optional cached `follower_count` and `?include=paid_subscriber_count` the optional cached `paid_subscriber_count` - current paid subs, Twitch Helix `total` / Kick `active_subscribers_count`, always `null` on YouTube and without `history:read` (field guard, no error); both combine as `?include=follower_count,paid_subscriber_count` (otherwise `null`, unknown include = 400; GraphQL parity `channelConnections.followerCount` / `paidSubscriberCount`) |
| Channel Info | `/v1/channel-info` | Live channel metadata for the active account |
| Stream History | `/v1/history` | Session list, reports, stats, exports, and shared report links |
| Public Stats | `/v1/public-stats` | Per-channel publicness (opt-out) settings + the unauthenticated public read model (channel + stream stats) |
| Public Stats browse | `/v1/public-stats/{browse,games}` | Public, unauthenticated cross-channel browse/ranking (metric nav) + Games directory + channel search. No auth; gated by the `system:public_stats` kill-switch; edge-cacheable |
| Emote Directory | `/v1/public-stats/emotes` | Public, unauthenticated emote-catalog browse (filter + name search + pagination). No auth; gated by the `system:public_stats` kill-switch; edge-cacheable |
| Watchlist | `/v1/watchlist` | Per-user favourite-channel list for the public Stats app. Authenticated viewer (JWT); no account/RBAC permission, no plan gate. GraphQL + REST (no WS) |
| Audit Log | `/v1/me/audit-log`, `/v1/account/audit-log` | Self-scope personal-security log and account-scope tenant audit log; the operator audit surface lives under `/v1/admin/audit-log` |
| Marketplace | `/v1/marketplace`, `/v1/store`, `/v1/categories`, `/v1/featured` | Public extension store browsing, listings, reviews, icons (`/v1/store/extensions/{id}/icon-data` serves the bytes), screenshots |
| Extension Installs | `/v1/extension-installs` | Install lifecycle, per-install storage, actions, and query/mutate/execute function calls |
| Extension Purchases | `/v1/extension-purchases` | Paid-extension checkout. Body `{ extension_id, accept_withdrawal_waiver }`: a paid checkout requires `accept_withdrawal_waiver: true` (`400 VALIDATION_ERROR`, same message as `POST /v1/billing/checkout`) and a signed-in person (`403` for tokens without one); a free-access install needs neither. `409 Extension already purchased` when the account owns it; for a subscription extension also `409 Active subscription already exists` while an earlier subscription is still running, even if its first payment was refunded |
| Extension Access | `/v1/extension-access-invites` | Private-extension access invites |
| User Roles | `/v1/user-roles` | User-scoped role CRUD (admin) |
| Well-Known | `/v1/.well-known/*` | Service discovery documents |
| Health | `/v1`, `/v1/health` | Liveness probes; `/v1/health` also carries service-dependency status and live WebSocket gauges |
| Metrics | `/metrics` | Prometheus scrape endpoint (origin root, **not** under `/v1`) |
| Admin | `/v1/admin/*` | System-admin-only endpoints: `admin-roles`, `admin-permissions`, `feature-flags`, `plans`, `coupons`, `users`, `accounts`, `api-keys` (operator management of tenant/user keys), `oauth-clients`, `system-keys`, `system-connections`, `providers`, `bot-control`, `bot-commands`, `bot-connections`, `discord-guilds`, `se-tokens`, `audit-log`, `abuse-reports`, `privacy` |

This page and the feature docs cover the endpoints in day-to-day use; the API serves more, and the OpenAPI document intentionally omits the surfaces listed under [Spec completeness policy](#spec-completeness-policy) above (everything else wired into the router is guaranteed present by a build-time test). For the exhaustive parameter list of the annotated endpoints, download `/v1/openapi.json` (or use the Swagger UI at `/v1/swagger-ui/` on deployments that enable it — not production). Feature-specific docs under **Features** document the most commonly used endpoints with their `resource:action` permissions.

## Public Songs and Playlists

All six public `GET /v1/songs*` and `GET /v1/playlists*` routes work without authentication and apply the fail-closed `feature:copyright_detection` gate. With an authenticated caller the gate resolves for that account; otherwise it resolves globally. A disabled feature returns `403 FEATURE_DISABLED`. Song reads expose global safe and blocked rows only; playlist reads expose system-curated playlists. Their [GraphQL twins](./graphql.md#public-songs-and-playlists) use the same feature gate.

| Method and path | Parameters | Result |
|---|---|---|
| `GET /v1/songs` | `page` (default 1), `limit` (default 25, maximum 100), optional `search`, `status` (`safe` or `blocked`), `source` | Paginated global songs. |
| `GET /v1/songs/check` | `spotify_track_id`, or a song `title` and `artist` | Global status for a song. |
| `GET /v1/songs/sitemap` | Optional `after` (exclusive song UUID cursor), `limit` (default and maximum 5,000) | `data.items[]` with `id` and nullable `lastmod`, plus `data.has_more`. Pass the last ID as `after` while `has_more` is true. |
| `GET /v1/songs/{id}` | Song UUID | One global song; 404 when unknown or not global. |
| `GET /v1/playlists` | None | System-curated playlist summaries. |
| `GET /v1/playlists/{id}` | Playlist UUID | One system-curated playlist with tracks; 404 when unknown. |

The sitemap song date is the row's `created_at` or `null`. Which global song lists are included is fixed on the server (safe and blocked); clients cannot change it with a query parameter. REST fields use `snake_case`, including `has_more`; GraphQL uses `camelCase`.

The public marketplace reviews (`GET /v1/marketplace/extensions/{slug}/reviews`, GraphQL `marketplaceExtensionReviews`) return `id`, `rating`, `comment`, `created_at` and `updated_at` per review. They contain no reviewer identity, neither a user ID nor a name. The store pages do not show reviewers either.

`GET /v1/connections/oauth-scopes/{platform}` returns `data: { platform, required, optional }` with full provider scope names. `required` contains base scopes and `optional` contains scopes requested on every authorization but excluded from `missing_scopes`. YouTube's optional list contains `https://www.googleapis.com/auth/yt-analytics-monetary.readonly`; Kick's required list includes `ads:read`. The route requires `feature:connections` and `connections:read`, as does its GraphQL twin `channelOAuthScopes(platform)`. An unsupported platform returns `400` with `Unsupported platform: X` (the GraphQL twin reports the same message).

## Health

### `GET /v1/health`

Public, unauthenticated. Returns the API version, uptime, per-dependency health
(PostgreSQL, TimescaleDB, Redis), and live WebSocket-server gauges. The
`websocket` block reports aggregate operational counters only - total active
sessions and broadcast channels, with no per-user or per-channel detail - and is
read lock-free, so scraping it never contends with the WebSocket broadcast path.

```json
{
  "data": {
    "status": "healthy",
    "version": "2026.8.31",
    "uptime_seconds": 3600,
    "services": {
      "postgres": { "status": "healthy", "latency_ms": 2 },
      "timescaledb": { "status": "healthy", "latency_ms": 3 },
      "redis": { "status": "healthy", "latency_ms": 1 }
    },
    "websocket": { "sessions": 128, "channels": 342 }
  },
  "_links": { "self": "https://api.lumio.vision/v1/health" }
}
```

`status` is `healthy` when every dependency is healthy, `degraded` when at least
one is up but not all, and `unhealthy` when all dependencies are down.

## Metrics (Prometheus)

### `GET /metrics` (internal only)

**Not on the public ingress.** `/metrics` is an operations endpoint - metric
names and route lists are recon material - so for the API it is served by a
**separate internal server bound to loopback** (`127.0.0.1:9100` by default),
outside the `/v1` scope and never on the public `api.lumio.vision` origin. A
scraper reaches it only over an internal network (bind it with
`LUMIO__METRICS__HOST=0.0.0.0` and publish that port to the scraper alone). It
serves the Prometheus 0.0.4 text exposition format
(`Content-Type: text/plain; version=0.0.4`). See
[Operational Metrics](../developer-guide/metrics.md) for the full `/metrics`
layout, the shared series, and the cardinality rules.

The endpoint renders the shared `lo-metrics` exposition - `http_requests_total`,
`http_request_duration_seconds`, and the Linux `process_*` series - plus the
API's own live operational gauges below. Every series additionally carries the
`service` and `env` constant labels. Each value is read lock-free (atomic gauge
loads and connection-pool counters) at scrape time by a pull-time collector over
the running `AppState`, so a scrape never contends with the WebSocket broadcast
hot path. The WebSocket gauges mirror the `websocket` block on `/v1/health`;
exposing them here lets operators confirm the connection-leak fix (`ZAF-396`)
holds in production without waiting ~72h to observe the *absence* of a wedge.

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `lumio_build_info` | gauge | `version` | Constant `1`; running build version in the label |
| `lumio_uptime_seconds` | gauge | - | Seconds since the API process started |
| `lumio_websocket_sessions` | gauge | - | Active WebSocket sessions |
| `lumio_websocket_channels` | gauge | - | Active WebSocket broadcast channels |
| `lumio_db_pool_connections` | gauge | `pool` | Connections owned by the pool (`postgres`, `timescaledb`) |
| `lumio_db_pool_idle` | gauge | `pool` | Idle connections available for checkout |

```text
# HELP lumio_websocket_sessions Active WebSocket sessions.
# TYPE lumio_websocket_sessions gauge
lumio_websocket_sessions{env="prod",service="api"} 128
# HELP lumio_websocket_channels Active WebSocket broadcast channels.
# TYPE lumio_websocket_channels gauge
lumio_websocket_channels{env="prod",service="api"} 342
# HELP lumio_db_pool_connections Connections owned by the pool (idle + in-use).
# TYPE lumio_db_pool_connections gauge
lumio_db_pool_connections{env="prod",pool="postgres",service="api"} 8
lumio_db_pool_connections{env="prod",pool="timescaledb",service="api"} 3
```

The endpoint carries only aggregate operational counters - no per-user,
per-channel, or per-request detail (the hard cardinality rule) - matching the
`websocket`, `version`, and `uptime` fields also visible as JSON on `/v1/health`.

## Auth

### `POST /v1/auth/popout/exchange`

Exchange a raw popout token (`lm_pop_*`) for a short-lived **popout session** - the REST twin of GraphQL `exchangePopoutToken`. See [Authentication → Popout Tokens & Popout Sessions](./authentication.md#popout-tokens--popout-sessions) for the full model.

**Auth:** none - possession of a valid popout token IS the authorization (as `?token=` is today).

**Request body:**

```json
{ "token": "lm_pop_..." }
```

**Response** - also sets the session as an httpOnly cookie `lumio-popout-token` (`Path=/`, `SameSite=Lax`, `Secure` outside development, `Max-Age` = 15 min):

```json
{
  "data": {
    "token": "lm_...",
    "expires_at": "2026-08-12T12:15:00Z",
    "account_id": "…"
  }
}
```

Validates the token (prefix + `revoked_at` / `expires_at`) and mints a 15-minute session JWT carrying the token's permission subset. The session resolves to the **same** popout auth context as the raw token (identical account, permission subset, OBS credential gate) - never a full user session. A revoked, expired, unknown, or non-popout token returns `401` with `Invalid or expired popout token`.

### `GET /v1/auth/popout/session`

Read the `(account_id, user_id)` pair the current popout session represents - the REST twin of GraphQL `popoutSession`. See [Authentication → Popout Tokens & Popout Sessions](./authentication.md#popout-tokens--popout-sessions) for the full model.

**Auth:** any authenticated context, including a popout token / session (the `?token=lm_pop_*` query param or the httpOnly `lumio-popout-token` cookie). It is **not** first-party gated. Anonymous is rejected with `401 Authentication required` - the same message the GraphQL `AuthGuard` emits.

**Response:**

```json
{
  "data": {
    "account_id": "…",
    "user_id": "…",
    "locale": "auto",
    "timezone": "auto",
    "date_format": "auto",
    "time_format": "auto",
    "season_look_enabled": true,
    "season_strength": "full",
    "season_motion": "auto",
    "season_creatures": {},
    "season_banner_dismissed": [],
    "motion_preference": "system"
  }
}
```

The `account_id` / `user_id` pair is read straight from the auth context (`auth.account_id()` / `auth.user_id()`) - never a client parameter, so the scope cannot be forged, and the response carries only the caller's **own** session ids. `user_id` is always the user the popout token is bound to - every popout token is bound to an explicit user and there is no owner fallback (ZAF-1922). No permission guard and no audit event (a read of the caller's own session).

The four display-preference fields (`locale`, `timezone`, `date_format`, `time_format`) are the represented user's stored preferences (same value space as [`GET /users/me`](#get-usersme)), so a popout - which cannot reach the first-party-gated `me` - can render language, timezone and date/time format. The five `season_*` fields carry the seasonal-look preferences and `motion_preference` the "Animations in Lumio" preference the same way (written via `PATCH /users/me`, which a popout cannot reach; a popout session's only two writes are the one-way season routes below). They carry the represented user's values (assigned member, or account owner for an unassigned token).

### `POST /v1/auth/popout/season-banner/dismiss`

Dismiss the season banner for one season instance on behalf of the current **popout session** - the REST twin of GraphQL `popoutDismissSeasonBanner`. One of exactly two one-way profile writes a popout may make (see [Authentication → Popout Tokens & Popout Sessions](./authentication.md#popout-tokens--popout-sessions)).

**Auth:** popout-only - a popout token or popout session. Anonymous → `401 Authentication required`; any other credential (user session, API key, overlay, shared-overlay, widget, extension) → `403 This endpoint requires a popout session`. A logged-in user writes the same list through [`PATCH /users/me`](#patch-usersme). The guard runs before validation.

**Request:**

```json
{ "instance": "halloween:2026" }
```

`instance` is `<seasonId>:<year>`. The season id must be a known season - the server-side list `user_preferences::SEASON_IDS` is `halloween`, `nicholas`, `christmas`, `new-year`, `easter` - every season of the web registry (`apps/web/src/lib/seasons/registry.ts`) plus the planned ones; a season outside it extends both. The year must be within ±1 of the current year. Anything else is a `400` validation error - `Invalid season instance: must be '<seasonId>:<year>'`, `Invalid season instance: unknown season id (allowed: halloween, nicholas, christmas, new-year, easter)` or `Invalid season instance: year must be between <y-1> and <y+1>`. Free text is never echoed back.

**Response:**

```json
{ "data": { "season_look_enabled": true, "season_banner_dismissed": ["halloween:2026"] } }
```

Appends `instance` to the represented user's `season_banner_dismissed` and changes nothing else. Idempotent: an instance already in the list is a no-op (no write). The same dedupe and 50-entry cap as `PATCH /users/me` apply - a full list drops its oldest entry. No audit event (UI bookkeeping) and no WebSocket push (the account events channel would leak one user's preference to every viewer).

### `POST /v1/auth/popout/season-look/off`

Switch the seasonal look **off** on behalf of the current **popout session** - the REST twin of GraphQL `popoutSwitchOffSeasonLook`. Same auth, request body, validation and error text as [`POST /v1/auth/popout/season-banner/dismiss`](#post-v1authpopoutseason-bannerdismiss).

Sets the represented user's `season_look_enabled = false` and, in the same write, appends `instance` to `season_banner_dismissed`, so switching the look back on later does not bring this season's banner back. `season_look_enabled` is the **global** switch (all seasons), the same one the Settings toggle writes. **Off only:** no popout route can set it to `true` or change `season_strength`, `season_motion` or `season_creatures` - turning the look on again is a dashboard Settings action ([`PATCH /users/me`](#patch-usersme)). Idempotent (look already off + instance present = no write). Response shape as above, with `"season_look_enabled": false`. No audit event, no WebSocket push.

### `POST /v1/auth/popout/ws-token`

Mint a **WebSocket-scoped** token for the current **popout session** - the REST twin of GraphQL `issuePopoutWsToken`, and the popout counterpart of `POST /v1/auth/ws-token`.

**Auth:** a popout session (the httpOnly `lumio-popout-token` cookie, or a popout session bearer). This is **popout-only**: `POST /v1/auth/ws-token` is session-only (see the note above) and returns `403` for a popout, so a popout cannot mint there. A non-popout caller here is rejected with `401 UNAUTHORIZED` (no credentials) or `403 FORBIDDEN` (any non-popout credential).

**Response:**

```json
{ "data": { "ws_token": "lm_..." } }
```

The minted token carries the popout's **own** permission subset (never the account owner's), a WebSocket-only use tag, and **no `session_id`**. The API accepts it **only** on the `/v1/ws` upgrade path - a leak of the `?token=` WS URL cannot be replayed against a REST/GraphQL mutation. It is short-lived (`auth.ws_token_expiration`, ~15 min); the popout re-mints on reconnect.

## Contact form

### `POST /v1/contact`

Public, no authentication. Forwards one message to the Lumio inbox (`[contact] recipient`, default `hey@lumio.vision`) as an e-mail whose `Reply-To` is the sender's address. Nothing is stored: there is no table and no retention job. Logs record only the outcome and the subject category, never the name, address or message. The GraphQL twin `submitContactMessage` calls the same service, so validation, limits and error codes and texts are identical.

| Field | Type | Rule |
|---|---|---|
| `name` | string, optional | At most 100 characters, no control characters; blank counts as absent. |
| `email` | string | A valid e-mail address; becomes the `Reply-To`. |
| `subject` | string | One of `general`, `privacy`, `legal`, `billing`, `other`. |
| `message` | string | 1 to 5000 characters after trimming. |
| `turnstile_token` | string | Cloudflare Turnstile token for action `contact`, issued on a web-app hostname (`turnstile.web_hostnames`). |

The checks run in this order: fields, then 5 messages per IP per hour, then Turnstile, then 100 forwarded messages per hour in total (only requests that passed Turnstile count). A field error therefore never uses up the single-use Turnstile token. The generic per-IP limit of the `/v1` scope applies as well.

**Response** `200`: `{ "data": { "status": "sent" } }`. The mail is sent in the background.

| Status | `error` | `message` |
|---|---|---|
| 400 | `INVALID_EMAIL` | `Enter a valid email address` |
| 400 | `INVALID_CONTACT_NAME` | `The name can have at most 100 characters` |
| 400 | `INVALID_CONTACT_SUBJECT` | `Choose a subject: general, privacy, legal, billing or other` |
| 400 | `INVALID_CONTACT_MESSAGE` | `The message needs 1 to 5000 characters` |
| 400 | `TURNSTILE_REQUIRED` | `Please complete the security check` |
| 400 | `TURNSTILE_FAILED` | `The security check failed. Please try again` |
| 429 | `RATE_LIMITED` | `Too many requests. Try again later` (`details.retry_after_secs` and a `Retry-After` header) |
| 503 | `TRY_AGAIN` | `Please try again in a moment` (Turnstile or the limit store unavailable) |

## API Keys

User API keys are personal bearer credentials with the `lm_usr_` prefix. Each key is bound to the current `(user_id, account_id)` and can only carry permissions the creator already has. The dashboard uses these endpoints for **Settings → Channel → Access → API Keys**; the full key is returned once from the create response and cannot be retrieved later.

All paths live under `/v1/api-keys` and are gated on `feature:apikeys`. Bodies use snake_case.

> **First-party session required (ZAF-1017 / ZAF-469):** personal API keys are a first-party surface - every path below requires a logged-in user session or a user's own API key. A popout/overlay/widget/extension token, whose `user_id` is bound at token-create time and could be the account owner, is rejected with `403 FORBIDDEN` on both REST and GraphQL. This stops a permission-capped member from listing/minting/renaming/revoking a key **bound to the owner** (an owner-bound `lm_usr_` key would otherwise launder past this same gate - e.g. `PATCH /v1/users/me` email change → owner takeover).

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| `GET` | `/v1/api-keys/permissions?kind=personal\|service` | `apikeys:read` | List the scopes assignable to an API key of the given kind |
| `GET` | `/v1/api-keys` | `apikeys:read` | List the caller's own user API keys for the active account |
| `POST` | `/v1/api-keys` | `apikeys:create` | Create a user API key; returns the full `lm_usr_` key once. **Session-only** - an API key cannot mint keys |
| `PATCH` | `/v1/api-keys/{id}` | `apikeys:edit` | Rename one of the caller's own keys (label only) |
| `POST` | `/v1/api-keys/{id}/rotate` | `apikeys:edit` | Rotate one of the caller's own keys - regenerate the secret in place; returns the new full `lm_usr_` key once. **Session-only** - an API key cannot rotate keys |
| `DELETE` | `/v1/api-keys/{id}` | `apikeys:delete` | Revoke one of the caller's own keys by hard-deleting it |

### Assignable scopes

An API key may carry **any permission the account/user behind it can** - not the deliberately narrow popout-token list. `GET /v1/api-keys/permissions?kind=personal|service` returns the assignable-scope registry (key + label + category), derived from the RBAC registries minus a small deny-list; it is the source of truth for the picker (parity with GraphQL `apiKeyAssignablePermissions`). `kind` is required - an unknown value returns `400 VALIDATION_ERROR`.

- **Personal keys** (`kind=personal`, `lm_usr_`) carry the **129** account permissions left after the four-key API-key deny-list plus the **10** user-scoped `ideas:*` permissions (**139** assignable scopes) - a personal key acts with its member's user identity, so `ideas:*` are reachable via the key (ZAF-1169).
- **Service keys** (`kind=service`, `lm_svc_`) carry those **129** assignable account permissions only - an account-owned key has no user identity, so the user-scoped family is not offered.
- **Deny-list (both kinds):** `apikeys:create`, `apikeys:edit`, `tokens:create` (credential minting - a key that mints credentials would outlive the human it belongs to) and `account:delete` (tenant destruction). These are never assignable.

On create, each requested scope is validated against this registry **first** - an unknown or deny-listed string is rejected with `400 VALIDATION_ERROR` "Invalid permission: `{perm}`" (identical to role writes) - and then against the subset rule (a key can never exceed its creator; over-reach → `403 FORBIDDEN`). Wildcards (`resource:*`) are never offered in the picker but are accepted from a principal that legitimately holds them. Scopes are **immutable after creation** - a too-narrow key must be re-minted.

**Create request:**

```json
{
  "label": "CI/CD pipeline",
  "permissions": ["events:read", "overlays:read"],
  "expires_at": "2026-09-01T00:00:00Z"
}
```

`label` is required. `expires_at` is optional; omit it or send `null` for a non-expiring key.

Every key object (list, create, rename, rotate) carries `permissions`, the stored scope list, and `effective_permissions`, the stored scopes the owner's current role still grants. Only `effective_permissions` authorize requests; a scope missing from it is dormant and returns when the owner regains it. `/v1/tokens` objects carry the same pair, capped to the token's bound member. If the owner's permissions cannot be read, the request fails instead of reporting the stored list. Parity with GraphQL `UserApiKey.effectivePermissions` / `PopoutToken.effectivePermissions`.

**Create response:**

```json
{
  "data": {
    "key": "lm_usr_xxxxxxxxxxxx",
    "id": "uuid",
    "user_id": "uuid",
    "account_id": "uuid",
    "key_prefix": "lm_usr_ab",
    "label": "CI/CD pipeline",
    "permissions": ["events:read", "overlays:read"],
    "effective_permissions": ["events:read", "overlays:read"],
    "created_at": "2026-08-16T10:00:00Z",
    "expires_at": "2026-09-01T00:00:00Z",
    "last_used_at": null
  },
  "_links": {
    "self": {
      "href": "/v1/api-keys/uuid"
    }
  }
}
```

**Rotate.** `POST /v1/api-keys/{id}/rotate` (gated `apikeys:edit` + `feature:apikeys`) regenerates the secret of one of the caller's own keys in place - the key id, label and scopes are unchanged, the old secret stops working immediately, and the response returns the new full `lm_usr_` `key` **once** (same shape as the create response). It emits the `user:api_key_rotated` audit event (metadata `api_key_id`, `old_key_prefix`, `new_key_prefix`). Parity with GraphQL `rotateUserApiKey`.

## Service Keys

Account-owned service keys are bearer credentials with the `lm_svc_` prefix, for CI/CD pipelines and long-lived integrations. Unlike personal `lm_usr_` API keys they are owned by the **account** and **keep authenticating after the member who created them leaves** - they carry no member identity. They share the `feature:apikeys` flag and the `apikeys:*` permission family with personal keys, and the create path enforces the same permission-subset guard (a key can only carry permissions the creator holds). The full key is returned once from the create response and cannot be retrieved later.

All paths live under `/v1/service-keys`. Bodies use snake_case. Every endpoint is gated on `feature:apikeys`. Create and rotate mint a credential, so they additionally require an **interactive sign-in session** (a logged-in user only - a popout/overlay/widget/extension token, a personal `lm_usr_` key, a service `lm_svc_` key or a system key is rejected with `FORBIDDEN` "This action requires an interactive sign-in session"; ZAF-1742 rule, applied to service keys by ZAF-1740 C3).

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| `GET` | `/v1/service-keys` | `apikeys:read` | List the account's service keys |
| `POST` | `/v1/service-keys` | `apikeys:create` + interactive session | Create a service key; returns the full `lm_svc_` key once |
| `PATCH` | `/v1/service-keys/{id}` | `apikeys:edit` | Rename a service key (label only) |
| `POST` | `/v1/service-keys/{id}/rotate` | `apikeys:edit` + interactive session; caller must hold every scope on the key | Rotate a service key - regenerate the secret in place; returns the new full `lm_svc_` key once |
| `DELETE` | `/v1/service-keys/{id}` | `apikeys:delete` | Revoke a service key by hard-deleting it |

**Create request:**

```json
{
  "label": "CI/CD deploy",
  "permissions": ["events:read", "overlays:read"],
  "expires_at": null
}
```

`label` is required. `expires_at` is optional; omit it or send `null` for a non-expiring key.

**Create response:**

```json
{
  "data": {
    "key": "lm_svc_xxxxxxxxxxxx",
    "id": "uuid",
    "account_id": "uuid",
    "created_by": "uuid",
    "key_prefix": "lm_svc_ab",
    "label": "CI/CD deploy",
    "permissions": ["events:read", "overlays:read"],
    "created_at": "2026-09-04T10:00:00Z",
    "updated_at": "2026-09-04T10:00:00Z",
    "expires_at": null,
    "last_used_at": null
  },
  "_links": {
    "self": {
      "href": "/v1/service-keys/uuid"
    }
  }
}
```

`created_by` records the member who minted the key; it becomes `null` once that member is removed from the account (the key itself keeps working). Lifecycle changes emit the account-scoped audit events `account:service_key_created` / `account:service_key_updated` / `account:service_key_revoked` / `account:service_key_rotated`. Parity with GraphQL `accountServiceKeys` / `createAccountServiceKey` / `updateAccountServiceKey` / `deleteAccountServiceKey` / `rotateAccountServiceKey`.

**Rotate.** `POST /v1/service-keys/{id}/rotate` (gated `apikeys:edit` + `feature:apikeys` + an **interactive sign-in session**, checked before the key is looked up) regenerates a service key's secret in place - id, label and scopes unchanged, the old secret invalidated immediately - and returns the new full `lm_svc_` `key` **once** (same shape as the create response). The caller must hold every scope on the key - rotating hands out a fresh secret with those scopes, so it is held to the same ceiling as create and refused with `403 FORBIDDEN` "Cannot grant permission '…'" otherwise (ZAF-1740 M5). It emits `account:service_key_rotated` (metadata `service_key_id`, `old_key_prefix`, `new_key_prefix`). Parity with GraphQL `rotateAccountServiceKey`.

## Developer API Keys

Developer API keys (`lm_dev_` prefix) are the publishing credential for extension developers - the key `lumio deploy` and CI use instead of a personal `lm_usr_` key. Unlike service keys they are **not** owned by an account: a developer key is bound to a developer **profile** or a developer **team**, carries **no account** and **no member identity**, and (like a service key) keeps authenticating after the member who minted it leaves the team. A developer key can carry **only** the `extension-dev:*` permission family, and - unlike every other key - is **decoupled from the plan gate**: eligibility is approved-developer status, not the Pro plan, so it is **not** gated on `feature:apikeys`. The full key is returned once from the create response and cannot be retrieved later.

All paths live under `/v1/developer/api-keys`. Bodies use snake_case. Management is **first-party only** - these endpoints require a logged-in user session, so a `lm_dev_` key can never mint or revoke another developer key. Minting (`POST`) is **session-only**: a user's own `lm_usr_` key is refused too (ZAF-1742, see [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces)).

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| `GET` | `/v1/developer/api-keys` | Auth (developer) | List the caller's developer keys (own profile + member teams) |
| `POST` | `/v1/developer/api-keys` | Auth (developer) + `team-secrets:edit` for a team key | Create a developer key; returns the full `lm_dev_` key once |
| `PATCH` | `/v1/developer/api-keys/{id}` | Auth (developer) + `team-secrets:edit` for a team key | Rename a developer key (label only) |
| `DELETE` | `/v1/developer/api-keys/{id}` | Auth (developer) + `team-secrets:edit` for a team key | Revoke (soft-delete) a developer key |

**Create request:**

```json
{
  "label": "CI deploy",
  "permissions": ["extension-dev:edit", "extension-dev:publish"],
  "team_id": null,
  "expires_at": null
}
```

`label` and `permissions` are required; every permission must be in the `extension-dev:*` family and cannot exceed what the creator holds. `team_id` binds the key to a developer team you belong to (requires the team's `team-secrets:edit` right) - omit it or send `null` to bind the key to your own developer profile. `expires_at` is optional (RFC3339; `null` = never).

**Rename / revoke authorization.** Both are scoped to the caller's developer identity: a key that does not exist or belongs to a profile or team the caller is not part of returns **404** `Not found: Developer key not found` (key existence is never disclosed). A **profile** key can be renamed or revoked by its owner. A **team** key additionally requires the caller's *current* developer-team right `team-secrets:edit` on that team - the same right that creating it requires. A member without it (e.g. the default **Member** role, which only holds `team-secrets:read`) can see the key but gets **403** `Missing team permission: team-secrets:edit` for both rename and revoke; there is no membership-only revoke - a member who suspects a leak asks a `team-secrets:edit` holder to revoke it. Re-revoking an already-revoked key is an authorized no-op `204`.

Lifecycle changes emit the **user-scoped** audit events `user:developer_api_key_created` / `user:developer_api_key_updated` / `user:developer_api_key_revoked` (there is no owning account to hang an account-scoped event on). Parity with GraphQL `developerApiKeys` / `createDeveloperApiKey` / `updateDeveloperApiKey` / `revokeDeveloperApiKey`.

## Sounds

All sound endpoints require the `feature:sounds` feature flag to be enabled for the account.

### `GET /v1/sounds`

List sounds in the account's library.

**Permission:** `sounds:read`

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | integer | Page size (default 20, max 100) |
| `offset` | integer | Pagination offset |
| `search` | string | Filter by name (partial match) |

**Response** - the list also carries the account's resolved sound limits and current usage:

```json
{
  "data": {
    "sounds": [
      {
        "id": "uuid",
        "account_id": "uuid",
        "name": "Tada",
        "filename": "tada.mp3",
        "content_type": "audio/mpeg",
        "size_bytes": 45312,
        "duration_ms": 2100,
        "waveform": null,
        "created_at": "2026-05-28T10:00:00Z",
        "source_extension_name": null
      }
    ],
    "total_count": 1,
    "user_sound_count": 1,
    "max_sounds": 50,
    "max_sound_file_size": 5242880,
    "max_sound_storage_bytes": 104857600,
    "used_storage_bytes": 45312
  },
  "_links": { "self": "https://api.lumio.vision/v1/sounds" }
}
```

### `GET /v1/sounds/{id}`

Get a single sound by ID.

**Permission:** `sounds:read`

**Response:** Sound object (same shape as list items).

### `POST /v1/sounds`

Upload a new sound file.

**Permission:** `sounds:create`

**Body:** `multipart/form-data`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | file | Yes | Audio file (MP3, WAV, OGG, FLAC). Max size set by `max_sound_file_size` plan limit. |
| `name` | string | No | Display name (defaults to filename without extension) |

**Errors:**
- `400` `BAD_REQUEST` / `VALIDATION_ERROR` - Unsupported file type or file exceeds size limit
- `403` `PLAN_LIMIT_REACHED` - Account has reached the `max_sounds` or storage plan limit

**Response:** 201 Created with the new sound object.

### `PATCH /v1/sounds/{id}`

Update sound metadata.

**Permission:** `sounds:edit`

**Body:** all fields optional.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New display name |
| `duration_ms` | integer | Duration in milliseconds |
| `waveform` | JSON | Precomputed waveform peaks |

**Response:** Updated sound object.

### `DELETE /v1/sounds/{id}`

Delete a sound.

**Permission:** `sounds:delete`

**Response:** 204 No Content.

### `POST /v1/sounds/{id}/play`

Trigger playback of a sound in browser sources.

**Permission:** `sounds:play`

**Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `volume` | float | No | Playback volume 0.0–1.0 (default 1.0) |
| `target` | object | No | `{ "type": "widget" \| "overlay", "id": "uuid" }`. Omit to broadcast to all browser sources; any other `type` is rejected. |

**Response:** 200 `{ "success": true }` (bare body, no HATEOAS envelope)

### `POST /v1/sounds/{id}/stop`

Stop playback of a sound in browser sources.

**Permission:** `sounds:play`

**Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `target` | object | No | `{ "type": "widget" \| "overlay", "id": "uuid" }`. Omit to broadcast to all browser sources; any other `type` is rejected. |

**Response:** 200 `{ "success": true }` (bare body, no HATEOAS envelope)

### `GET /v1/sounds/{id}/stream`

Stream the audio bytes for a sound. Used by browser sources to load and play the audio.

**Permission:** `sounds:read`

**Response:** Raw audio bytes with the correct `Content-Type` header (e.g. `audio/mpeg`) and `Cache-Control: private, max-age=86400, immutable`. The payload is account-scoped and carries no `Vary`, so it is marked `private` - long-lived in the caller's own browser cache but never storable in a shared/CDN cache.

> **Protocol parity:** All endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#sounds).

## Widgets

### Instances

#### `GET /v1/widgets`

List the widget instances of the active account.

**Permission:** `widgets:read`

**Visibility:** per-widget grants apply. A widget on which the caller has the role `none` is left out; a widget without an entry for the caller, or with `viewer`/`editor`, is listed. A caller with `widgets:access-read` sees every widget of the account. Same rule as `GET /v1/overlays` and GraphQL `widgetInstances`.

**Widget object:** `id`, `account_id`, `name`, `widget_type`, `extension_id`, `install_id`, `config`, `width`, `height`, `created_at`, `updated_at` and `extension`. `extension` is `null` for a built-in widget. For an extension widget it is the GraphQL [`WidgetExtensionRef`](./graphql.md#widgetextensionref) in snake_case: `id`, `slug`, `name`, `visibility`, `icon_key`, `developer_name`, `version`, `targets`, `config_schema`, `designer_schema`, `permissions`. `permissions` holds the manifest permissions of that version, `[]` when it declares none. Every endpoint that returns a widget (`GET /v1/widgets`, `GET /v1/widgets/{id}`, `POST /v1/widgets`, `PATCH /v1/widgets/{id}`, `POST /v1/widgets/{id}/duplicate`) uses this shape.

#### `POST /v1/widgets`

Create a widget instance with a one-time access token and OBS URL.

**Permission:** `widgets:create`

**Body:** `name`, `widget_type`, optional `install_id`, `extension_id`, `config`, `width`, `height`.

**Extension binding:** `extension_id` is never stored as sent. With an `install_id`, the install must be a live install of the active account (not soft-uninstalled), and the widget takes that install's extension. The check runs in the same transaction as the insert.

| Condition | Response |
|-----------|----------|
| `install_id` unknown, from another account, or soft-uninstalled | `404` `Extension install not found` |
| `extension_id` differs from the install's extension, or `widget_type` names another extension (its slug, `ext:<slug>`, or a built-in type of another system extension) | `400` `Widget extension does not match the install` |
| `extension_id` or an `ext:` `widget_type` without `install_id` | `400` `An extension widget requires an install_id` |
| Plan widget limit reached | `403` `Widget limit reached (…). Upgrade your plan for more widgets.` |

**Response:** 201 Created with the widget object, `access_token` and `obs_url`.

### Access Management

#### `GET /v1/widgets/{id}/access`

List access entries for a widget.

**Permission:** `widgets:access-read`

**Response:** List of access entries with `id`, `widget_id`, `user_id`, `user_name`, `user_avatar`, `role`, `granted_by`, and `created_at`.

#### `GET /v1/widgets/{id}/access/candidates`

List account members eligible for the widget access dialog.

**Permission:** `widgets:access-read`

**Response:** List of account members with `id` (the user ID), `display_name`, and `avatar_url`.

#### `PUT /v1/widgets/{id}/access/{user_id}`

Set a user's access role on a widget.

**Permission:** `widgets:access-grant`

**Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `role` | string | Yes | `"viewer"`, `"editor"`, or `"none"`. Any other value is rejected with `400 BAD_REQUEST` (`Invalid role`). |

**Response:** 200 with the updated access entry.

#### `DELETE /v1/widgets/{id}/access/{user_id}`

Remove a user's access entry from a widget.

**Permission:** `widgets:access-revoke`

**Response:** 204 No Content.

### Duplication

#### `POST /v1/widgets/{id}/duplicate`

Duplicate a widget instance. Creates a copy of the widget with its configuration and returns the new widget with an access token.

**Permission:** `widgets:create`, plus **Editor** access on the source widget (a copy carries the full configuration). `widgets:access-grant` bypasses the per-widget check; `widgets:access-read` does not. A source the caller cannot edit answers `404` `Widget not found`, the same as a missing one.

**Limits:** the plan widget limit is checked inside the insert, so concurrent creates and duplicates cannot exceed it (`403` `Widget limit reached (…). Upgrade your plan for more widgets.`). A source bound to an extension install that is no longer live is not copied (`404` `Extension install not found`).

**Response:** 201 Created with the new widget object including `access_token`.

> **Protocol parity:** All endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#widgets).

## Setting Presets

Named snapshots of chat/events/music display settings, keyed to the pair `(user, account)` (ZAF-622 §52c; see [Setting Presets](../features/setting-presets.md)). All endpoints require the `feature:setting_presets` feature flag. Create/edit/delete are scoped to *(the authenticated user, their active account)* with no `resource:action` permission and fail-closed on membership; a preset owned by another user, living in another account, or in an account you have left is never visible or mutable (it reads as `404`). The **one** RBAC gate is `presets:share` on the share/un-share endpoints.

**Popout access:** the read endpoints (`GET`) accept a **popout token** so the OBS-source popout can list and load presets. The write endpoints (`POST`/`PATCH`/`DELETE`, incl. share/un-share) require a **first-party user session** (a logged-in user or the user's own API key) - a popout/overlay/widget/extension token is rejected with `403 FORBIDDEN`. This is deliberate: a popout token authenticates as the member it is bound to, not as the person holding it, so allowing writes there would let whoever holds the token act as that member (ZAF-450/469).

**Account sharing (ZAF-622 §19):** a user can share one of their own presets with the members of their active account. `GET /v1/setting-presets` for a **first-party** caller then also returns presets shared into that account by a still-member owner - each such foreign row is marked `shared: true` with `owner_display_name`. Over a **popout token the list stays restricted to your own presets** (no shared branch). Sharing is a flag on the existing row (no copy) and costs no quota; loading a shared preset writes nothing server-side. See the `.../share` endpoints below.

The quota is one number spanning all kinds combined, resolved **per account** from that account's own plan (`plans.max_setting_presets`, overridable per account via `account_limits.max_setting_presets`; `0 = unlimited`) - a full account never blocks a different one. The effective limit is also readable without creating a preset - as `maxSettingPresets` on the GraphQL `accountLimits` query and its REST twin `GET /v1/billing/account-limits` (both gated on `plan:read`) - so a UI can render "N of M used".

### `GET /v1/setting-presets`

List the current user's presets.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `kind` | string | Optional filter: `chat` \| `events` \| `music` |

**Response:** `data` is an array of preset objects (`id`, `user_id`, `kind`, `name`, `payload`, `is_default`, `shared_account_id`, `shared`, `owner_display_name`, `created_at`, `updated_at`). Own rows sort first (default-first, then most-recently-changed) with `shared: false`; foreign rows shared into your active account follow, with `shared: true` + `owner_display_name`. A popout token sees only own rows.

### `GET /v1/setting-presets/quota`

Your own preset quota in the active account. Per-account (no `resource:action` permission, popout-token readable) - deliberately **not** `plan:read`, so every member sees their limit.

**Response:** `data` is `{ used, limit }` - `used` counts your own presets in the active account across all kinds (foreign rows shared into your account never count), `limit` is the account's resolved cap with `0` meaning unlimited. Both come from the functions the create path gates on, so this read and the create rejection can never disagree.

### `GET /v1/setting-presets/{id}`

Get a single preset by ID. Returns `404` if it does not exist or belongs to another user.

### `POST /v1/setting-presets`

Create a preset. **First-party session only.**

**Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `kind` | string | Yes | `chat` \| `events` \| `music` |
| `name` | string | Yes | Display name (non-empty, ≤ 255 chars). Duplicate names are allowed. |
| `payload` | object | Yes | The settings snapshot (the ZAF-622 export format, `{ "format": 1, ... }`). Opaque to the backend. |
| `is_default` | boolean | No | Mark as this kind's default (unsets the previous default of the same kind) |

**Errors:**
- `400` `BAD_REQUEST` - invalid `kind`, empty name, or non-object/oversized payload
- `403` `FORBIDDEN` - wrong token class (not a first-party session) / feature disabled
- `409` `PLAN_LIMIT_REACHED` - the user is at their preset quota

**Response:** the created preset object.

### `PATCH /v1/setting-presets/{id}`

Rename and/or overwrite a preset (same route serves both; moves `updated_at`). **First-party session only.**

**Body:** at least one of:

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New name (rename) |
| `payload` | object | New settings snapshot (overwrite) |

**Response:** the updated preset object; `404` if not found or foreign.

### `POST /v1/setting-presets/{id}/default`

Mark the preset as its kind's default (unsets the previous default of that kind). **First-party session only.**

**Response:** the updated preset object; `404` if not found or foreign.

### `DELETE /v1/setting-presets/{id}`

Hard-delete a preset (no trash). **First-party session only.**

**Response:** `200 { "success": true }`; `404` if not found or foreign.

### `POST /v1/setting-presets/{id}/share`

Share one of your own presets with the members of your **active account**. **First-party session + `presets:share`.** The target account is always the caller's active account; a second share re-points the same row (no copy) and costs no quota. Emits `account:setting_preset_shared`.

**Errors:**
- `403` `FORBIDDEN` - `Missing permission: presets:share`, wrong token class, or feature disabled
- `404` `NOT_FOUND` - `Setting preset not found` (missing or not owned by the caller)

**Response:** the updated preset object (`shared_account_id` set).

### `DELETE /v1/setting-presets/{id}/share`

Un-share one of your own presets (make it private again). **First-party session + `presets:share`.** Idempotent - un-sharing an already-private preset succeeds and emits no event; otherwise emits `account:setting_preset_unshared` keyed to the account it was shared into.

**Response:** the updated preset object (`shared_account_id` cleared); `404` if not found or foreign.

> **Protocol parity:** All endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#setting-presets).

## Automation Extension Nodes

### `GET /v1/automation/extension-nodes`

List all installed automation node extensions for the current account.

**Permission:** `automations:read`

**Response:**

```json
{
  "data": [
    {
      "extension_id": "uuid",
      "install_id": "uuid",
      "name": "Shopify Order Trigger",
      "node_type": "trigger",
      "input_schema": { ... },
      "output_schema": { ... },
      "trigger_mode": "webhook",
      "icon": "shopping-cart",
      "color": "#96bf48"
    }
  ]
}
```

### `GET /v1/automation/webhooks/{install_id}/{automation_id}`

Get the webhook URL and secret for an installed trigger node within a specific automation.

**Permission:** `automations:read`

**Response:**

```json
{
  "data": {
    "webhook_url": "https://api.lumio.vision/v1/automation/webhooks/{extension_id}/{install_id}",
    "webhook_secret": "64-char-hex-string"
  }
}
```

### `POST /v1/automation/webhooks/{extension_id}/{install_id}`

Receive an external webhook for a trigger node. The external service must include the `X-Webhook-Secret` header matching the stored secret.

**Auth:** `X-Webhook-Secret` header (not JWT).

**Request body:** Arbitrary JSON payload. Forwarded to the extension handler as `ctx.webhookBody`.

**Response:** 200 on success, 401 if the secret is invalid, 404 if the extension/install is not found.

> **Protocol parity:** `installedAutomationNodes` query and `automationWebhookUrl` query in GraphQL -- see [GraphQL](./graphql.md#automation-extension-nodes).

## Extension Actions

### `POST /v1/extension-installs/{install_id}/actions/{action}`

Run an action on behalf of an extension install - the backend of `useLumioAction()`. Body: `{ "params": { ... } }`. `200` carries `{ "success": true, "data": { ... } }`, or `{ "success": false, "error": "..." }` when the action itself fails. `400` for `Unknown action: …` / `Invalid params: …`, `401` `Authentication required`, `403` for every token, permission or manifest denial, `404` `Extension install not found`. Messages are character-for-character those of GraphQL.

**Auth** (identical on both protocols, one shared resolver):

| Credential | May act on |
|------------|-----------|
| Extension token (`lm_ext_*`) | Only its own install; any other id → `Extension token install_id does not match the requested install` |
| User session / personal API key | A live install of the caller's account, with `extension-store:configure` (`Missing permission: extension-store:configure`; another account's install → `Extension install belongs to a different account`; unknown or uninstalled → `Extension install not found`) |
| Overlay token (`lm_overlay_*`) | Only a live install of the token's account that an extension layer (`ext:{slug}`) of **that** overlay renders; anything else → `Extension install belongs to a different overlay` |
| Widget token (`lm_widget_*`) | Only the widget's own install; anything else → `Extension install belongs to a different widget` |
| Shared overlay link (`lm_share_*`), popout token, anything else | Never → `Authentication required` |

Overlay and widget tokens never run a `chat:*` action (`chat:send`, `chat:delete`, `chat:ban`, … and any future `chat:` action): their links are permanent and leak through stream captures and shared screenshots, and a chat action runs as the account's bot. Such a call is refused with `403` before the install is looked up: `Permission denied: chat actions require a signed-in session, not an overlay or widget token`. Spotify, OBS and the other actions stay available to them. Chat actions need a user session, an API key or the extension token.

The extension identity is always read from the token or the install row, never from the request. The install's manifest must then declare the permission the action needs (`Permission denied: Extension does not declare the required permission: …`). Feature: `feature:extensions`. Actions run on behalf of the install. Only the chat moderation actions `chat:delete`, `chat:ban`, `chat:unban` and `chat:timeout` emit an audit event (`account:extension_moderation`, see [Audit Log](../features/audit-log.md)); every other action emits none.

> **Protocol parity:** GraphQL `executeExtensionAction` - see [GraphQL](./graphql.md#extension-actions).

## Shopify

The account connection routes need `integration:shopify` plus the listed permission; hiding a stored order name needs `events:edit` without the plan flag. GraphQL twins in [GraphQL → Shopify](./graphql.md#shopify) use the same guards, fields and messages. Link flow, errors and storage: [Shopify](/features/shopify).

| Method | Path | Permission | Notes |
|--------|------|-----------|-------|
| `GET` | `/v1/connections/shopify` | `connections:read` | `{ configured, app_store_url, connection }`; `connection` is `null` or `{ shop_host, shop_name, status ("connected" \| "needs_reconnect"), customer_display, show_items, show_price, scopes, enabled, connected_at }`. Never a token |
| `POST` | `/v1/connections/shopify/link/inspect` | `connections:create`, interactive session | Body `{ "handle": "<link handle>" }`; returns `{ shop_host, state ("pending" \| "confirmed") }`, the store a link request comes from. `409` when another user already confirmed it: the request is then deleted and must be started again in Shopify; `422` when the request has expired |
| `POST` | `/v1/connections/shopify/link/confirm` | `connections:create`, interactive session | Body `{ "handle": "<link handle>" }`; binds the request to the active account (`{ shop_host, state: "confirmed" }`). Refuses a browser request whose `Sec-Fetch-Site` is not `same-origin` (`403`). `409` when the store belongs to another account, the account holds another store, the request is being completed, or it was confirmed for another account (it is then deleted and must be started again in Shopify); `422` when expired; `429` after 10 per user in 10 min |
| `PUT` | `/v1/connections/shopify/settings` | `connections:edit` | Body `{ "customer_display"?: "none" \| "first_name" \| "first_initial" \| "first_name_last_initial" \| "custom_name", "show_items"?: bool, "show_price"?: bool }`, at least one field; returns the connection. `400` for another form or an empty body, `404` when not connected. Each changed value emits `account:shopify_settings_updated` |
| `POST` | `/v1/connections/shopify/events/{event_id}/hide-name` | `events:edit` | Body `{ "created_at": "<RFC 3339>" }` (the event's timestamp, ±1 s); removes `raw.customer_display` from the `shopify:order` / `shopify:order_paid` event and from the other event of the same order. Returns `{ hidden }` (`false` = nothing left to hide). `404` when it is not a Shopify order event of the account, `400` for an unreadable `created_at`. Not gated on `integration:shopify`. A hide emits `account:shopify_order_name_hidden` |
| `DELETE` | `/v1/connections/shopify` | `connections:delete` | `204`; clears the storefront metafields (best effort), deletes the row and writes the `app/uninstalled` tombstone. Shopify keeps sending order webhooks while the app is installed; they are dropped. `404` when not connected |

`customer_display` defaults to `none`; `show_items` defaults to `true` and `show_price` to `false`. These settings affect orders received after the update. When items are off, order event `raw` has no `line_items`; when price is off, it has no `total_price`, `currency` or item `price`. Absent details do not reach automations or widgets. The handle travels in the request body, never in a URL.

### Embedded app (`/v1/shopify/embedded/*`)

The endpoints the embedded Shopify app (inside the Shopify admin) calls through its own server. **Auth: Shopify ID token** — the App Bridge session token as `Authorization: Bearer <JWT>` (OpenAPI scheme `shopify_id_token`). HS256 with the app's client secret (or `client_secret_previous` during a rotation), `aud` = the client id, `exp`/`nbf` checked with 5 s leeway, `iss`/`dest` must name the same `*.myshopify.com` store, and `sub` (the staff member) is required. A Lumio token (`lm_*`, JWT or API key) is refused here, and an ID token is refused everywhere else. The store comes **only** from the token's `dest`; no route takes a store or an account id. A linked store acts on its own account's Shopify connection and nothing else, with no Lumio permission check (any staff member with app access).

Every refused token, and a token exchange Shopify answers with `400`, is `401` with `X-Shopify-Retry-Invalid-Session-Request: 1` and the body `invalid session`, so App Bridge fetches a fresh token and retries once. **REST-only:** the caller is not a Lumio principal, so there is no GraphQL twin.

| Method | Path | Notes |
|--------|------|-------|
| `GET` | `/v1/shopify/embedded/status` | `{ linked, account_name, connection }`; `account_name` is the linked account's display name (the only account data), `connection` as above or `null`. Also renews a dead token by token exchange and re-pushes lagging storefront metafields |
| `POST` | `/v1/shopify/embedded/link` | Starts a link: `{ handle, url, expires_in: 600 }`; `url` is the Lumio page with the handle in its fragment (`…/connections/shopify#link=<handle>`). A new request replaces the store's open one. `409` when the store is already linked; `429` after 5 per store in 10 min |
| `GET` | `/v1/shopify/embedded/link/{handle}` | `{ state ("pending" \| "confirmed" \| "completing"), account_name, confirmed_by }` — once confirmed, the Lumio account and user. Reads only. `422` when expired or not this store's |
| `DELETE` | `/v1/shopify/embedded/link/{handle}` | `204`; cancels the request (also when it no longer exists). `409` while it is being completed |
| `POST` | `/v1/shopify/embedded/link/complete` | Body `{ "handle" }`; completes a confirmed request with the token exchange and returns the connection. Only the staff member who started it (`sub`). `409` when not confirmed yet, being completed, or the store/account is taken; `403` for another staff member or a plan without Shopify; `422` when expired; `429` after 10 per store per minute. A failure leaves the request confirmed, so a retry works. Emits `account:integration_connected` and notifies the owner and the confirming user |
| `PUT` | `/v1/shopify/embedded/settings` | Body as `PUT /v1/connections/shopify/settings`, same validation and messages; `404` when not linked. Emits `account:shopify_settings_updated` (`source: shopify_admin`) per changed value and sends the account owner an in-app notice |
| `POST` | `/v1/shopify/embedded/disconnect` | `204`; as `DELETE /v1/connections/shopify`, audit `reason: shopify_admin`, in-app notice to the account owner. `404` when not linked |

Reads and writes of the embedded routes are limited to 120 per store per minute.

Shopify's mandatory compliance webhooks (`customers/data_request`, `customers/redact`, `shop/redact`) arrive at the public `POST /v1/webhooks/shopify/compliance` (signed with the app secret; `401` on a bad `hmac`, `200` once queued). They have no GraphQL twin: Shopify calls them, not a client. See [Webhooks → Shopify compliance topics](/features/webhooks#shopify-compliance-topics).

## Discord Bot Connections

`GET /v1/bot-connections/discord/authorize` returns a Discord invite URL for the one global Lumio bot. It requires an interactive session, the active account's `bot-connections:create` permission, and `feature:bots`. The invite uses scopes `bot applications.commands identify`, `integration_type=0`, and targeted permissions. The browser returns to `/api/connections/oauth/discord/callback`; the unified exchange verifies the code and uses the server ID in Discord's token response, not an untrusted browser parameter. `POST /v1/bot-connections/discord/exchange` rejects Discord because that legacy exchange handles account-source bot OAuth only.

`GET /v1/discord-guilds` requires `bot-connections:read` and lists the active account's servers. Each row includes `bot_removed` and `missing_permissions` booleans. `DELETE /v1/discord-guilds/{guild_id}` requires `bot-connections:delete`, removes that account's server mapping and settings, and returns `{"success":true}` when a row was deleted. The GraphQL twins use the same guards for authorize, list and disconnect. See [Bot Connections](/features/bot-connections#discord-servers).

## Login Assignments

Login assignments link a user's assignable login connection (e.g. their Twitch login) to a specific Lumio account. A single user can own multiple accounts; login assignments control which platform identity is associated with which account. Discord is sign-in-only and cannot be assigned.

> **Own assignments are always allowed without permissions.** The `login-assignments:*` permissions only apply when managing another user's assignments.

> **Which account the write targets.** The create and delete endpoints take an optional `account_id` and fall back to the caller's **active** account when it is omitted — so a user-centric surface such as the Profile page must always send the account the user picked, never rely on the account switcher. A supplied `account_id` must be an account the caller belongs to: acting on one's **own** login connection, any account in the caller's membership list is accepted; acting on **another user's** connection (`user_id` supplied) the target is pinned to the active account, because `login-assignments:*` is resolved against the active account's roles. Anything else is rejected with `403` and `You do not have access to the target account`.

### `GET /v1/accounts/login-assignments`

Returns all login assignments for the caller's active account.

**Permission:** `login-assignments:read` (or own account - no permission required for the account owner).

**Response:**

```json
{
  "data": [
    {
      "provider": "twitch",
      "login_connection_id": "00000000-0000-0000-0000-000000000001",
      "user_id": "00000000-0000-0000-0000-000000000002",
      "assigned_at": "2026-01-15T10:00:00Z"
    }
  ]
}
```

### `POST /v1/accounts/login-assignments`

Assign a login connection to an account.

**Permission:** `login-assignments:create` (or own account).

**Request body:**

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `login_connection_id` | UUID | Yes | ID of the login connection to assign |
| `provider` | string | Yes | Platform slug, e.g. `"twitch"`, `"google"` |
| `user_id` | UUID | No | Defaults to the authenticated user |
| `account_id` | UUID | No | Target account. Defaults to the active account |

**Response:** 200 with the created or updated assignment object.

**Audit:** emits `account:login_connection_assigned` (Account scope) with `provider`, `target_user_id` and `connection_id`.

**Discord:** if either the requested provider or the stored connection's provider is Discord, the API rejects the assignment with `400` and `This sign-in method is login-only and cannot be assigned to a channel`. GraphQL `assignLoginConnection` uses the same check and message.

### `DELETE /v1/accounts/login-assignments/:provider`

Remove the login assignment for a given provider from an account.

**Permission:** `login-assignments:delete` (or own account).

**Path parameter:** `:provider` - platform slug (e.g. `twitch`, `google`).

**Query parameters:** `user_id` (UUID, defaults to the caller), `account_id` (UUID, defaults to the active account).

**Response:** 200 with `{"data":{"success":true}}`.

**Audit:** emits `account:login_connection_removed` (Account scope) when a row was actually removed.

### `DELETE /v1/login-connections/:id`

Delete a login connection by its UUID. The connection must belong to the authenticated user.

**Permission:** None (own connections only).

**Path parameter:** `:id` - UUID of the login connection.

**Step-up:** after the "last sign-in method" check, the calling session needs a step-up in the last 10 minutes; otherwise `403` with code `STEP_UP_REQUIRED` ("Please confirm that it's you first") and nothing is deleted. Same code and message as GraphQL `disconnectLoginConnection`. `POST /v1/auth/link` (a new link, not a reconnect of the same connection), `POST /v1/users/me/mfa/setup` and `POST /v1/users/me/mfa/enable` need the same step-up. See [Authentication → Step-up before sign-in changes](../features/auth.md#step-up-before-sign-in-changes).

**Response:** 204 No Content.

> **Session-only (ZAF-1742):** the create, delete and login-connection delete endpoints require an interactive sign-in session - a user's own API key is refused with `403 This action requires an interactive sign-in session`. The two list endpoints keep the first-party gate. See [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces).

> **Protocol parity:** All four endpoints have matching GraphQL operations - see [GraphQL](./graphql.md#login-assignments).

## Feature Flags & Status

### `GET /users/me`

Returns the authenticated user's profile, account memberships, permissions, feature statuses, login connections, and preferences.

The response includes `streamer_mode` (boolean) - the user's Streamer Mode preference. Use `PATCH /users/me` with `{ "streamer_mode": true }` to toggle it.

The `UserResponse` also includes `admin_permissions` (admin-scope permission strings), `admin_mfa_required` (boolean - `true` when the user holds admin grants but has no 2FA factor, so admin endpoints answer `403 ADMIN_MFA_REQUIRED`; GraphQL twin `MeResult.adminMfaRequired`), `user_permissions` (user-scoped, cross-account non-admin permission strings - e.g. Ideas Hub `ideas:moderate_*`; the exact set the backend enforces via `AuthContext::require_user_permission`, and the GraphQL twin of `MeResult.userPermissions`), `enabled_features` (list of enabled feature keys for the active account), `login_connections` (OAuth login identities linked to the user, filtered by enabled providers), `is_developer` (boolean - `true` when the user has a developer profile or the `extension_dev_mode` admin override), and `extension_dev_mode` (boolean - when `true`, extension bundle serving loads the latest draft/testing version instead of the published version for extensions the user develops).

The `UserResponse` also carries the user-global **display preferences** (all `string`, stored on `users`):

| Field | Values | Meaning |
|-------|--------|---------|
| `locale` | `auto` · `en` · `de` | UI language; `auto` uses the request-time fallback (`locale` cookie if valid, otherwise default language) |
| `timezone` | `auto` or an IANA name (`Europe/Berlin`, …) | `auto` uses the browser-detected zone mirrored into `lumio-tz`; server render falls back to `UTC` until that mirror exists |
| `date_format` | `auto` · `dmy_dot` · `dmy_slash` · `mdy_slash` · `ymd_dash` | Numeric date format: automatic language-locale format, `31.12.2026`, `31/12/2026`, `12/31/2026`, or `2026-12-31` |
| `time_format` | `auto` · `h12` · `h24` | Numeric time format: automatic format-locale hour cycle, `11:30 PM`, or `23:30` |

These are the user's own preferences, applied across the webapp and every account the user can access. Set them with `PATCH /users/me`; an invalid value is rejected with `400`, never coerced back to `auto`. Changing them emits **no audit event** (a display preference is neither security- nor lifecycle-relevant).

It also carries the user-global **seasonal-look preferences** (the seasonal dashboard look, e.g. Halloween). They live on the profile so they follow the user to every device and into popouts (also inside OBS):

| Field | Type | Default | Values |
|-------|------|---------|--------|
| `season_look_enabled` | `bool` | `true` | One switch for every season |
| `season_strength` | `string` | `full` | `full` · `subtle` |
| `season_motion` | `string` | `auto` | `auto` (animations play unless the OS asks for reduced motion) · `off` |
| `season_creatures` | `object` | `{}` | `{ "<creature>": bool }`; an absent key means the creature's registry default (spider off, bat on). Keys `[a-z_]{1,32}`, at most 32 entries |
| `season_banner_dismissed` | `string[]` | `[]` | Dismissed season banners as `<seasonId>:<year>` (season id `[a-z0-9-]{1,32}`, the year the season window starts in), oldest first |

GraphQL parity: `me { seasonLookEnabled seasonStrength seasonMotion seasonCreatures seasonBannerDismissed }`. No audit event on change (a display preference).

And the user-global **"Animations in Lumio"** preference, also read by popouts via [`GET /v1/auth/popout/session`](#get-v1authpopoutsession):

| Field | Type | Default | Values |
|-------|------|---------|--------|
| `motion_preference` | `string` | `system` | `system` (full motion unless the OS asks for reduced motion) · `reduced` · `off` |

There is no "always on" (the OS reduced-motion request is never overridden); it is independent of `season_motion`, and the stricter of the two applies to the seasonal decoration. GraphQL parity: `me { motionPreference }`. No audit event on change (a display preference).

The `feature_statuses` field is a merged list of account-scope feature statuses **and** the user-scope `system:account_creation` status.

```json
{
  "data": {
    "id": "...",
    "feature_statuses": [
      { "key": "feature:bots",   "enabled": true,  "reason": null },
      { "key": "feature:music",  "enabled": false, "reason": "plan_locked" },
      { "key": "system:account_creation", "enabled": true, "reason": null }
    ],
    ...
  }
}
```

The `reason` field is one of: `"global_off"`, `"plan_locked"`, `"account_override"`, `"user_override"`, or `null` (when enabled).

### `PATCH /users/me`

Updates the authenticated user's profile, active account, or preferences. All fields are optional - at least one must be provided.

> **First-party session required (ZAF-450 S1 / ZAF-469):** this endpoint - and the whole first-party user surface keyed on the acting user's own identity (`GET /users/me`, the session endpoints under `/users/me/sessions`, login-connection and login-assignment management, `PUT /users/me/name-source-connection`, the `/notifications` endpoints, `POST`/`GET /developer/application`, `POST`/`GET /developer/verification`, account create/dissolve/leave, invite accept (`POST /invites/{code}/accept`, ZAF-1740 A6), and the JWT-minting `POST /auth/ws-token`) - apply the first-party gate. It admits a logged-in user session or the user's own API key, except for the identity-changing operations and `POST /auth/ws-token` listed as session-only below. A popout/overlay/widget/extension token, whose `user_id` is bound at token-create time and could be set to the account owner, is rejected with `403 FORBIDDEN` on both REST and GraphQL. This closes the profile-edit (email → password-reset) account-takeover path, the owner-bound-JWT minting path, and the broader authorization/disclosure gap. The same first-party bar extends to the **extension-developer REST surface** keyed on the developer identity (ZAF-471): the `developer/profile`, `developer/revenue`, `developer/payout-settings`, `developer/payout-history`, `developer/limits*` reads, the `developer/payouts` (update) / `developer/payouts/request` (request) writes, extension create/submit/delete and tester invites, the developer-team endpoints, and extension-access grants/invites - all reject a popout/overlay/widget/extension token with `403 FORBIDDEN`. The payout writes require an interactive session (ZAF-1750); ownership-scoped extension operations, including the extension secret store, may also admit developer keys under their separate guard.

> **What happens to a requested payout (ZAF-1257):** the payout is `pending` and the balance is debited. The payout cycle sends Stripe and PayPal payouts within about 15 minutes (Stripe `completed`, PayPal `processing` until its webhook); SEPA payouts and payouts with an unknown provider answer are settled by an operator. Every request emits `developer:payout_requested` (user scope) on both protocols. See [Developer Payouts](../features/developer-payouts.md).

> **Payouts need a verified developer (ZAF-2804):** `POST /developer/payouts/request` answers `403 DEVELOPER_VERIFICATION_REQUIRED` ("Payouts require a verified developer identity. Complete the verification in the developer settings first") until the developer verification is `verified`; the automatic payout cycle skips unverified developers. GraphQL twin: `requestPayout`, same code and text.

> **Closing payout (ZAF-2825):** `POST /developer/payouts/request` takes an optional JSON body `{ "closing": true }`. It pays out the whole balance even below the method's minimum payout amount, but only while the user has a profile deletion scheduled (grace period running, or held by the deletion job); otherwise `409 CLOSING_PAYOUT_REQUIRES_DELETION` ("A closing payout below the minimum payout amount is only possible while a profile deletion is scheduled"). A balance of 0 still fails with the below-minimum `400`. Payout method, verified identity and the interactive session stay required. No body means a regular payout. GraphQL twin: `requestPayout(closing: true)`, same code and text.

> **Every payout carries a self-billed credit note (ZAF-2807):** `POST /developer/payouts/request` issues the payout's credit note (Gutschrift) in the same transaction. The payout `amount` is the note's gross amount: for a German developer who charges VAT, 19 % VAT is added on top of the balance (the balance is debited by the net amount). It answers `422 TAX_DETAILS_REQUIRED` while the tax details of the verification are incomplete (`Tax details required: enter your tax number (Steuernummer) or VAT ID`, `… state whether you are a small business under section 19 UStG`, `… enter your VAT ID`) and `503 CREDIT_NOTE_ISSUER_NOT_CONFIGURED` while `[billing.issuer]` is incomplete; nothing is booked in either case. See [Developer Credit Notes](#developer-credit-notes). GraphQL twin: `requestPayout`, same codes and texts.

> **Money-moving writes are session-only (ZAF-1750):** `POST /developer/stripe-connect/onboard` (creates the Stripe Connect account and so sets the payout destination), `POST /developer/payouts` (payout settings), `POST /developer/payouts/request`, and the billing `POST /billing/checkout`, `POST /billing/portal` and `POST /billing/cancel` require an **interactive sign-in session**. A user's own API key is refused with `403 This action requires an interactive sign-in session`, whatever its scopes, before any row is written or Stripe is called; every token type is refused the same way. The reads (`GET /developer/stripe-connect/status`, `developer/payout-settings`, `developer/payout-history`, `developer/revenue`, billing status and invoices) keep the first-party gate, so a scripted key can still read them. GraphQL twins identical. See [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces).

> **`email` is not settable:** the profile email is set by the email sign-in only. A request with `email` is refused for every caller with `400 EMAIL_MANAGED_BY_LOGIN` (`Set your e-mail under Security › Sign-in › E-mail & password`) before anything is written (GraphQL `updateMe` identical). With an email sign-in the profile email is always the confirmed sign-in address (`email_source: "email_login"`); without one it is a platform sign-in's address (`platform:<provider>`, filled only when empty), otherwise `null`. Removing the email sign-in brings back the platform address it replaced, or leaves none.

> **Session-only fields (ZAF-1922):** the account switch / clear (`active_account_id`, `clear_active_account`) is session-only too (ZAF-1922): both re-mint the session JWT, and a JWT is only minted for a caller that already holds a session - a user API key or a session-less JWT gets the same `403`. Every other field keeps the first-party gate above. Session-only as a whole: `POST /auth/link` (linking / reconnecting a login provider), the login-assignment create/delete, `DELETE /login-connections/{id}`, `PUT /users/me/name-source-connection`, `PATCH /users/me/display-name`, `POST`/`DELETE /users/me/avatar` (they rearrange, rename or remove the identities you log in with), the channel name/picture writes `PUT /accounts/{id}/identity-source`, `PATCH /accounts/{id}/name`, `POST`/`DELETE /accounts/{id}/avatar` (see [Channel name and picture](#channel-name-and-picture)) and `POST /auth/ws-token` (the minted JWT carries the full user permission set). See [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces).

| Field | Type | Description |
|-------|------|-------------|
| `email` | `string` | Deprecated. Always refused with `400 EMAIL_MANAGED_BY_LOGIN` |
| `active_account_id` | `UUID` | Switch active account (must be a member; interactive sign-in session only) |
| `clear_active_account` | `bool` | Clear active account (go to user-only mode; interactive sign-in session only) |
| `streamer_mode` | `bool` | Toggle Streamer Mode on/off |
| `extension_dev_mode` | `bool` | Toggle Extension Developer Mode - loads draft/testing versions in editors |
| `locale` | `string` | UI language: `auto` · `en` · `de` |
| `timezone` | `string` | `auto` or a valid IANA timezone name |
| `date_format` | `string` | `auto` · `dmy_dot` · `dmy_slash` · `mdy_slash` · `ymd_dash` |
| `time_format` | `string` | `auto` · `h12` · `h24` |
| `display_currency` | `string` | `auto`, EUR, or an ECB reference currency; `auto` resolves to EUR for German and USD otherwise |
| `season_look_enabled` | `bool` | Seasonal look on/off |
| `season_strength` | `string` | `full` · `subtle` |
| `season_motion` | `string` | `auto` · `off` |
| `season_creatures` | `object` | Replaces the creature map: `{ "<creature>": bool }`, keys `[a-z_]{1,32}`, at most 32 entries; `{}` resets every creature to its default |
| `season_banner_dismissed` | `string[]` | Replaces the dismissed-banner list: `<seasonId>:<year>` entries; duplicates are dropped and beyond 50 the oldest entries are dropped |
| `motion_preference` | `string` | "Animations in Lumio": `system` · `reduced` · `off` |

An invalid `locale`, `timezone`, `date_format`, or `time_format` is rejected with `400` (fail-closed, identical message on GraphQL and REST) - never silently coerced to `auto`. The same holds for the seasonal fields: an unknown `season_strength` / `season_motion`, a non-object or non-boolean `season_creatures`, a bad creature key, more than 32 creatures, or a malformed `season_banner_dismissed` entry returns `400` with the message the GraphQL twin returns (e.g. `Invalid season_strength 'loud': allowed values are full, subtle`). An unknown `motion_preference` likewise returns `400` with the GraphQL twin's message (`Invalid motion_preference 'auto': allowed values are system, reduced, off`).

`display_name` is **no longer accepted** here (the field was removed): the Lumio display name + avatar follow the name source. Change the source via [`PUT /users/me/name-source-connection`](#put-usersmename-source-connection); with own details, set the name via [`PATCH /users/me/display-name`](#patch-usersmedisplay-name). `GET /users/me` exposes the current source as `name_source_kind` + `name_source_connection_id`.

Response: full `UserResponse` (same shape as `GET /users/me`), including `display_currency` and resolved `effective_display_currency`. When switching accounts, a `token` field with a fresh JWT bound to the caller's session is included; a non-session caller never receives a `token`.

#### Stale-membership filtering on `active_account_id`

If the JWT carries an `accountId` the user is no longer a member of (e.g. the
account owner removed them after the token was issued), the resolver returns
`active_account_id: null` rather than the stale claim. Permissions are computed
against the corrected scope. The dashboard shell reads this signal and routes
the user to onboarding instead of rendering an account context they can no
longer access.

The REST `DELETE /v1/accounts/{id}/members/{membership_id}` (admin kick) and `POST /v1/accounts/{id}/leave` (self-leave) endpoints invalidate the Redis permission cache for the removed user, matching the existing GraphQL `removeMember` mutation behaviour - two-protocol parity for cache invalidation.

### `PUT /users/me/name-source-connection`

Chooses where the current user's Lumio display name + avatar come from (`name_source_kind` on `GET /users/me`):

- **`connection`** - mirrored on every login from a single *name-source* login connection, so a login via a secondary platform never rewrites them.
- **`own`** - the user's own details. Sign-ins never overwrite them. Set the name with [`PATCH /users/me/display-name`](#patch-usersmedisplay-name) and the picture with [`POST /users/me/avatar`](#post-usersmeavatar).

Session-only (ZAF-469 / ZAF-1742): rejected with `403` for an API key or a popout/overlay/widget/extension token. GraphQL twin: `setNameSourceConnection(loginConnectionId, kind)`.

| Field | Type | Description |
|-------|------|-------------|
| `kind` | `string` / absent | `connection` (default) or `own`. Anything else returns `400 INVALID_NAME_SOURCE`. |
| `login_connection_id` | `UUID` / `null` | With `connection`: the connection to source from. `null` clears the pin, so resolution falls back to the first-ever-connected login (`created_at` ascending). Ignored with `own`. |

With `connection`, the connection must belong to the caller; a foreign or unknown id returns `400` (same message as the GraphQL twin). A profile without any platform sign-in returns `409 NO_LOGIN_CONNECTION`. The name/avatar are re-materialized immediately, and an uploaded own picture is deleted from storage. With `own`, the current name and picture stay as the starting values. Response (also returned by the display-name and avatar endpoints below):

```json
{ "data": { "display_name": "…", "avatar_url": "…", "name_source_connection_id": "…", "name_source_kind": "connection" } }
```

Audit: switching between `own` and `connection` writes `user:profile_identity_changed` (`changed: ["source"]`, plus `"avatar"` when an uploaded picture was deleted, and `source`). Choosing among one's own connections is not audited (a display preference).

### `PATCH /users/me/display-name`

Sets the own display name. Only while `name_source_kind` is `own`, otherwise `409 NAME_SOURCE_NOT_OWN`. Session-only. GraphQL twin: `updateDisplayName(displayName)`.

```json
{ "display_name": "René" }
```

The name is trimmed and NFC-normalised, then needs 2-32 characters without control or invisible characters (zero-width spaces/joiners, bidi controls, BOM). Errors: `400 DISPLAY_NAME_TOO_SHORT`, `400 DISPLAY_NAME_TOO_LONG`, `400 DISPLAY_NAME_INVALID_CHARACTERS` - the same codes and messages as on GraphQL. Writes `user:profile_identity_changed` (`changed: ["display_name"]`) when the name actually changes.

### `POST /users/me/avatar`

Uploads the own profile picture as `multipart/form-data` with one field `file`. Only while `name_source_kind` is `own`, otherwise `409 NAME_SOURCE_NOT_OWN`. Session-only.

**REST-only by design** - the picture is binary data and the API has no GraphQL file uploads. GraphQL has the counterpart `removeAvatar`, and the result shape is the same `NameSourceResponse` / `NameSourceResult`.

The server validates the file itself and never relies on the browser's crop:

| Check | Error |
|-------|-------|
| At most 5 MB | `413 AVATAR_TOO_LARGE` |
| Type by magic bytes: PNG, JPEG or WebP (no SVG, no GIF, no renamed files) | `415 AVATAR_UNSUPPORTED_TYPE` |
| At most 16 megapixels, checked from the header before decoding (decompression bombs) | `400 AVATAR_TOO_MANY_PIXELS` |
| The image decodes completely | `400 AVATAR_UNREADABLE` |
| At most 10 uploads per profile and hour (every attempt counts; counted before the body is read) | `429 RATE_LIMITED` with `retry_after_secs` |
| No `file` field | `400 AVATAR_MISSING` |
| File storage is not configured | `503 AVATAR_UNAVAILABLE` |
| All picture decode slots are taken (at most 2 profile and channel pictures are decoded at a time across the API) | `503 AVATAR_BUSY` with a `Retry-After` header and `retry_after_secs` (5 s) |

An accepted picture is turned upright (EXIF orientation), cropped to a centred square and re-encoded as **512 × 512** and **128 × 128** lossless WebP. The re-encode keeps pixels only, so EXIF, GPS, ICC and XMP metadata are gone. Both files are stored through lo-storage under `users/{user_id}/avatar/{uuid}-512.webp` and `…-128.webp`. `avatar_url` becomes `{storage.public_url}/users/{user_id}/avatar/{uuid}-512.webp`; with the default `storage.public_url` (`{api}/v1/uploads/file`) that is the [public picture route](#get-uploadsfileusersuser_idavatarfile). An earlier upload is deleted. Writes `user:profile_identity_changed` (`changed: ["avatar"]`).

### `DELETE /users/me/avatar`

Removes the own profile picture: `avatar_url` becomes `null` (initials) and an uploaded file is deleted. Only while `name_source_kind` is `own`, otherwise `409 NAME_SOURCE_NOT_OWN`. Session-only. GraphQL twin: `removeAvatar`. Writes `user:profile_identity_changed` (`changed: ["avatar"]`) when there was a picture.

The uploaded picture is part of the "user data only" GDPR export (`profile_picture.webp`) and is deleted together with the profile.

### `GET /uploads/file/users/{user_id}/avatar/{file}`

Serves an uploaded profile picture. Public, no sign-in, like platform avatars: the picture is shown to anyone who sees the profile. The path is the default `storage.public_url` (`{api}/v1/uploads/file`) plus the storage key, so the `avatar_url` of an upload lands here; the files in storage never have to be public. Not audited (read). No GraphQL twin (binary download, like the upload); GraphQL `me` and REST `GET /users/me` return the same `avatar_url`.

`{file}` is `{uuid}-512.webp` or `{uuid}-128.webp` (lower-case UUID). Only the user's **current** upload is served, never a replaced or removed one.

| Case | Response |
|------|----------|
| Current upload | `200`, `Content-Type: image/webp`, `Cache-Control: public, max-age=31536000, immutable` (the name is new per upload), `X-Content-Type-Options: nosniff`, `Content-Security-Policy: default-src 'none'; sandbox` |
| `{file}` does not match the pattern | `400 Invalid picture file name` |
| Not the user's current upload (replaced, removed, another user's id) | `404 Picture not found` |
| File storage is not configured | `503 AVATAR_UNAVAILABLE` |

### `GET /v1/accounts/{id}/enabled-features`

Returns the list of enabled feature keys for the given account. The caller's active account must match `{id}`. Works with popout-token auth (no `account:read` permission required). Excludes `system:*` flags.

**Response:**
```json
{ "data": ["feature:bots", "feature:music", "feature:connections"] }
```

### `GET /v1/accounts/{id}/feature-statuses`

Returns the full feature status list for the given account (key, enabled, reason). The caller's active account must match `{id}`. Works with popout-token auth (no `account:read` permission required). Excludes `system:*` flags.

**Response:**
```json
{
  "data": [
    { "key": "feature:bots",        "enabled": true,  "reason": null },
    { "key": "feature:music",       "enabled": false, "reason": "plan_locked" },
    { "key": "integration:shopify", "enabled": true,  "reason": null }
  ]
}
```

### `POST /v1/accounts` - account creation disabled (403)

When the `system:account_creation` flag is disabled (globally or per user), this endpoint returns:

```json
HTTP 403
{
  "error": "Account creation is currently disabled",
  "error_code": "account_creation_disabled"
}
```

This mirrors the GraphQL error `extensions.code: "ACCOUNT_CREATION_DISABLED"` with message `"Account creation is currently disabled"`.

### `POST /v1/accounts` / `DELETE /v1/accounts/:id` - `token` in the response

Account creation returns the new account plus a `token`: a fresh JWT carrying the new account, bound to the caller's existing session. Dissolution returns a fresh JWT without an account the same way. A JWT is only minted for a caller that already holds an interactive session (ZAF-1922) - for any other first-party caller (e.g. a user API key) account creation proceeds under its usual guards and `token` is `null`; dissolution refuses such a caller (step-up, below). GraphQL twins: `createAccount` (`CreateAccountResult.token` is a nullable `String`) and `dissolveAccount` (returns `{ success }`, no token).

### `DELETE /v1/accounts/:id` - step-up

After the `account:delete`, owner, active-account and `confirm_name` checks, the calling session needs a step-up in the last 10 minutes; otherwise `403` with code `STEP_UP_REQUIRED` ("Please confirm that it's you first") and nothing is deleted. Only an interactive sign-in session can hold a step-up, so a user API key, service key or popout token is refused even with `account:delete`. Same code and message as GraphQL `dissolveAccount`. See [Authentication → Step-up before sign-in changes](../features/auth.md#step-up-before-sign-in-changes).

### `POST /v1/accounts/:id/dissolution` - dissolve after a grace period

Schedules the dissolution of a channel, or dissolves it at once. Guard: `require_permission("account:delete")`, the same as GraphQL `scheduleAccountDissolution(accountId, graceDays)`. Optional body `{ "grace_days": 0 | 7 | 30 }`, default 30. The checks run in this order, with the same codes on both protocols:

| Check | Response |
|---|---|
| First-party user (popout, overlay, widget and extension tokens refused) | `403 FORBIDDEN` |
| `grace_days` is 0, 7 or 30 | `400 INVALID_GRACE` |
| `:id` is the caller's active account | `403` |
| Caller is the owner | `403` "Only the account owner can dissolve an account" |
| No dissolution already scheduled | `409 DISSOLUTION_ALREADY_SCHEDULED` |
| No running Stripe subscription that is not set to cancel at period end | `409 ACTIVE_SUBSCRIPTION` ("Cancel it in the billing settings first") |
| Step-up in the last 10 minutes (only an interactive session holds one, so user API keys are refused) | `403 STEP_UP_REQUIRED` |

Response: `{ "dissolution_scheduled_for": string | null, "dissolved": bool }`. `grace_days: 0` dissolves the channel at once through the same path as `DELETE /v1/accounts/:id` and returns `{ "dissolution_scheduled_for": null, "dissolved": true }`. A scheduled dissolution writes `account:dissolution_scheduled` and mails the owner and every other member. The account security worker sends the owner a reminder (7 days before the end of a 30-day period, 1 day before the end of a 7-day period) and dissolves the channel when the date is reached (`account:dissolved` with `via: "scheduled"`).

### `DELETE /v1/accounts/:id/dissolution` - cancel a scheduled dissolution

Owner only, interactive session only (no user API key, no popout token), no step-up - cancelling is the safe direction. Works while the channel is suspended, up to the end of the grace period. Returns `409 PROFILE_DELETION_SCHEDULED` while the owner's own profile is scheduled for deletion (cancel the profile deletion first), `409 DISSOLUTION_IN_PROGRESS` ("The dissolution is already running") once the date has passed, and `409 NO_DISSOLUTION_SCHEDULED` when nothing is scheduled. Writes `account:dissolution_cancelled` and mails the owner and the other members. GraphQL: `cancelAccountDissolution(accountId)`.

`DELETE /v1/accounts/:id` (immediate dissolve) refuses with `409 ACTIVE_SUBSCRIPTION` too; that check runs before the step-up.

### Channel name and picture

A channel's name and picture come from one **source**: `connection` (one of the channel's own Twitch, YouTube or Kick channel connections - never Spotify - whose channel name and platform profile picture are used) or `own` (an editable name and an optional uploaded picture; without one, `avatar_url` is `null` and the initial is shown). New channels start with `own`. Background: [Accounts › Channel name and picture](../features/accounts.md#channel-name-and-picture).

`identity` on `GET /v1/accounts/{id}`, `POST /v1/accounts` and every `accounts[]` entry of `GET /v1/users/me` (`AccountIdentityResponse`), also the response of the four writes below:

```json
{ "source_kind": "connection", "source_connection_id": "…", "source_platform": "twitch", "name": "…", "avatar_url": "https://static-cdn.jtvnw.net/…" }
```

**Guard (all four writes):** `require_permission("account:edit")` (owner and administrator by default), an interactive sign-in session (a user API key or popout token gets `403 This action requires an interactive sign-in session`), and the path `{id}` must be the session's active channel (`403 Account id does not match the active account`). While the channel is scheduled for dissolution the refusal is `403 CHANNEL_DISSOLVING`. GraphQL twins use the same guard, validation and error codes.

**Audit:** an effective change writes `account:identity_changed` (scope `account`, actor = caller) with metadata `changed` (list of `source`, `name`, `avatar`), `source_kind` and `source_platform` - never a name or URL. Nothing is written when nothing changed.

#### `PUT /v1/accounts/{id}/identity-source`

Chooses the source. GraphQL twin: `setAccountIdentitySource(accountId, kind, connectionId)`.

```json
{ "kind": "connection", "connection_id": "uuid-of-channel-connection" }
```

| Case | Error |
|------|-------|
| `kind` is not `connection` / `own`, `connection` without `connection_id`, `own` with a `connection_id`, or a Spotify connection | `400 INVALID_SOURCE` |
| The connection does not exist or belongs to another channel | `404 Connection not found` |

Switching to `own` keeps the current name as the starting value; the picture starts as the initial. Switching back to a connection deletes an uploaded picture (`changed: ["source", "avatar"]`). While a connection is the source, the channel's stored name mirrors its channel name.

#### `PATCH /v1/accounts/{id}/name`

Sets the own channel name. Only with source `own`, otherwise `409 SOURCE_NOT_OWN`. GraphQL twin: `updateAccountName(accountId, name)`.

```json
{ "name": "My Channel" }
```

The name is trimmed and NFC-normalised, then needs 2-50 characters without control or invisible characters: `400 NAME_TOO_SHORT`, `400 NAME_TOO_LONG`, `400 NAME_INVALID_CHARACTERS`.

#### `POST /v1/accounts/{id}/avatar`

Uploads the own channel picture as `multipart/form-data` with one field `file`. Only with source `own`, otherwise `409 SOURCE_NOT_OWN`. **REST-only by design** (no GraphQL file uploads); the GraphQL counterpart is `removeAccountAvatar`. Same pipeline as [`POST /users/me/avatar`](#post-usersmeavatar):

| Check | Error |
|-------|-------|
| At most 5 MB | `413 AVATAR_TOO_LARGE` |
| Type by magic bytes: PNG, JPEG or WebP | `415 AVATAR_UNSUPPORTED_TYPE` |
| At most 16 megapixels | `400 AVATAR_TOO_MANY_PIXELS` |
| The image decodes completely | `400 AVATAR_UNREADABLE` |
| At most 10 uploads per channel and hour (every attempt counts; counted before the body is read) | `429 RATE_LIMITED` with `retry_after_secs` |
| No `file` field | `400 AVATAR_MISSING` |
| File storage is not configured | `503 AVATAR_UNAVAILABLE` |
| All picture decode slots are taken (at most 2 profile and channel pictures are decoded at a time across the API) | `503 AVATAR_BUSY` with a `Retry-After` header and `retry_after_secs` (5 s) |

An accepted picture is re-encoded as **512 × 512** and **128 × 128** WebP without metadata and stored through lo-storage under `accounts/{id}/avatar/{uuid}-512.webp` and `…-128.webp`. `avatar_url` becomes `{storage.public_url}/accounts/{id}/avatar/{uuid}-512.webp`. An earlier upload is deleted.

#### `DELETE /v1/accounts/{id}/avatar`

Removes the own channel picture (`avatar_url` becomes `null`, the initial is shown) and deletes the files. Only with source `own`, otherwise `409 SOURCE_NOT_OWN`. GraphQL twin: `removeAccountAvatar(accountId)`.

#### `GET /v1/uploads/file/accounts/{id}/avatar/{file}`

Serves an uploaded channel picture. Public, no sign-in: the picture is shown wherever the channel is. The files in storage are never public. Not audited (read). No GraphQL twin (binary download).

`{file}` is `{uuid}-512.webp` or `{uuid}-128.webp`. Only the channel's **current** upload is served, never a replaced or removed one.

| Case | Response |
|------|----------|
| Current upload | `200`, `Content-Type: image/webp`, `Cache-Control: public, max-age=31536000, immutable`, `X-Content-Type-Options: nosniff`, `Content-Security-Policy: default-src 'none'; sandbox` |
| `{file}` does not match the pattern | `400 Invalid picture file name` |
| Not the channel's current upload | `404 Picture not found` |
| File storage is not configured | `503 AVATAR_UNAVAILABLE` |

Disconnecting the channel connection that is the source switches the channel to `own` with the connection's last channel name and the initial; the owner gets an in-app notification (`channel_identity_source_removed`). Dissolving the channel or deleting it from the admin app deletes the uploaded files.

### Channels being dissolved

While a channel has `dissolution_scheduled_for` set, one check in the API auth middleware, right after the credential is resolved, suspends it:

- **Credentials bound to the channel** - user API keys (`lm_usr_`), service keys (`lm_svc_`), popout tokens, overlay (`lm_overlay_`), shared overlay (`lm_share_`), widget (`lm_widget_`) and extension (`lm_ext_`) tokens - are refused:

  ```json
  HTTP 403
  {
    "error": "CHANNEL_DISSOLVING",
    "message": "This channel is being dissolved. Only cancelling the dissolution is possible",
    "details": { "dissolution_scheduled_for": "2026-11-08T03:00:00Z" }
  }
  ```

  They are not revoked and work again after the dissolution is cancelled.
- **A member's dashboard session** keeps its identity but holds no account permission: every permission-gated route answers `403 CHANNEL_DISSOLVING`. User-level routes keep working - the profile, `GET /v1/users/me` with the account list and `dissolution_scheduled_for`, switching and leaving accounts, and the owner's `DELETE /v1/accounts/:id/dissolution`.
- **Feature flags** all resolve off for the account, which stops automations and feature-gated routes.
- **Bots** - the channel drops out of the bot channel and Discord guild lists; bots leave on their next poll and rejoin by themselves after a cancel. Bot-module and automation-node handler feeds report the account's installs as disabled.
- **Webhook ingest** (YouTube PubSubHubbub, Kick) drops deliveries for the channel.
- **Checkout** - `POST /v1/billing/checkout` answers `403 CHANNEL_DISSOLVING`.

The WebSocket upgrade is refused the same way; see [WebSocket](./websocket.md).

### `PATCH /v1/admin/users/{id}` - account creation override

The request body accepts an optional `account_creation_override` field:

```json
{ "account_creation_override": "default" }
```

Valid values: `"default"` (inherit global flag), `"allow"` (always permitted), `"deny"` (always blocked). The override is cached in Redis and invalidated immediately on save. Requires `users:edit` admin permission.

The `account_creation_override` field is also present in `GET /v1/admin/users/{id}` and the user-list response.

### Platform-filtered connection lists

`GET /users/me/login-connections`, `GET /connections/channel`, `GET /bot-connections`, and `GET /admin/providers` filter by platform flags:

- Login connections are filtered by `platform:{x}:login` - platforms with the login sub-flag disabled are excluded.
- Channel connections are filtered by `platform:{x}:channel`.
- Bot connections are filtered by `platform:{x}:bot`.
- Admin providers exclude integration-only entries (e.g., Shopify does not appear - its flag is `integration:shopify` in the Feature Flags page, not a platform provider).

> **Protocol parity:** All endpoints above have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#feature-flags--status).

## Admin API Keys

Platform-operator management of **any** account's or user's API keys, for support and incident response. All paths are under `/v1/admin` and check **admin-scope permissions** (the `account-apikeys:*` family, `require_admin_permission`) - distinct from the account-scope `apikeys:*` a member uses on their own keys under [`/v1/api-keys`](#api-keys). `{kind}` is `personal` (`lm_usr_`, in `api_keys`) or `service` (`lm_svc_`, in `account_service_keys`). Bodies use snake_case; no response ever includes a key's secret except the one-time rotate result.

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| `GET` | `/v1/admin/accounts/{account_id}/api-keys` | `account-apikeys:read` | List an account's keys - **both** kinds (its members' personal `lm_usr_` keys and the account's `lm_svc_` service keys) |
| `GET` | `/v1/admin/users/{user_id}/api-keys` | `account-apikeys:read` | List a user's personal `lm_usr_` keys (service keys have no owning user) |
| `PATCH` | `/v1/admin/api-keys/{kind}/{id}` | `account-apikeys:edit` | Edit a key's `label` and `permissions` (scopes) |
| `POST` | `/v1/admin/api-keys/{kind}/{id}/rotate` | `account-apikeys:rotate` | Rotate a key - regenerate its secret in place; returns the new full key **once** |
| `DELETE` | `/v1/admin/api-keys/{kind}/{id}` | `account-apikeys:delete` | Revoke (delete) a key; **idempotent** - an already-gone key resolves to the same not-found result |

**Scope-edit rule.** `PATCH` validates each requested scope against the assignable-scope registry for the key's kind (ZAF-1170) - an unknown, deny-listed, or user-scoped-on-a-service-key scope is rejected. For a **personal** key the scopes are additionally capped to the key **owner's** own grantable permissions; for a **service** key the account is the principal, so the registry minus the deny-list is the ceiling. An operator can never push a key above its own principal.

**Audit.** Each write emits a **system-scope** audit event - `system:api_key_updated` (PATCH), `system:api_key_rotated` (rotate), `system:api_key_revoked` (delete) - with the operator as the actor (`user_id`) and the target `kind` / `api_key_id` / `account_id` / (personal only) `user_id` in metadata; rotate/update additionally carry `old_key_prefix`+`new_key_prefix` / `permissions`. These rows land only in the operator log, never in the target account's or user's own audit log. Parity with the GraphQL `adminAccountApiKeys` / `adminUserApiKeys` queries and `adminUpdateApiKey` / `adminRotateApiKey` / `adminDeleteApiKey` mutations - see [GraphQL](./graphql.md#admin-api-key-management).

## Admin Account Membership

These endpoints check admin-scope permissions and mirror `adminAccountRoles` and `adminAddAccountMember` in GraphQL.

### `GET /v1/admin/accounts/{id}/roles`

Requires `accounts:read`. Returns the account's roles in `sort_order` order in the standard `data` envelope; each item has `id`, `slug`, `name`, nullable `color`, `is_system`, `is_default`, and `sort_order`. Returns 404 `"Not found: Account not found"` for an unknown account. The API includes the Owner role; the admin dialog excludes it from its choices.

### `POST /v1/admin/accounts/{id}/members`

Requires `accounts:edit`. The JSON body requires both `user_id` and `role_id`:

```json
{ "user_id": "<user-uuid>", "role_id": "<role-uuid>" }
```

The role must belong to the target account. Missing fields fail request validation (400); an unknown role or one belonging to another account returns 404 `"Not found: Role not found for this account"`. On success, returns the updated account detail and emits `system:account_member_added` with the selected `role_id`; adding a user who is already a member changes nothing and emits no event.

## Admin Account Limits

`PUT /v1/admin/accounts/{id}/limits` requires `accounts:edit`. Its optional `chat_retention_days` override must be 0–1095 days; values outside that range return 400 with `"chat_retention_days must be between 0 and 1095 days (the published maximum)"`. Omit the field to keep the existing override. `GET /v1/admin/accounts/{id}/limits` requires `accounts:read`. The retention sweeps use the account override when set, otherwise the plan value.

## Admin Role Management

All endpoints below are under the `/v1/admin` scope and check **admin-scope permissions** (not account permissions). The caller must have the admin permission listed for each endpoint.

### `GET /v1/admin/admin-roles`

Requires `admin-roles:read`. Returns `[AdminRoleResponse]` - the full list of admin roles with their permissions and member counts.

### `POST /v1/admin/admin-roles`

Requires `admin-roles:create`. Body: `CreateAdminRoleRequest`. Returns 201 + `AdminRoleResponse`.

Validation errors (400):
- `"Name is required"` - empty name
- `"Name must be 100 characters or less"` - name too long
- `"Invalid permission: <perm>"` - unknown permission string
- `"Role name already in use"` - duplicate name

`admin:access` is auto-injected if not included in the permissions list.

### `GET /v1/admin/admin-roles/{id}`

Requires `admin-roles:read`. Returns `AdminRoleResponse`. Returns 404 `"Admin role not found"` if not found.

### `PATCH /v1/admin/admin-roles/{id}`

Requires `admin-roles:edit`. Body: `UpdateAdminRoleRequest` (all fields optional). Returns `AdminRoleResponse`.

- Omit a field to leave it unchanged
- Set `description` to `null` to clear it
- Permissions are applied as a diff; unknown/legacy permissions are preserved
- Same validation error wording as `POST`

### `DELETE /v1/admin/admin-roles/{id}`

Requires `admin-roles:delete`. Returns 204 on success.

- 400 `"Cannot delete system admin role"` - if `is_system = true`
- 404 `"Admin role not found"` - if not found

### `GET /v1/admin/admin-roles/{id}/members`

Requires `admin-roles:read`. Returns `[AdminRoleMemberResponse]` - all users assigned to the role.

### `PUT /v1/admin/admin-roles/{id}/members/{userId}`

Requires `admin-roles:edit`. Assigns the given user to the role. Idempotent. Returns 204.

- 404 `"Admin role not found"` - if the role does not exist

### `DELETE /v1/admin/admin-roles/{id}/members/{userId}`

Requires `admin-roles:edit`. Removes the user's role assignment. Returns 204.

### `GET /v1/admin/admin-permissions`

Requires `admin-roles:read`. Returns `[AdminPermissionInfoResponse]` - the full catalog of admin-scope permissions with category labels. Source: `lo_auth::rbac::all_admin_permissions()`.

### `GET /v1/admin/system-key-permissions`

Requires `system-keys:read`. Returns `[AdminPermissionInfoResponse]` - every scope assignable to a [System key](../admin/system-keys.md), each with its category. Source: `lo_auth::rbac::system_key::get_assignable_permission_infos()` - the derived registry (admin ∪ account ∪ user minus the credential-minting / tenant-destruction deny-list, ZAF-1213). This is the same registry `POST /v1/admin/system-keys` validates against, so the create picker can never drift from what the mint accepts. Guarded on `system-keys:read` (not `admin-roles:read`), so the operator who mints keys can read it. Parity: GraphQL `adminSystemKeyPermissions`.

### Request / Response Types

**`CreateAdminRoleRequest`**

| Field | Type | Required |
|-------|------|----------|
| `name` | `string` | Yes |
| `description` | `string \| null` | No |
| `permissions` | `string[]` | Yes (may be empty) |

**`UpdateAdminRoleRequest`**

| Field | Type | Notes |
|-------|------|-------|
| `name` | `string` | Optional; trimmed |
| `description` | `string \| null` | `null` = clear; omit = leave unchanged |
| `permissions` | `string[]` | Optional; replaces via diff |

**`AdminRoleResponse`**

| Field | Type |
|-------|------|
| `id` | UUID |
| `name` | string |
| `description` | string or null |
| `is_system` | boolean |
| `permissions` | string[] |
| `member_count` | integer |
| `created_at` | ISO-8601 string |
| `updated_at` | ISO-8601 string |

**`AdminRoleMemberResponse`**

| Field | Type |
|-------|------|
| `user_id` | UUID |
| `display_name` | string |
| `email` | string or null |
| `avatar_url` | string or null |
| `assigned_at` | ISO-8601 string |

**`AdminPermissionInfoResponse`**

| Field | Type |
|-------|------|
| `permission` | string |
| `category` | string |

> **Protocol parity:** All 9 endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#admin-role-management).

## Admin Plan Management

All endpoints below are under the `/v1/admin` scope and check **admin-scope permissions**. Request and response bodies use snake_case.

Reading the plan list is GraphQL-only - use the `adminPlans` query. There is no `GET /v1/admin/plans`; the REST surface covers create, update, delete, and the feature mapping.

### `POST /v1/admin/plans`

Requires `plans:create`. Body: `CreatePlanRequest`. Returns 201 + `AdminPlanResponse`.

Validation errors (400):
- `"Invalid slug format"` - slug does not match `^[a-z0-9]+(?:-[a-z0-9]+)*$` or is outside 2–40 chars
- `"Price cannot be negative"` - monthly or yearly price is negative
- `"Limit cannot be negative"` - a numeric limit is negative
- `"chat_retention_days must be between 0 and 1095 days (the published maximum)"` - retention is outside the published range

Conflict errors (409):
- `"Plan slug already in use"` - another plan already uses this slug

Auth errors: `401 UNAUTHORIZED` for a missing or invalid JWT; `403 FORBIDDEN` (`Missing permission: plans:create`) when the admin role lacks `plans:create`.

Fields of `CreatePlanRequest`:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `slug` | `string` | Yes | Regex `^[a-z0-9]+(?:-[a-z0-9]+)*$`, length 2–40, immutable after creation |
| `name` | `string` | Yes | Display name |
| `description` | `string \| null` | No | |
| `price_monthly` | `integer` | Yes | Cents (or the minor unit of `currency`) |
| `price_yearly` | `integer` | Yes | Cents |
| `currency` | `string \| null` | No | ISO-4217 code; defaults to `"USD"` |
| `is_public` | `boolean` | Yes | Whether the plan is visible on the public pricing page |
| `sort_order` | `integer` | Yes | Sort position in pricing pages |
| `max_overlays` | `integer` | Yes | |
| `max_storage_bytes` | `integer` | Yes | |
| `max_upload_size_bytes` | `integer` | Yes | |
| `max_integrations` | `integer` | Yes | |
| `chat_retention_days` | `integer` | Yes | 0–1095 days. `0` keeps chat and events indefinitely; chatter and moderation data are still deleted after 1095 days. A value outside this range returns 400. |
| `max_sounds` | `integer` | Yes | Maximum number of sounds per account |
| `max_sound_file_size` | `integer` | Yes | Maximum size per sound file in bytes |
| `max_sound_storage_bytes` | `integer` | Yes | Total sound storage quota in bytes |
| `max_setting_presets` | `integer` | Yes | Setting-preset quota across all kinds; `0` = unlimited (defaults: Free 5, Pro 20) |
| `stripe_product_id` | `string \| null` | No | Paste from Stripe dashboard |
| `stripe_monthly_price_id` | `string \| null` | No | Paste from Stripe dashboard |
| `stripe_yearly_price_id` | `string \| null` | No | Paste from Stripe dashboard |

### `PATCH /v1/admin/plans/{id}`

Requires `plans:edit`. Body: `UpdatePlanRequest`. Returns 200 + `AdminPlanResponse`.

- The `slug` is **immutable** and is therefore not part of `UpdatePlanRequest`.
- All fields are required on update - the handler rewrites the full editable field set.
- On success, the feature cache is invalidated for every account currently on the plan.

Errors:
- 400 `"Price cannot be negative"` / `"Limit cannot be negative"` / `"chat_retention_days must be between 0 and 1095 days (the published maximum)"` - validation failures
- 403 `FORBIDDEN` - missing `plans:edit` (`Missing permission: plans:edit`)
- 404 `"Plan not found"` - no plan with that ID

Fields of `UpdatePlanRequest`:

| Field | Type | Notes |
|-------|------|-------|
| `name` | `string` | |
| `description` | `string \| null` | |
| `price_monthly` | `integer` | |
| `price_yearly` | `integer` | |
| `currency` | `string` | |
| `is_public` | `boolean` | |
| `sort_order` | `integer` | |
| `max_overlays` | `integer` | |
| `max_storage_bytes` | `integer` | |
| `max_upload_size_bytes` | `integer` | |
| `max_integrations` | `integer` | |
| `chat_retention_days` | `integer` | 0–1095 days; outside this range returns 400. `0` keeps chat and events indefinitely, while chatter and moderation data have a 1095-day ceiling. |
| `max_sounds` | `integer` | |
| `max_sound_file_size` | `integer` | |
| `max_sound_storage_bytes` | `integer` | |
| `stripe_product_id` | `string \| null` | |
| `stripe_monthly_price_id` | `string \| null` | |
| `stripe_yearly_price_id` | `string \| null` | |

### `DELETE /v1/admin/plans/{id}`

Requires `plans:delete`. Returns 204 No Content on success.

- 403 `FORBIDDEN` - missing `plans:delete` (`Missing permission: plans:delete`)
- 404 `"Plan not found"` - no plan with that ID
- 409 `"Cannot delete plan: N account(s) still reference it. Migrate them to a different plan first."` - one or more accounts still point at this plan; migrate them before retrying

Deletion cascades to `plan_features` via the foreign key constraint. No other data is affected.

### Request / Response Types

**`AdminPlanResponse`**

| Field | Type |
|-------|------|
| `id` | UUID |
| `slug` | string |
| `name` | string |
| `description` | string or null |
| `price_monthly` | integer |
| `price_yearly` | integer |
| `currency` | string |
| `is_public` | boolean |
| `sort_order` | integer |
| `max_overlays` | integer |
| `max_storage_bytes` | integer |
| `max_upload_size_bytes` | integer |
| `max_integrations` | integer |
| `chat_retention_days` | integer |
| `max_sounds` | integer |
| `max_sound_file_size` | integer |
| `max_sound_storage_bytes` | integer |
| `max_setting_presets` | integer |
| `stripe_product_id` | string or null |
| `stripe_monthly_price_id` | string or null |
| `stripe_yearly_price_id` | string or null |
| `features` | `[AdminPlanFeatureResponse]` |
| `accounts_using` | integer |

**`AdminPlanFeatureResponse`**

| Field | Type |
|-------|------|
| `feature_id` | UUID |
| `feature_key` | string |
| `label` | string |
| `enabled` | boolean |

> **Protocol parity:** The three write endpoints have matching GraphQL mutations, plus `PUT /v1/admin/plans/{id}/features` for the feature mapping; the plan list is GraphQL-only (`adminPlans`) - see [GraphQL](./graphql.md#plan-management).

## Admin - Setting Presets

Operator view/delete of a user's setting presets (ZAF-1282; see [Setting Presets](../features/setting-presets.md#deleting-presets-as-an-operator)). Presets are user-bound, so an operator manages them by owning user; deleting one removes it for that user across every account they belong to. The `payload` is never exposed.

### `GET /v1/admin/users/{id}/setting-presets`

Requires `users:read`. Returns a list of `AdminSettingPresetResponse` (`id`, `user_id`, `kind`, `name`, `is_default`, `created_at`, `updated_at`).

### `DELETE /v1/admin/setting-presets/{id}`

Requires `users:edit`. Returns 204 No Content on success, 404 `"Setting preset not found"` if no such preset. Emits `system:user_setting_preset_deleted`.

> **Protocol parity:** Matching GraphQL `adminUserSettingPresets` (query) / `adminDeleteUserSettingPreset` (mutation) - see [GraphQL](./graphql.md#setting-presets).

## Chat History

### `GET /v1/chat/shared-chat`

Reads the account's current Twitch Shared Chat session with `chat:read` and
`feature:multichat`. A popout token with those grants can use it. The body is
snake_case `SharedChatSessionView`: `status` (`session`, `none`, `unknown`),
`revision`, `session_id`, `host_broadcaster_id`, `own_broadcaster_id`,
`started_at`, `updated_at`, `participants` and `total_viewers`. Participants
carry broadcaster identity, `joined_at`, optional viewer/category/title/
follower data and `inferred`, `is_host`, `is_own_channel`. `unknown` means the
state could not be determined and must not clear a previously known session;
its `revision` is null. A newer revision wins over an older read or WebSocket
frame. GraphQL twin: `sharedChatSession`.

Twitch announcements are chat rows with `message_type: "announcement"` and
`announcement_color: "primary" | "blue" | "green" | "orange" | "purple"`.
Other messages have `announcement_color: null`. A missing or unrecognised
announcement colour resolves to `primary`. The same fields appear in
`GET /v1/chat/history` and the message part of the merged history read.

### Current pins and pin actions

`GET /v1/chat/pins` returns `{twitch, kick, available}` for the active account.
It requires `chat:read` and `feature:multichat` and accepts a popout token.
`available: false` means the state could not be read; `null` platform pins
then mean unknown. A pin has `platform`, `channel_id`, `message_id`, `sender`,
`pinned_by`, `text`, `emotes`, `sent_at`, `starts_at`, `ends_at` and
`updated_at`. `sent_at` is the message's write time, or `null` when unknown,
not the pin time. Each person has `platform`, `user_id`, `login`,
`display_name`, `avatar_url`, `color` and `badges`.

| Method | Path | Body | Effect |
|--------|------|------|--------|
| `POST` | `/v1/chat/pins` | `platform`, `message_id`, `duration_seconds` | Pin a Twitch message, replacing the current pin. |
| `PATCH` | `/v1/chat/pins` | Same | Change the current pin's duration from now. |
| `DELETE` | `/v1/chat/pins/{platform}/{message_id}` | None | Unpin the current Twitch message. |

All actions require `chat:pin` and `feature:multichat`. The duration is
30–1,800 seconds or `null` / absent for until stream end. The caller's own
Twitch login must moderate the channel and grant
`moderator:manage:chat_messages`. Kick actions return a result with
`success: false` and `error_code: "pin_platform_unsupported"`. Every result
has `success`, `platform`, `message_id`, `action`, `error_code` and `details`.
Invalid platform, message ID or duration gives a 400; a refused platform
action is represented in the result. The GraphQL twins have the same guard,
validation and outcome fields in camelCase.

### `GET /v1/chat/history`

Returns paginated account chat history. Query parameters use snake_case and match the GraphQL `chatHistory(filter: ChatFilterInput)` surface, except that REST encodes keyword search as one comma-separated string.

| Query parameter | Type | Description |
|-----------------|------|-------------|
| `platform` | string | Optional platform filter: `twitch`, `youtube`, or `kick` |
| `platform_user_id` | string | Optional platform-native user filter |
| `live_chat_id` | string | Optional YouTube live-chat/broadcast filter |
| `from` | ISO 8601 timestamp | Optional inclusive lower time bound. When omitted, the read covers the 30 days before `to` (or now) |
| `to` | ISO 8601 timestamp | Optional inclusive upper time bound |
| `search` | comma-separated string | Optional keyword search over message text, for example `?search=hello,world`. Matching is case-insensitive and uses the same validation as GraphQL: at most 20 keywords, each at most 100 characters after trimming and dropping blanks. A keyword search always has a lower time bound: the supplied `from`, or the last 12 hours when `from` is omitted. A keyword that itself contains a comma cannot be expressed through REST; use GraphQL `ChatFilterInput.search: [String!]` for that case. |
| `page` | integer | 1-based page number, default 1 |
| `limit` | integer | Items per page, default 50, max 100 |

`_meta.total` is capped at 10 000; `_meta.total_capped: true` means more messages match (see [Response format](#response-format) for the paging rules).

Each returned message is a snake_case chat row. A reply carries the parent author under two fields: `reply_parent_username` (the **display name**) and `reply_parent_login` (the **login/handle** twin, ZAF-1452 F1) — `reply_parent_login` is `null` for platforms/messages without a distinct login (Kick's username already is the handle; YouTube carries no reply handle) and for pre-existing rows (no backfill). For a Twitch **Shared Chat** message that originated in a different channel's room, the row additionally carries `is_shared_chat: true` and `source_channel: { platform_channel_id, login, display_name, avatar_url }` (the origin channel). For normal and host-origin messages `is_shared_chat` is `false` and `source_channel` is `null`. Attribution is by channel (public broadcaster identity), never by viewer.

> **Protocol parity:** mirror at GraphQL `chatHistory(filter: ChatFilterInput)`. GraphQL accepts `ChatFilterInput.search` as a real `[String!]` list; REST accepts the same logical terms through the comma-separated `search` query parameter. The `replyParentLogin`, `isSharedChat` / `sourceChannel` fields are present on both protocols and on the `chat:message` WebSocket payload.

### `GET /v1/chat/history/merged`

Returns **one timestamp-ordered page of chat messages, platform events and Twitch AutoMod holds interleaved**, for the multichat history view. It replaces the client-side merge of the two separate `/v1/chat/history` and `/v1/events` windows (which drift on a chat-quiet, event-loud channel): messages and events for the same time span always arrive together, in `created_at` order, with nothing capped or hidden.

Pagination is **keyset**, not page/offset: pass the opaque `before` cursor from the previous response to fetch the strictly-older page. A single cursor spans both sources so the two streams can never page apart.

One request reads at most **30 days** below its cursor, or down to the account's retention cutoff when retention is enforced and shorter. The history ends 7 days before the account was created. A page can therefore be **short or empty while `has_more` is `true`**: the window was exhausted and older history still exists below it, so `next_cursor` points at the window edge. Keep paging until `has_more` is `false`; only that marks the end of the history (see [Chat → Server-merged history read](../features/chat.md#server-merged-history-read-mergedchathistory)).

| Query parameter | Type | Description |
|-----------------|------|-------------|
| `platform` | string | Optional platform-tab filter (`twitch`, `youtube`, `kick`); applied to **every** source; a non-Twitch value skips AutoMod holds |
| `live_chat_id` | string | Optional YouTube live-chat/broadcast filter; **messages only**; skips AutoMod holds |
| `type` | comma-separated string | Optional enabled event-type set (e.g. `?type=twitch:follower,kick:subscribe`); **events only**. Maps to GraphQL `types: [String!]` |
| `before` | string | Opaque keyset cursor from a prior page's `next_cursor` (or any item's `cursor`); omit for the newest page |
| `limit` | integer | Total items across all sources, default 50, max 100 |

Response body:

```jsonc
{
  "items": [
    { "kind": "message", "id": "…", "created_at": "…", "cursor": "…", "message": { /* ChatMessageResponse */ }, "event": null },
    { "kind": "event",   "id": "…", "created_at": "…", "cursor": "…", "message": null, "event": { /* EventResponse */ } },
    { "kind": "automod", "id": "…", "created_at": "…", "cursor": "…", "message": null, "event": null, "automod": { /* AutoMod log entry */ } }
  ],
  "next_cursor": "…",   // cursor for the next (older) page; null when has_more is false
  "has_more": true
}
```

Each item is tagged `kind: "message" | "event" | "automod"` and carries the full row in the matching field — `message` reuses the [`GET /v1/chat/history`](#get-v1chathistory) shape, `event` reuses the `GET /v1/events` shape (see [Events](../features/events.md)), `automod` reuses the entry shape of `GET /v1/history/reports/{id}/automod` (see [AutoMod log](../features/stream-history.md#automod-log)) (outcome `open`/`approved`/`denied`/`expired`, `resolved_via`, moderator, reason, text, `emotes`, sender look), so no field drifts from the standalone endpoints. An AutoMod item's `id` is the log row id and its `created_at` is `held_at`. Event `raw` is returned as stored on both endpoints, including the Twitch Shared Chat partner-event fields `is_shared_chat`, `source_channel` and `shared_chat_notice_type` ([Events → Twitch Shared Chat partner events](../features/events.md#twitch-shared-chat-partner-events)). A chat message sent through a channel-points reward with text input carries `message_type: "channel_points_custom_reward"`.

**Gates are server-side and independent.** Messages are included only with `feature:multichat` **and** `chat:read`; events only with `feature:events` **and** `events:read`; AutoMod holds only with `feature:multichat` **and** `chat:read` **and** `chat:automod-read` — with `history:read` across the account's full chat window, without it for the last 24 hours. The AutoMod source always applies the plan-window floor and ends the history instead of paging empty windows. A member missing a gate receives only the streams they may read — no error, no empty state; a member holding none receives an empty page. Popout tokens (`lm_pop_*`) are accepted and scoped exactly like a member; overlay, shared-overlay, widget, extension, developer and system keys and anonymous callers get no AutoMod items. A malformed `before` cursor is a `400`.

> **Protocol parity:** mirror at GraphQL `mergedChatHistory(filter: MergedChatHistoryFilterInput): ChatHistoryPage!` — identical fields, filters, independent gates, and errors. WebSocket live-append is unchanged; this is the history read path only.

## Chatter List

### `GET /v1/chat/chatters`

Who is in the chat right now, per platform — see [Chatter List](../features/chatter-list.md). Requires `chat:read` and the feature `feature:chat-viewer-list` (same guard as GraphQL `chatters` and the `chatters:{account_id}` WebSocket channel); popout tokens with `chat:read` are accepted.

| Query | Notes |
|---|---|
| `platform` | Optional, comma-separated (e.g. `twitch,kick`). Omitted = every supported platform. An unknown platform is `400 BAD_REQUEST` `Bad request: Unsupported chatter platform: <name>`. Kick without a usable channel connection is omitted even when requested explicitly |

```json
{
  "data": {
    "supported_platforms": ["twitch"],
    "platforms": [
      { "platform": "twitch", "available": true, "reason": null,
        "total": 12400, "truncated": true, "updated_at": "2026-10-02T18:00:00Z" }
    ],
    "chatters": [
      { "platform": "twitch", "user_id": "141981764", "login": "nightbot",
        "display_name": "Nightbot", "avatar_url": "https://…", "color": null,
        "role": "bot", "last_message_at": null, "present": true,
        "first_seen_at": "2026-10-02T17:12:00Z", "last_seen_at": "2026-10-02T18:00:00Z" },
      { "platform": "twitch", "user_id": "22484632", "login": "lena_plays",
        "display_name": "lena_plays", "avatar_url": null, "color": null,
        "role": "viewer", "last_message_at": null, "present": false,
        "first_seen_at": "2026-10-02T17:40:00Z", "last_seen_at": "2026-10-02T17:56:00Z" }
    ]
  },
  "links": { "self": "…/v1/chat/chatters" }
}
```

`chatters` lists present people first, then the recently-left entries (`present: false`, kept 30 min after `last_seen_at`). `first_seen_at` is when the person (re)entered the chat in the current stream; `last_seen_at` is the later of the last snapshot that listed them and their last message, frozen once they left. `total` never counts recently-left entries. See [GraphQL → Chatter List](./graphql.md#chatter-list) for the field semantics.

`supported_platforms` contains Twitch and, when the account has a usable Kick channel connection, Kick. A platform status has `available: false` with `reason: "source_unavailable"` when its list source fails. Kick’s undocumented web source can return that reason; recent writers remain listed without a reconnect. In this state `total` is `null` and `truncated` is `false`. Kick’s ordinary chatter group is otherwise capped at 100, so `truncated: true` can accompany a larger platform `total`.

Same fields as the GraphQL type (snake_case), same errors: `403` `Missing permission: chat:read`, `403` `Feature 'feature:chat-viewer-list' is not available`.

## Chat User Search

### `GET /v1/chat/users/search`

Prefix-search the account's known chatters (the `platform_users` table) by username or display name, for the multichat filter name-completion. Requires `chat:userinfo` and the `feature:multichat` feature - without `chat:userinfo` the search returns nothing, so it never leaks user data. The account is derived server-side from the token (cookie **or** popout `lm_pop_*`), never from a client parameter.

| Query parameter | Type | Description |
|-----------------|------|-------------|
| `q` | string | Case-insensitive prefix over `username` **and** `display_name`. Shorter than 2 characters (after trimming) returns an empty list, not an error. `%`, `_`, `\` match literally. |
| `platform` | comma-separated string | Optional platform filter, for example `?platform=twitch,youtube`. Omit for all platforms. Maps to GraphQL `platforms: [String!]`. |
| `limit` | integer | Optional, default 10, **hard-capped at 25**. |

Each result is the slim shape `{ platform, platform_user_id, username, display_name, avatar_url, last_seen_at, message_count }`, ordered `last_seen_at DESC, message_count DESC` (most-recently-active first).

> **Protocol parity:** mirror at GraphQL `searchPlatformUsers(query, platforms, limit)` - same fields, same validation, same empty-below-2-characters behaviour. See [GraphQL](./graphql.md#searchplatformusersquery-string-platforms-string-limit-int-gqlplatformusersearchresult) and [Chat](../features/chat.md#name-completion-searchplatformusers).

## Chat Ingest (internal)

`POST /v1/chat/message` is the bot fleet's ingest path for chat messages read from the platforms (buffer + broadcast). It is internal: it requires a System key carrying [`bots:internal`](./permissions.md#system-key-only-permissions) (non-System → `403 System access required`; System key without the grant → `403 Missing permission: bots:internal`), an explicit `account_id` in the body (`400` `account_id is required` when absent), and `feature:multichat` for that account. Tenant credentials - including a `chat:write` grant - cannot call it. GraphQL twin: `sendChatMessage(input: { accountId, … })`, same guard, validation and messages. Sending a message **to** a platform is [`POST /v1/chat/send`](#chat-send).

## Chat Send

`POST /v1/chat/send` (`chat:write` + `feature:multichat`) sends with the acting user's **personal login grant** for the platform, refreshing it through the central chokepoint if expired. The response mirrors the GraphQL `sendChatToPlatform` result 1:1 and always returns HTTP 200 for a send outcome (only a hard validation error - unsupported platform, no channel connection - is a non-200):

```jsonc
{ "sent": true,  "message_id": "abc", "platform": "youtube" }
{ "sent": false, "error_code": "login_reconnect_required", "platform": "youtube" }
{ "sent": false, "error": "…platform message…", "error_code": "send_failed", "platform": "twitch" }
```

`error_code` is machine-readable so the client renders a translated message instead of parsing `error`: `login_reconnect_required` (the sender's login grant is dead - flagged `reconnect_required`; **no** crypto/DB internals in `error`), `internal_error` (scrubbed internal failure), or `send_failed` (the platform rejected the send). GraphQL parity: `GqlSendResult.errorCode` + `platform`.

**Kick emotes on send.** For `platform: "kick"` every whitespace-separated word
that exactly matches a known Kick emote (channel, Kick `Global` and `Emojis` sets
from the emote catalog) is sent as Kick's `[emote:ID:NAME]` markup, which is the
only form Kick renders as an emote. Same conversion on GraphQL
`sendChatToPlatform` (one shared send function).

## Emotes

### `GET /v1/emotes/info`

Returns hover-card details for up to 50 emotes. This read requires authentication but no RBAC permission or plan feature. Dashboard sessions, API / service / developer keys, popout tokens and System keys may call it; overlay, shared overlay, widget and extension tokens are refused with `403` `Emote details are not available to overlay, widget or extension tokens`. `platform` is required and accepts `twitch`, `youtube`, or `kick`. `items` is a URL-encoded JSON array of objects with required `emote_id` and optional `owner_id` and `url`; omitting `items` returns an empty array.

```text
GET /v1/emotes/info?platform=youtube&items=%5B%7B%22emote_id%22%3A%22UC...%2Femote%22%2C%22url%22%3A%22https%3A%2F%2Fyt3.ggpht.com%2F...%22%7D%5D
```

The response envelope's `data` is an array in request order. Each element has `emote_id`, nullable `animated`, and nullable `owner` (`owner_id`, nullable `login`, `display_name`, nullable `avatar_url`). An unknown owner stays `null`; without an account context all owners are `null`. Twitch animation is always `null`. Kick animation is checked from a server-built `files.kick.com` URL for a numeric ID, ignoring any client URL. YouTube animation requires an HTTPS `yt3.ggpht.com` URL in the item. The server reads at most 512 KiB with a 2-second deadline and at most three same-origin redirects; an undecidable result is `null`. One request resolves at most 10 distinct owners and probes at most 10 images; items beyond those caps come back with `owner: null` / `animated: null`. Probe results are cached by the fetched image URL (hashed), not by the client's emote id - decided results for 30 days, undecidable results for one hour.

Unsupported platforms, more than 50 items, an empty or over-200-character `emote_id`, an `owner_id` over 200 characters, or a `url` over 2048 characters return a validation error. Malformed `items` JSON returns `Validation error: items must be a JSON array of {emote_id, owner_id?, url?}`. The GraphQL twin is [`emoteInfo`](./graphql.md#emoteinfo) and uses the same resolver, guard, and validation.

`GET /v1/emotes/{platform}/{channel_id}` (authenticated) and GraphQL
`emotes(platform, channelId)` (`feature:multichat` + `chat:read`) return the same
sets through one shared resolver. For `platform = kick` the response includes
Kick's native sets — one `EmoteSet` per section with `provider: "kick"` and
`section` = `channel` | `global` | `emojis` — and each Kick emote carries
`subscribers_only` (omitted when `false`). GraphQL exposes them as
`GqlEmoteSet.section` and `GqlEmote.subscribersOnly`. Kick channel emotes carry
`owner_id = "kick:<user id>"`, and the response's `owners` map (keyed by that id)
carries the channel owner's `display_name` and `avatar_url`; GraphQL returns the
same entries as `owners: [{ id, displayName, avatarUrl }]`. `owners` is `null`
when no set has an owner. See
[Emotes](../features/emotes.md#kick-native-sets).

Each emote also has nullable `owner_name` (a 7TV, FFZ, or BTTV creator name) and nullable `scope` (`channel` or `global` for a third-party set; `null` when unknown or for native sets). Their GraphQL names are `ownerName` and `scope`. Chat-message badge JSON on REST history rows can carry `image_url_hd` for Twitch's Helix 4x badge image when available; older rows and badges without that image retain `image_url` alone. The GraphQL chat row and WebSocket payload carry the same badge JSON.

## Chat Moderation

### Twitch AutoMod held messages

| Route | Permission | Response |
|-------|------------|----------|
| `GET /v1/chat/automod/held` | `chat:automod-read` | Open holds, oldest first, as `messages`; `queue_available: false` means the queue could not be read. |
| `POST /v1/chat/automod/held/{message_id}/allow` | `chat:automod-allow` | Decision result; Twitch publishes an allowed message with a new ID. |
| `POST /v1/chat/automod/held/{message_id}/deny` | `chat:automod-deny` | Decision result; Twitch drops a denied message. |

All three require `feature:multichat` and mirror `heldChatMessages`, `allowHeldChatMessage` and `denyHeldChatMessage` on GraphQL. A hold carries `platform`, `message_id`, `sender` (with optional `avatar_url`, `color` and `badges`: the sender's look at hold time from Lumio's chatter record, absent for a chatter Lumio has not seen), `text`, optional `fragments`, optional `emotes` (Twitch emotes and cheermotes in the chat-message `emotes` shape; absent or `null` when there are none or the fragments were dropped for size), `reason_kind`, `reason`, `flagged_spans`, `held_at` and optional `expires_at`. Spans use Unicode code-point offsets and an inclusive `end`. A decision uses the acting member's Twitch login and returns `success`, `message_id`, `decision`, `error_code` and `details`; a provider or queue refusal is a 200 result with `success: false`. When the acting user's stored Twitch login scopes are known and lack `moderator:manage:automod`, the decision returns `error_code: login_scope_missing` ("Your Twitch login does not grant `moderator:manage:automod`. Log in with Twitch again to allow AutoMod actions.") without a Helix call; an empty stored scope set counts as unknown and Helix decides, and a Helix 401 maps to the same code. Same on GraphQL. An unavailable queue is distinct from an empty queue. The history log uses a separate route and requires `history:read` as well.

`POST /v1/chat/moderate` is the REST counterpart of the GraphQL `moderateChat` mutation and behaves identically - same fields, same per-platform support, same `chat:clear_user` broadcast on ban/timeout. See [Chat](../features/chat.md) for the moderation-permission matrix and [GraphQL](./graphql.md#moderatechatinput-moderationinput-gqlmoderationresult) for the field semantics.

Body (snake_case):

```jsonc
{
  "action": "ban" | "timeout" | "delete",
  "platform": "twitch" | "youtube" | "kick",
  "user_id": "<platform user id>",        // required for ban / timeout
  "message_id": "<platform message id>",  // required for delete
  "duration_secs": 300,                   // required for timeout; YouTube 1..86400, Kick rounded up to minutes, max 604800 (7 days)
  "reason": "spam",                       // optional, written to moderation_log
  "live_chat_id": "<id>"                  // YouTube only, optional — auto-resolved from Redis when omitted
}
```

Provider ids (`message_id`, `user_id`, `live_chat_id`) must be 1–512 printable ASCII characters without whitespace; anything else is a validation error (`message_id contains invalid characters`, `user_id contains invalid characters`, `live_chat_id contains invalid characters`), identical on GraphQL. The server percent-encodes them (or sends them as query parameters) when building provider URLs.

Permission required matches the action: `chat:ban`, `chat:timeout`, or `chat:delete`. All three platforms support all three actions. Kick uses the official public API (`POST /public/v1/moderation/bans` for ban/timeout, `DELETE /public/v1/chat/{message_id}` for delete).

Request errors (validation, unsupported platform, non-numeric Kick `user_id`, Kick timeout above 7 days, missing login/channel connection) return the HTTP status with the standard error body. A refused action returns `200` with `data.success = false`, a readable `data.details`, and a stable `data.error_code`: `login_scope_missing`, `login_reconnect_required`, `moderation_forbidden`, `moderation_failed`, or `internal_error`. The codes are identical to GraphQL `errorCode`; see the table there for their meaning.

> **Protocol parity:** mirror at GraphQL `moderateChat(input: ModerationInput!)` - see [GraphQL](./graphql.md#chat-moderation).

## Chat Profile Refresh

### `POST /v1/chat/users/{platform}/{platform_user_id}/refresh`

Force a fresh enrichment of a platform user's profile, bypassing the normal staleness interval. Returns the refreshed profile in the same shape as `GET /v1/chat/users/{platform}/{platform_user_id}`.

**Permission:** `chat:refresh_user`

**Path parameters:**

| Parameter | Description |
|-----------|-------------|
| `platform` | Platform slug: `twitch`, `youtube`, or `kick` |
| `platform_user_id` | The platform-native user identifier |

**Responses:**

| Status | Body | Description |
|--------|------|-------------|
| `200` | Refreshed `UnifiedProfile` (snake_case) | Enrichment succeeded; profile is updated in DB and Redis |
| `429` | `{ "error": "REFRESH_COOLDOWN", "retry_after_seconds": N }` | Cooldown active; retry after `N` seconds (max 600) |

The cooldown is 10 minutes per (account, platform, user) triple, enforced via a Redis SETNX key.

Both `GET /v1/chat/users/{platform}/{platform_user_id}` and this refresh return the enrichment fields `description`, `broadcaster_type`, `is_follower`, `followed_at`, `account_created_at`, `follower_count` and `enriched_at`, all nullable. `follower_count` (integer) is the user's **own** follower count - filled on Twitch, best-effort on Kick (undocumented Kick endpoint, may be `null`), `null` on YouTube; it matches GraphQL `followerCount`.

> **Protocol parity:** mirror at GraphQL `refreshPlatformUserProfile(platform, platformUserId)` - see [GraphQL](./graphql.md#chat-moderation).

## Notifications

User-scoped in-app notifications. See [Notifications](../features/notifications.md) for the full endpoint reference.

`POST /v1/notifications/{id}/action` takes `{ "action": "accept_team_invite" }` (or another dispatched action) and returns the acted-on notification. The first-party caller must own it; no account RBAC permission is required. It executes `accept_invite` and `decline_invite` for account invites, or `accept_team_invite` and `decline_team_invite` for developer-team invites. Account acceptance joins the inviting account with the invite's role. Team acceptance joins with the team invite's role, checks `feature:extension_development`, expiry, use count and membership, and notifies the team owner. Declining an account invite deletes it when present. Declining a team invite deletes it only when it is unused and single-use; multi-use or already-used invites remain, and a missing invite is a successful no-op. The notification is marked acted on success.

Actions carrying a `url` open a page in the bell. Posting one of them, including `view_idea`, `view_developer_application`, `view_developer`, `view_extension`, or `install_extension`, returns `400 NOTIFICATION_ACTION_NAVIGATES`. The same validation and invite handling backs [`executeNotificationAction`](./graphql.md#notifications).

| HTTP status | `code` | Meaning |
|-------------|--------|---------|
| 400 | `NOTIFICATION_NO_ACTIONS` | The notification has no actions. |
| 400 | `NOTIFICATION_ACTION_NOT_AVAILABLE` | The requested action is absent from this notification. |
| 400 | `NOTIFICATION_ACTION_NAVIGATES` | The action opens a page; there is nothing to execute. |
| 400 | `NOTIFICATION_ALREADY_HANDLED` | The notification has already been acted on. |
| 400 | `NOTIFICATION_UNKNOWN_ACTION` | The action is present but has no dispatcher. |
| 400 | `INVALID_INVITE_ID` | A required invite ID is missing or invalid. |
| 400 | `INVITE_EXPIRED` / `INVITE_FULL` | The invite has expired or reached its use limit. |
| 400 / 409 | `ALREADY_MEMBER` | The caller is already in the account (400) or developer team (409). |
| 403 | `FEATURE_DISABLED` | Team invite acceptance requires `feature:extension_development`. |
| 404 | `NOTIFICATION_NOT_FOUND` | The notification does not exist or belongs to another user. |
| 404 | `INVITE_NOT_FOUND` | The invite to accept no longer exists. |
| 409 | `INVITE_NO_LONGER_VALID` | The invite became invalid during acceptance. |

The REST error body carries a plain `error` message and the stable `code`. The GraphQL twin returns the same message with `extensions.code`.

### Notification preferences

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/notifications/preferences` | Auth | List all delivery-channel preferences for the current user |
| `PATCH` | `/v1/notifications/preferences/{type}` | Auth | Set the delivery channel for a notification type |

`PATCH` body: `{ "channel": "off" | "in_app" | "email" | "in_app_email" }`. Returns 400 for unknown channel values or locked types (e.g. `invite`).

> **Protocol parity:** `notificationPreferences` query and `updateNotificationPreference` mutation in GraphQL - see [GraphQL](./graphql.md#notifications).

## Ideas Hub

Community idea board with voting, comments, moderation, categories, and tags. All endpoints require the `system:ideas_hub` feature flag to be enabled. GET endpoints are public (no auth required). Mutation endpoints require authentication and the permissions noted below.

**Field visibility.** Some fields depend on who is calling. The same rules apply to the GraphQL twins:

- `login` on an `author` or timeline `actor` is returned only to Ideas staff (`ideas:moderate_read` on the user or admin role) and to the user themself. Everyone else gets `null`, including anonymous callers and other signed-in users. The public pages and the dashboard show only `display_name` and `avatar_url`.
- In the `timeline` of `GET /v1/ideas/:id`, the `old_value` / `new_value` of `title_changed` and `description_changed` entries hold the previous and new text. Only the idea's author and Ideas staff see them. Everyone else gets `null` for both, and `action` is still returned. `status_changed` (status key) and `category_changed` (category label) values are returned to everyone, because the public timeline shows them.

### Ideas

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/ideas` | List ideas (filter, sort, paginate) | Public |
| `GET` | `/v1/ideas/:id` | Get idea with timeline | Public |
| `POST` | `/v1/ideas` | Create idea | `ideas:create` |
| `PATCH` | `/v1/ideas/:id` | Update idea | `ideas:edit` / `ideas:moderate_edit` |
| `DELETE` | `/v1/ideas/:id` | Delete idea | `ideas:delete` / `ideas:moderate_delete` |

Deleting an idea that other people commented on, or a comment that has replies, keeps it as a tombstone so the other people's posts stay. A tombstone reads as `"deleted": true` with `"author": null` and an empty `title`/`description` (idea) or `body` (comment); every live idea and comment carries `"deleted": false`. Writes to a tombstone return `409` with `Idea was deleted` or `Comment was deleted`. See [Ideas Hub → Deletion and tombstones](../features/ideas-hub.md#deletion-and-tombstones).

**Query parameters for `GET /v1/ideas`:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter by status slug |
| `category_id` | UUID | Filter by category |
| `tag_ids` | string | Comma-separated list of tag UUIDs |
| `author_id` | UUID | Filter by author |
| `search` | string | Full-text search on title and description |
| `sort` | string | `newest`, `most_voted`, `most_commented`, `recently_updated` |
| `limit` | integer | Page size |
| `offset` | integer | Page offset |

### Voting

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `POST` | `/v1/ideas/:id/vote` | Vote on an idea | `ideas:vote` |
| `DELETE` | `/v1/ideas/:id/vote` | Remove vote | `ideas:vote` |

`POST` body: `{ "vote_type": "up" | "down" }`.

### Comments

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/ideas/:id/comments` | List comments (nested) | Public |
| `POST` | `/v1/ideas/:id/comments` | Create comment | `ideas:comment_create` |
| `PATCH` | `/v1/ideas/comments/:id` | Update comment | `ideas:comment_edit` |
| `DELETE` | `/v1/ideas/comments/:id` | Delete comment | `ideas:comment_delete` / `ideas:moderate_comment` |
| `POST` | `/v1/ideas/comments/:id/vote` | Vote on a comment | `ideas:comment_vote` |
| `DELETE` | `/v1/ideas/comments/:id/vote` | Remove comment vote | `ideas:comment_vote` |

Comment voting mirrors idea voting exactly: one vote per user per comment, and voting the active direction again removes the vote (toggle-off). `POST` body: `{ "vote_type": "up" | "down" }`. Both endpoints return the updated comment with recounted `vote_count_up` / `vote_count_down` and the caller's `my_vote`. Comment listings include those three fields per comment and reply.

Comment bodies contain sanitized HTML from a rich text editor. @mentions are stored as `<span data-mention-id="UUID" class="mention">@Name</span>`.

### Participants

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/ideas/:id/participants` | List participants for @mention autocomplete | Signed-in user only (session or `lm_usr_*`; embed, popout, service, developer and system credentials get `403`) |

Returns the union of the idea author, voters, and commenters. Supports an optional `search` query parameter.

### Voters

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/ideas/:id/voters` | List voters for an idea | Public |

### Categories

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/ideas/categories` | List all categories | Public |
| `POST` | `/v1/ideas/categories` | Create category | Admin `ideas:edit` |
| `PATCH` | `/v1/ideas/categories/:id` | Update category | Admin `ideas:edit` |
| `DELETE` | `/v1/ideas/categories/:id` | Delete category | Admin `ideas:delete` |

### Tags

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/ideas/tags` | List / search tags | Public |
| `POST` | `/v1/ideas/tags` | Create tag | `ideas:create` |
| `DELETE` | `/v1/ideas/tags/:id` | Delete tag | Admin `ideas:delete` |

`GET /v1/ideas/tags` supports an optional `search` query parameter.

### Status (Moderation)

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `PATCH` | `/v1/ideas/:id/status` | Change idea status | `ideas:moderate_status` |

`PATCH` body: `{ "status": "<status_slug>" }` (e.g. `open`, `in_progress`, `done`, `declined`).

> **Protocol parity:** All endpoints above have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#ideas-hub).

## Developer Applications

Endpoints for the developer application flow. Users apply to become developers; admins review and approve or reject applications.

### `GET /v1/developer/application`

Returns the authenticated user's latest developer application.

**Auth:** JWT (user-level, no account context required).

**Response:**

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Application ID |
| `user_id` | UUID | Applicant's user ID |
| `application_type` | string | `"solo"` or `"team"` |
| `display_name` | string | Developer/team display name |
| `slug` | string | URL slug (3-50 chars, lowercase, hyphens) |
| `description` | string | Description of the developer/team |
| `motivation` | string | Why the user wants developer access |
| `what_to_build` | string | What extensions the user plans to build |
| `github_url` | string or null | GitHub profile URL |
| `website_url` | string or null | Website URL |
| `experience` | string or null | Development experience |
| `avatar_key` | string or null | Upload key for avatar image |
| `status` | string | `"pending"`, `"approved"`, or `"rejected"` |
| `review_notes` | string or null | Notes from the reviewer |
| `reviewed_by` | UUID or null | Reviewer's user ID |
| `reviewed_at` | ISO-8601 or null | Review timestamp |
| `created_at` | ISO-8601 | Submission timestamp |
| `updated_at` | ISO-8601 | Last update timestamp |

Returns 404 `"No developer application found"` if the user has not submitted an application.

### `POST /v1/developer/application`

Submit a developer application.

**Auth:** JWT (user-level).

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `application_type` | string | Yes | `"solo"` or `"team"` |
| `display_name` | string | Yes | Developer/team display name |
| `slug` | string | Yes | URL slug (3-50 chars, starts with lowercase letter, only lowercase letters, digits, hyphens) |
| `description` | string | Yes | Description |
| `motivation` | string | Yes | Why you want developer access |
| `what_to_build` | string | Yes | What you plan to build |
| `github_url` | string | No | GitHub profile URL |
| `website_url` | string | No | Website URL |
| `experience` | string | No | Development experience |

**Validation errors (400):**
- `"application_type must be 'solo' or 'team'"` - invalid type
- `"Slug must be between 3 and 50 characters"` - slug length
- `"Slug must start with a lowercase letter"` - slug format
- `"Slug must contain only lowercase letters, digits, and hyphens"` - slug characters

**Conflict errors (409):**
- `"You already have a developer profile"` - user is already a developer
- `"You already have a pending application"` - previous application still pending
- `"Slug is already taken"` - slug in use

**Response:** 201 Created with the application object.

> **Protocol parity:** `myDeveloperApplication` query and `submitDeveloperApplication` mutation in GraphQL - see [GraphQL](./graphql.md#developer-applications).

## Developer Verification (self-service)

KYC verification an **approved developer** submits about themselves (individual or company) to unlock paid-extension publishing. This is the developer-facing counterpart to the admin review endpoints under `/v1/admin/developer-verifications`.

**Auth:** first-party user session or the user's own API key. A popout/overlay/widget/extension token is rejected with `403 FORBIDDEN` (ZAF-469). The caller must be an **approved developer** (have a `developer_profiles` row - created when a developer application is approved).

> These endpoints are deliberately **not** gated on `feature:extension_development`: that feature is *granted by* verification approval, so gating submission on it would be circular.

### `GET /v1/developer/verification`

Returns the authenticated developer's own verification record, or `null` if none has been submitted (or the caller is not yet an approved developer). Returns `200` with a nullable `data` - **not** a `404` - mirroring the nullable GraphQL query.

**Response `data` (or `null`):**

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Verification ID |
| `developer_id` | UUID | The developer profile this record belongs to |
| `legal_name` | string | Legal name |
| `company_name` | string or null | Company name (company type only) |
| `address_line1` | string | Address line 1 |
| `address_line2` | string or null | Address line 2 |
| `postal_code` | string | Postal code |
| `city` | string | City |
| `country` | string | ISO-3166-1 alpha-2 country code |
| `tax_id` | string or null | Tax ID (legacy free text) |
| `tax_number` | string or null | Steuernummer |
| `vat_id` | string or null | USt-IdNr. / foreign VAT ID (stored upper-case, without spaces) |
| `small_business_declared` | boolean or null | Small business under § 19 UStG; `null` = not answered |
| `tax_details_updated_at` | ISO-8601 or null | When the tax details were last entered |
| `trade_register_id` | string or null | Trade register ID (company type only) |
| `document_key` | string or null | Upload key for a supporting document |
| `status` | string | `"pending"`, `"verified"`, or `"rejected"` |
| `review_notes` | string or null | Notes from the reviewer (e.g. rejection reason) |
| `reviewed_by` | UUID or null | Reviewer's user ID |
| `reviewed_at` | ISO-8601 or null | Review timestamp |
| `created_at` | ISO-8601 | First submission timestamp |
| `updated_at` | ISO-8601 | Last update timestamp |

### `POST /v1/developer/verification`

Submit (or resubmit) the developer's own KYC verification. **Idempotent upsert** - one record per developer; a resubmit re-enters `pending` and clears any prior review verdict, so a rejected developer can correct and resubmit. An already-`verified` record is terminal via self-service and cannot be resubmitted.

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `legal_name` | string | Yes | Legal name |
| `company_name` | string | No | Company name - its presence infers the `company` developer type |
| `address_line1` | string | Yes | Address line 1 |
| `address_line2` | string | No | Address line 2 |
| `postal_code` | string | Yes | Postal code |
| `city` | string | Yes | City |
| `country` | string | Yes | ISO-3166-1 alpha-2 country code (exactly 2 letters) |
| `tax_id` | string | No | Tax ID |
| `trade_register_id` | string | No | Trade register ID |
| `document_key` | string | No | Upload key for a supporting document |
| `tax_number` | string | No | Steuernummer (max. 50 characters) |
| `vat_id` | string | No | USt-IdNr. / foreign VAT ID (max. 50 characters) |
| `small_business_declared` | boolean | No | Small business under § 19 UStG |

A submit without any of the three tax fields keeps the stored tax details.

**Validation errors (400):** `"Legal name is required"`, `"Address line 1 is required"`, `"Postal code is required"`, `"City is required"`, `"Country is required"`, `"Country must be a 2-letter ISO code"`, `"Tax number must be at most 50 characters"`, `"VAT ID must be at most 50 characters"`.

**Other errors:** `403` `"You must be an approved developer to submit verification"` (caller has no developer profile); `409` `"Your developer verification is already approved"` (record is already `verified`).

**Response:** `201 Created` with the verification object (same shape as the GET response).

**Audit:** emits `developer:verification_submitted` (user scope; no KYC/PII in metadata).

### `PUT /v1/developer/verification/tax-details`

Set the tax details a payout's credit note is derived from, in **any** verification status (also once `verified`). They are self-declared: an update does not reset the review and never changes a credit note that was already issued.

**Request body:** `tax_number`, `vat_id` (strings, max. 50 characters, blank = cleared), `small_business_declared` (boolean or omitted = not answered). The body replaces all three.

Which details a payout needs:

| Developer | Needed | Credit note |
|-----------|--------|-------------|
| Germany, small business | `tax_number` or `vat_id`, `small_business_declared: true` | No VAT, § 19 UStG note |
| Germany, charges VAT | `tax_number` or `vat_id`, `small_business_declared: false` | 19 % VAT on top of the revenue share |
| Other EU country | `vat_id` | No VAT, reverse-charge note (§ 13b UStG) |
| Outside the EU | — | No VAT, reverse-charge note |

**Errors:** `400` validation (as above); `403` `"You must be an approved developer to submit verification"`; `404` `"Submit your developer verification before entering tax details"`.

**Response:** `200 OK` with the verification object.

**Audit:** emits `developer:tax_details_updated` (user scope; metadata says which details are present, never their values).

> **Protocol parity:** `developerVerificationStatus` query and the `submitDeveloperVerification` / `updateDeveloperTaxDetails` mutations in GraphQL - see [GraphQL](./graphql.md#developer-verification-self-service).

## Developer Credit Notes

Every developer payout is documented by a **self-billed credit note** (Gutschrift, § 14 Abs. 2 S. 2 UStG), issued in the payout's own transaction, numbered `GS-<year>-<6 digits>` without gaps per calendar year (Europe/Berlin). A failed payout is cancelled by a **cancellation note** (Stornierung) with its own number and negated amounts. The PDF is generated once after the payout and mailed to the developer with the PDF attached; until then `pdf_status` is `pending` and `download_url` is `null`. See [Developer credit notes](../features/developer-credit-notes.md).

### `GET /v1/developer/credit-notes`

The caller's own credit notes and cancellations, newest first. Query: `limit` (default 20, max 100), `offset`.

**Auth:** `extension-dev:payouts` + `feature:extension_development`, first-party user (a popout token or developer key is refused, as for the payout history).

**Response `data`:** an array of:

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Credit note ID |
| `kind` | string | `credit_note` or `cancellation` |
| `number` | string | `GS-2026-000001` |
| `issued_at` | ISO-8601 | Date of issue |
| `payout_id` | UUID or null | The payout it documents (credit notes only) |
| `cancels_id` | UUID or null | The cancelled credit note (cancellations only) |
| `cancelled_at` | ISO-8601 or null | When this credit note was cancelled |
| `cancellation_reason` | string or null | `payout_failed`, `developer_objection` or `correction` |
| `period_start`, `period_end` | ISO-8601 | Service period |
| `currency` | string | `EUR` |
| `net_amount`, `vat_amount`, `gross_amount` | integer | Cents; negative on a cancellation |
| `vat_rate_bp` | integer | VAT rate in basis points (`1900` = 19 %) |
| `vat_treatment` | string | `domestic_standard`, `domestic_small_business`, `reverse_charge_eu` or `reverse_charge_third_country` |
| `pdf_status` | string | `pending` (being generated) or `stored` |
| `download_url` | string or null | `GET` URL of the PDF (`null` while pending) |
| `delivered_at` | ISO-8601 or null | When the mail with the PDF was sent |

### `GET /v1/developer/credit-notes/{id}`

One of the caller's own notes. Another developer's note answers `404 "Credit note not found"`. Same auth.

### `GET /v1/developer/credit-notes/{id}/pdf`

The PDF as issued (`Content-Type: application/pdf`, `Content-Disposition: attachment`, `Cache-Control: private, no-store`). The bytes are checked against the stored SHA-256 before they are served. `404` for another developer's note; `409 CREDIT_NOTE_PDF_PENDING` while the PDF is being generated. Same auth.

### `GET /v1/admin/credit-notes`

Operators. Query: `developer_id` (optional), `limit`, `offset`. Includes notes whose developer profile was deleted (`developer_id: null`). **Permission:** `billing:read` (admin-scope). Each item is the developer view plus `developer_id`, `supplier_legal_name`, `supplier_country`, `objection_received_at`, `recorded_by`; `download_url` points at the admin PDF route.

### `GET /v1/admin/credit-notes/{id}` and `GET /v1/admin/credit-notes/{id}/pdf`

One note / its PDF. **Permission:** `billing:read` (admin-scope).

### `POST /v1/admin/credit-notes/{id}/cancel`

Record a developer's objection to a credit note (§ 14 Abs. 2 S. 3 UStG) or correct it. Issues the cancellation note and, with `reissue: true`, a corrected credit note for the same payout and service period from the developer's current verification, in one transaction. **Permission:** `billing:edit` (admin-scope).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `reason` | string | Yes | `developer_objection` or `correction` |
| `objection_received_at` | ISO-8601 | For an objection | When the objection arrived; not allowed for a correction |
| `reissue` | boolean | No | Issue a corrected credit note (default `false`) |

**Errors:** `400` `"Reason must be developer_objection or correction"`, `"An objection needs the date it was received"`, `"Only an objection carries a received date"`; `404` `"Credit note not found"`; `409` `"Only an effective credit note can be cancelled"`, `"This credit note has no payout to re-issue it for"`, `409 CREDIT_NOTE_AMOUNT_MISMATCH` (the corrected note would total a different amount than was paid, e.g. the VAT status changed; settle the difference first); `422 TAX_DETAILS_REQUIRED` for the re-issue.

**Response:** `{ "cancellation": …, "reissued": … | null }` (admin view).

**Audit:** emits `system:developer_credit_note_cancelled` (system scope; ids, numbers and reason only).

### `GET /v1/admin/developer-payouts`

Developer payouts for operators, newest first, including payouts of deleted profiles. **Permission:** `billing:read` (admin-scope). Query: `status` (`pending`, `processing`, `completed`, `failed`), `limit` (default 20, max 100), `offset`.

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Payout id |
| `developer_id` | UUID \| null | `null` once the profile was deleted |
| `amount` / `currency` | integer / string | Cents, `EUR` (the credit note's gross amount) |
| `method` | string | `stripe`, `paypal` or `bank` |
| `status` | string | `pending`, `processing`, `completed` or `failed` |
| `stripe_transfer_id` / `paypal_batch_id` | string \| null | Provider ids |
| `payout_reference` | string \| null | Masked destination |
| `created_at` / `completed_at` / `execution_started_at` | ISO-8601 | `execution_started_at`: when the payout cycle sent it |
| `needs_operator` | boolean | `pending` SEPA payout, or a provider payout whose answer the cycle did not receive |

**Errors:** `400` `"Status must be one of pending, processing, completed, failed"`.

### `POST /v1/admin/developer-payouts/{id}/complete` and `POST /v1/admin/developer-payouts/{id}/fail`

Mark a `pending` or `processing` payout paid, or failed. Failed credits the debited amount back to the balance and cancels the credit note. **Permission:** `billing:edit` (admin-scope). No body.

**Response:** `{ "payout": …, "refunded": <cents> | null, "cancellation_number": "GS-…" | null }` (`refunded` and `cancellation_number` are only set by `/fail`).

**Errors:** `404` `"Payout not found"`; `409 PAYOUT_NOT_IN_FLIGHT` (`"Only a pending or processing payout can be settled"`); `/fail` only: `409 PAYOUT_BEING_SENT` (`"The payout cycle is sending this payout right now; try again in 15 minutes"`).

**Audit:** emits `system:developer_payout_completed` or `system:developer_payout_failed` (system scope). See [Developer Payouts](../features/developer-payouts.md).

> **Protocol parity:** `developerCreditNotes`, `developerCreditNote`, `adminCreditNotes`, `adminCreditNote`, `cancelCreditNote`, `adminDeveloperPayouts`, `completeDeveloperPayout` and `failDeveloperPayout` in GraphQL - see [GraphQL](./graphql.md#developer-credit-notes).

## Admin Developer Applications

Admin endpoints for reviewing developer applications. All require `developer-verifications:read` or `developer-verifications:edit` admin-scope permissions.

### `GET /v1/admin/developer-applications`

List developer applications with optional status filter.

**Permission:** `developer-verifications:read` (admin-scope).

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter by status: `"pending"`, `"approved"`, `"rejected"` |

**Response:** `{ "items": [...], "total": N }` where each item contains `id`, `user_id`, `application_type`, `display_name`, `slug`, `status`, `created_at`, `user_display_name`, `user_avatar_url`.

### `GET /v1/admin/developer-applications/{id}`

Get full details of a specific application.

**Permission:** `developer-verifications:read` (admin-scope).

Returns 404 `"Developer application not found"` if not found.

### `POST /v1/admin/developer-applications/{id}/approve`

Approve a developer application. Creates the developer profile, seeds default team roles (for team applications), and sends approval notifications (in-app + email).

**Permission:** `developer-verifications:edit` (admin-scope).

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `notes` | string | No | Optional reviewer notes |

**Response:** `{ "success": true, "new_status": "approved" }`

### `POST /v1/admin/developer-applications/{id}/reject`

Reject a developer application. Sends rejection notifications.

**Permission:** `developer-verifications:edit` (admin-scope).

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `notes` | string | Yes | Rejection reason (required) |

**Response:** `{ "success": true, "new_status": "rejected" }`

> **Protocol parity:** All four endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#admin-developer-applications).

## Admin Limit Requests

Admin endpoints for reviewing developer limit increase requests. All require `developer-limits:read` or `developer-limits:edit` admin-scope permissions.

### `GET /v1/admin/limit-requests`

List all limit requests across all developers with optional status filter.

**Permission:** `developer-limits:read` (admin-scope).

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter by status: `"open"`, `"in_review"`, `"approved"`, `"rejected"` |

**Response:** `{ "data": [...] }` - list of limit request objects.

### `GET /v1/admin/developers/{id}/limit-requests`

List limit requests for a specific developer.

**Permission:** `developer-limits:read` (admin-scope).

**Response:** `{ "data": [...] }` - list of limit request objects for the given developer.

### `PUT /v1/admin/limit-requests/{id}`

Review (approve or reject) a limit request. Approving automatically applies the requested limits. Rejecting requires review notes.

**Permission:** `developer-limits:edit` (admin-scope).

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `action` | string | Yes | `"approve"` or `"reject"` |
| `notes` | string | For reject | Review notes (required when rejecting) |

**Response:** Updated limit request object.

### `GET /v1/admin/limit-requests/{id}/events`

Get timeline events for a limit request.

**Permission:** `developer-limits:read` (admin-scope).

**Response:** `{ "data": [...] }` - list of event objects with `event_type`, `actor_id`, `details`, and `created_at`.

### `PATCH /v1/admin/extensions/{id}/limits`

Set or clear per-extension limit overrides. Replaces the previous `/max-sounds` endpoint with support for all three sound limits.

**Permission:** `developer-limits:edit` (admin-scope).

**Request body:**

| Field | Type | Description |
|-------|------|-------------|
| `max_sounds` | integer or null | Max bundled sounds (null to clear) |
| `max_sound_file_size` | integer or null | Max per-file size in bytes (null to clear) |
| `max_sound_storage_bytes` | integer or null | Max total sound storage in bytes (null to clear) |

**Response:** `{ "data": { "success": true } }`

> **Protocol parity:** All endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#admin---developer-limits).

## Developer Teams

Team management endpoints with team-scoped RBAC. All team operations (except create and list) check `require_team_permission()` against the caller's team role. Every endpoint except the public invite lookup requires a first-party user (session or the user's own API key). Creating a team and accepting an invite additionally require the `feature:extension_development` plan feature on the caller's account; when it is off they fail with `Feature 'feature:extension_development' is not available`. The first-party check runs first.

### Team CRUD

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `POST` | `/v1/developer/teams` | Auth (developer) + `feature:extension_development` | Create a new team |
| `GET` | `/v1/developer/teams` | Auth (developer) | List teams the user belongs to |
| `GET` | `/v1/developer/teams/{id}` | Team member | Get team details |
| `PATCH` | `/v1/developer/teams/{id}` | `team-settings:edit` | Update team name/description/URLs |
| `DELETE` | `/v1/developer/teams/{id}` | Team owner only | Delete a team and its extensions (uninstalled from every channel; see [Accounts](../features/accounts.md)) |

### Team Members

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/developer/teams/{id}/members` | `team-members:read` | List team members |
| `PATCH` | `/v1/developer/teams/{id}/members/{member_id}/role` | `team-members:edit` | Change a member's role |
| `DELETE` | `/v1/developer/teams/{id}/members/{member_id}` | `team-members:remove` | Remove a member |

### Team Invites

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `POST` | `/v1/developer/teams/{id}/invites` | `team-members:invite` | Create an invite link |
| `GET` | `/v1/developer/teams/{id}/invites` | `team-members:read` | List active invites |
| `DELETE` | `/v1/developer/teams/{id}/invites/{invite_id}` | `team-members:invite` | Revoke an invite |
| `GET` | `/v1/developer/team-invites/{code}` | Public | Look up an invite by code |
| `POST` | `/v1/developer/team-invites/{code}/accept` | Auth + `feature:extension_development` | Accept an invite |

An addressed invite email links to `https://lumio.vision/invite/dev/{code}` (or the configured web app origin in another environment). This page accepts by code. The bell accepts the same invite by its stored invite ID; the notification never contains the secret code. Both paths apply the same feature, expiry, use-limit and membership checks. Acceptance errors use `INVITE_NOT_FOUND` (404), `INVITE_EXPIRED` / `INVITE_FULL` (400), and `ALREADY_MEMBER` / `INVITE_NO_LONGER_VALID` (409). The bell also offers Decline: it removes an unused single-use invite, retains shared or used invites, and treats a missing invite as handled.

### Team Roles (RBAC)

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/developer/teams/{id}/roles` | `team-members:read` | List roles for a team |
| `POST` | `/v1/developer/teams/{id}/roles` | `team-settings:edit` | Create a custom role |
| `PATCH` | `/v1/developer/teams/{id}/roles/{rid}` | `team-settings:edit` | Update a role |
| `DELETE` | `/v1/developer/teams/{id}/roles/{rid}` | `team-settings:edit` | Delete a role |
| `GET` | `/v1/developer/teams/permissions` | Auth (first-party user) | List all available team permissions |

> **Protocol parity:** All endpoints have matching GraphQL queries/mutations - see [GraphQL](./graphql.md#developer-teams).

## Developer Store Profiles

Public endpoints for developer and team profile pages. No authentication required.

### `GET /v1/developer/profiles/{slug}`

Returns a public developer profile by slug, including aggregate stats (extension count, total installs, average rating) and a list of published extensions.

**Auth:** None (public).

**Response:**

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Developer profile ID |
| `display_name` | string | Developer display name |
| `slug` | string | URL slug |
| `description` | string or null | Bio/description |
| `github_url` | string or null | GitHub profile URL |
| `website_url` | string or null | Website URL |
| `avatar_key` | string or null | Avatar upload key |
| `created_at` | ISO-8601 | Profile creation date |
| `stats` | object | `{ extension_count, total_installs, avg_rating }` |
| `extensions` | array | List of published extensions with `id`, `short_id`, `slug`, `name`, `description`, `category`, `icon_key`, `pricing_type`, `pricing_amount`, `pricing_currency`, `install_count`, `rating_avg`, `rating_count`, `published_at` |

Returns 404 if no developer has the given slug.

### `GET /v1/developer/teams/{slug}/profile`

Returns a public team profile by slug, including aggregate stats, team members (with roles), and published extensions.

**Auth:** None (public).

**Response:**

| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Team ID |
| `name` | string | Team name |
| `slug` | string | URL slug |
| `description` | string or null | Team description |
| `github_url` | string or null | GitHub URL |
| `website_url` | string or null | Website URL |
| `avatar_key` | string or null | Avatar upload key |
| `created_at` | ISO-8601 | Team creation date |
| `stats` | object | `{ extension_count, total_installs, avg_rating }` |
| `members` | array | `[{ user_id, display_name, avatar_url, role }]` |
| `extensions` | array | Published extensions (same shape as developer profile) |

Returns 404 if no team has the given slug.

> **Protocol parity:** Both endpoints have matching GraphQL queries - see [GraphQL](./graphql.md#developer-store-profiles).

## Extension Store Icons

### `GET /v1/store/extensions/{slug}/icon`

Returns icon metadata for a store extension: `extension_id`, `icon_key` and `icon_url` (the absolute URL of the byte route below, or `null` when the extension has no icon). Returns JSON, not the image.

**Auth:** None (public). `404 Extension not found` unless the extension is visible on the store detail page (status `published` or `deprecated`, visibility `public`, `paid`, `unlisted` or `system`).

### `GET /v1/store/extensions/{id}/icon-data`

Serves the icon image of a store extension by its UUID.

**Auth:** None (public). Same visibility as the store detail page.

**Response:** the stored bytes with `Content-Type` `image/png`, `image/jpeg` or `image/webp` (from the stored key), `X-Content-Type-Options: nosniff`, `Content-Security-Policy: default-src 'none'; sandbox` and `Cache-Control: public, max-age=3600`.

| Status | When |
|--------|------|
| `404 Extension icon not found` | Unknown extension, not store-visible, no icon, a stored key that is not PNG/JPEG/WebP, or the object is missing from storage |
| `503 ICON_UNAVAILABLE` | File storage is not configured |

REST only: raw image bytes have no GraphQL representation. Every `icon_url` / `iconUrl` the API returns for an extension points at this route — the store icon metadata and the developer icon upload as an absolute URL, the marketplace lists and detail (REST `/v1/marketplace/*` and the GraphQL `marketplace*` queries) as the API-relative path `/v1/store/extensions/{id}/icon-data`.

## Extension Bot Module Endpoints

### `GET /v1/internal/bot-modules/{account_id}/triggers`

Returns the resolved bot-module trigger set for the given account. This is an internal endpoint the platform bots call on connect (and on `trigger_sync`) to build their in-memory matcher. Per install, the effective triggers are resolved by layering per-install overrides from `extension_installs.config.triggers` over the version manifest's `triggers` (COALESCE: config wins, manifest is the default).

**Auth:** System key carrying `bots:internal` only. A non-System caller gets `403 System key required for internal endpoints`; a System key without the grant gets `403 Missing permission: bots:internal`.

**Path parameter:** `account_id` - UUID of the account.

**Response:** the raw body (no `data` envelope) - the bots deserialize it directly. Each trigger's `handler` is the `function_name` the bot sends to the Worker's `/v1/execute` (command → command name, keyword → keyword text, pattern → regex source). `killed` is the account's stored kill switch (`account_extension_kill_switch`), so a restarted bot starts killed; live changes arrive over Redis pub/sub on top.

```json
{
  "installs": [
    {
      "install_id": "uuid",
      "extension_id": "uuid",
      "extension_name": "My Bot Module",
      "commands": [
        { "name": "rank", "alias": null, "cooldown_global": 5, "cooldown_user": 10, "min_role": "everyone", "enabled": true, "handler": "rank" }
      ],
      "keywords": [
        { "value": "gg", "enabled": true, "handler": "gg" }
      ],
      "patterns": [
        { "regex": "^!\\w+$", "enabled": true, "handler": "^!\\w+$" }
      ],
      "has_moderate": false,
      "platforms": ["twitch", "youtube"]
    }
  ],
  "killed": false
}
```

### `GET /v1/internal/bot-modules/handlers`

Returns the resolved handler-code bundle plus trusted context for every installed bot-module extension. The Bot Module Worker consumes this to populate its in-memory `InstallRegistry` at startup and to refresh it incrementally on install / uninstall / update. Where the trigger feed above delivers only trigger *metadata*, this feed delivers the executable handler code.

**Auth:** System key carrying `bots:internal` only. A non-System caller gets `403 System key required for internal endpoints`; a System key without the grant gets `403 Missing permission: bots:internal`.

**Query parameters (all optional):**

| Field | Type | Description |
|-------|------|-------------|
| `account_id` | UUID | Scope to a single account (incremental account refresh). |
| `install_id` | UUID | Scope to a single install (incremental install/update refresh). |
| `bundles` | `by_version` | Bundle layout. `by_version` ships each distinct bundle once in a top-level `bundles` map and enables the `ETag` / `304` change check. Omitted: every install carries its own `handler_code`. Any other value is a `400`. |

Omitting `account_id` and `install_id` returns a full cross-account snapshot (initial registry load). Disabled installs are included (with `enabled: false`) so the worker can short-circuit them.

**Response:** the raw body (no `data` envelope) - the worker deserializes it directly. `handlers` lists the valid `function_name`s the bots dispatch (command name / keyword text / regex source / `"moderate"` / `"timer"`, plus subscribed event types and timer names); every name maps to the same bundle. `command_min_roles` is each command's effective `min_role`, `events` the subscribed event types (manifest `triggers.events`), `timers` the timers the worker schedules (`[{ "name", "interval_secs" }]`), and `killed` whether the account's extension kill switch is on. `timers` covers the SDK form `triggers.timers[{ name, interval }]` (entries under 60 s or without a name are skipped) and the legacy `triggers.timer: true` form, which yields one timer named `"timer"` whose interval is the install's `intervalSeconds` setting, clamped to 60..86400, default 300.

Where the bundle lives depends on `bundles`:

- **`bundles=by_version`** (what the Bot Module Worker sends): every install's `handler_code` is `null`, and `bundles` maps each install's `version_id` to the compiled `server.js` bundle, or to `null` when it cannot be resolved (missing file / storage unavailable). Installs sharing a version share one entry, so each bundle is downloaded from storage and sent at most once per response.
- **omitted**: `handler_code` is the bundle (one string per install) or `null` when unresolvable; there is no `bundles` key.

**Change check (`bundles=by_version` only):** the response carries an `ETag` over the install metadata (everything above except the bundles; `version_id` identifies the bundle). Send it back as `If-None-Match` and the API answers `304 Not Modified` with no body while nothing has changed. It decides that before downloading any bundle. The `ETag` is omitted while any bundle is unresolvable, so the next request downloads again.

```json
{
  "installs": [
    {
      "install_id": "uuid",
      "extension_id": "uuid",
      "account_id": "uuid",
      "extension_name": "Link Protection",
      "version": "1.0.2",
      "version_id": "uuid",
      "install_config": { "action": "delete" },
      "enabled": true,
      "platforms": ["twitch", "youtube", "kick"],
      "has_moderate": true,
      "handlers": ["moderate"],
      "handler_code": null,
      "command_min_roles": {},
      "events": [],
      "timers": [],
      "killed": false
    }
  ],
  "bundles": {
    "uuid": "async (ctx, args) => { /* compiled server.js */ }"
  }
}
```

### `POST /v1/internal/bot-modules/{install_id}/actions`

Runs the `actions` of one bot-module handler result. The Bot Module Worker (keyword, pattern, event, timer handlers) and the chat bots (command handlers, moderate decisions) call it after the reply, at most once - there is no retry, because a retried `chat:ban` is not idempotent at the platform. Not part of `openapi.json`, like the other internal feeds.

**Auth:** System key carrying `bots:internal` only. A non-System caller gets `403 System key required for internal endpoints`; a System key without the grant gets `403 Missing permission: bots:internal`.

**Path parameter:** `install_id` - UUID of the bot-module install. The account always comes from the install row, never from the request.

**Request body:**

```json
{
  "trigger_type": "moderate",
  "handler": "moderate",
  "platform": "twitch",
  "actions": [
    { "action": "chat:timeout", "params": { "platform": "twitch", "user_id": "123", "duration_secs": 600 } }
  ]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `trigger_type` | string | `command`, `keyword`, `pattern`, `event`, `timer` or `moderate` |
| `handler` | string | Handler function name (command name, event type, timer name, …), 1-200 characters |
| `platform` | string, optional | Platform the trigger came from |
| `actions` | array | `{ "action", "params" }` items, at most 20; `params` defaults to `{}` |

**Errors:**

| Status | When |
|--------|------|
| `400` | Unknown `trigger_type`, empty or over-long `handler`, or more than 20 actions |
| `404` | `Bot module install not found or not runnable` - the install is uninstalled, disabled, not a bot module, its extension is suspended, its channel is in the dissolution grace period, or the account's kill switch is on |

**Response `200`:** the raw body, one result per action in request order. One failing action does not stop the next.

```json
{
  "results": [
    { "action": "chat:timeout", "success": true },
    { "action": "obs:set_scene", "success": false, "error": "Permission denied: Extension does not declare the required permission: obs:set_scene", "error_code": "denied" }
  ]
}
```

Each action runs through the same dispatcher and manifest-permission gate as widget and app actions (the 21 supported actions): the manifest must declare the action name as a permission, the account's plan must include the action's feature (`spotify:*` → `feature:music`, `obs:*` → `feature:obs_remote`, `chat:*` → `feature:multichat`), and the params must be valid.

| `error_code` | Meaning |
|--------------|---------|
| `denied` | Refused before dispatch: unknown action, invalid params, permission not declared, plan feature off, or `params` not an object. The message is the one the widget path returns |
| `rate_limited` | The install exceeded `[extensions] bot_module_action_rate_per_minute` (default 120) in the current minute |
| `rate_limit_unavailable` | Redis could not count the action; refused (fail-closed) |
| dispatcher codes (`bot_not_connected`, `bot_scope_missing`, `moderation_forbidden`, `platform_not_supported`, …) or none | The action failed during execution |

The rate cap is counted per install in Redis `lumio:botmod:act_rl:{install_id}:{epoch_minute}` (TTL 120 s). Every outcome is written to the install's log (`extension_install_logs`, level `info` on success, `warn` otherwise), at most one row per second and install per API process; after the cap is hit only the first refused action of the minute is logged. A row's args hold only the action name and, for `chat:*`, `platform` / `user_id` / `message_id` - never message text or other params.

`chat:ban`, `chat:unban` and `chat:timeout` emit the audit event `account:extension_moderation` with `source: "bot_module"` and an empty origin (service-to-service call). A bot module's `chat:delete` is not audited; it appears in the install log only. See [Audit Log](../features/audit-log.md).

### `GET /v1/internal/automation-nodes/handlers`

The automation-node counterpart of the bot-module handler feed - resolves the handler bundle + context for every installed `automation_node` extension for the Automation Worker's `InstallRegistry`.

**Auth:** System key carrying `bots:internal` only. A non-System caller gets `403 System key required for internal endpoints`; a System key without the grant gets `403 Missing permission: bots:internal`.

**Query parameters:** identical to the bot-module handler feed (`account_id`, `install_id`, both optional).

**Response:** raw body. `node_type` is the node's kind (`trigger` / `action` / `logic`); `handler_code` is the single compiled `server.js` bundle (automation nodes have exactly one handler), or `null` when unresolvable.

```json
{
  "installs": [
    {
      "install_id": "uuid",
      "extension_id": "uuid",
      "account_id": "uuid",
      "extension_name": "HTTP Request",
      "version": "1.0.0",
      "install_config": { "url": "https://example.com" },
      "enabled": true,
      "node_type": "action",
      "handler_code": "async (ctx, args) => { /* compiled server.js */ }"
    }
  ]
}
```

### `POST /v1/bot-modules/kill`

Sets the extension kill switch for the caller's account: while `killed` is `true`, the bots match no extension bot-module trigger for the account, and every handler server function (`query()` / `mutation()` / `action()`, [`/execute`](#post-v1extension-installsinstall_idexecutefunction_name)) of the account's extensions of any category, widgets included, is refused with `403 EXTENSIONS_KILLED`. Declarative server functions (`/query`, `/mutate`) keep working. The state is stored in Postgres (`account_extension_kill_switch`), so it survives a bot restart, and is pushed live over `lumio:botmod:kill:{account_id}`. Install configuration is untouched.

**Auth:** Account auth (JWT, API key, or popout token).

**Permission:** `bot-modules:edit`

**Request body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `account_id` | UUID | Yes | Must be the caller's active account (`403 Cannot control kill switch for another account` otherwise) |
| `killed` | boolean | Yes | `true` stops extension triggers, `false` resumes them |

**Response:** `200 {"ok": true}`. Emits the account-scoped audit event `account:extension_kill_switch_set` (metadata: `killed`).

**GraphQL twin:** `setBotModuleKillSwitch(accountId: UUID!, killed: Boolean!): Boolean!` (same permission, check, error and audit event).

## Developer Extension Endpoints

Create and update requests accept only `private`, `unlisted`, `public`, or `paid` visibility. `system` is reserved for Lumio, and a developer slug beginning with `system-` (ignoring case and surrounding whitespace) is rejected. REST returns `400` with `Invalid visibility: <value>. Allowed: private, unlisted, public, paid` or `The slug prefix 'system-' is reserved for Lumio system extensions`. GraphQL applies the same validators.

### Extension secrets

Secrets are the extension author's credentials (for example a third-party API key). Each extension has **one** set, shared by every install: bot-module handlers read it with `ctx.secrets.get(key)`. The developer's active account plays no part, so a developer key (`lm_dev_`) manages secrets like a logged-in developer. Values are encrypted with AES-256-GCM before they are stored and are never returned.

| Method | Path | Permission | Description |
|---|---|---|---|
| `GET` | `/v1/developer/extensions/{id}/secrets` | `extension-dev:read` (+ `team-secrets:read` on a team extension) | List secret key names |
| `PUT` | `/v1/developer/extensions/{id}/secrets/{key}` | `extension-dev:edit` (+ `team-secrets:edit` on a team extension) | Create or replace a secret. Body `{"value": "..."}` |
| `DELETE` | `/v1/developer/extensions/{id}/secrets/{key}` | `extension-dev:edit` (+ `team-secrets:edit` on a team extension) | Delete a secret (`204`, also when no secret had that key) |

- **Order of checks:** ownership first (`404 Extension not found` for an extension the caller's profile or teams do not own), then the team right (`403 Missing team permission: team-secrets:edit`), then validation.
- **Validation:** the key must match `^[A-Z0-9_]{1,64}$` (`400 Secret key must match ^[A-Z0-9_]{1,64}$`); the value must be 1 to 4096 bytes (`400 Secret value must be between 1 and 4096 bytes`).
- **Response row:** `id`, `extension_id`, `account_id` (always `null`), `key`, `created_at`, `updated_at`.
- **Audit:** set emits `developer:extension_secret_set`, a delete that removed a row emits `developer:extension_secret_deleted` (user scope, metadata `extension_id`, `key`, and `developer_key_id` for a developer key; never the value).
- **Runtime:** a changed or deleted secret reaches running bot-module handlers within 60 seconds.

**GraphQL twins:** `developerExtensionSecrets(extensionId)`, `setExtensionSecret(extensionId, key, value)`, `deleteExtensionSecret(extensionId, key): Boolean!` (same permissions, checks, messages and audit events).

### Version creation, upload, and submission

| Method and path | Request | Validation |
|---|---|---|
| `POST /v1/developer/extensions/{id}/versions` | JSON `version`, `manifest`, optional `data_schema` | Manifest schema, extension ID, and manifest version must match the request; `data_schema` is validated and checked to be additive. |
| `POST /v1/developer/extensions/{id}/versions/upload` | Multipart `files`, `source`, `manifest`, optional `data_schema` (JSON), and version metadata | Manifest schema and extension ID are validated; bundle storage keys are server-derived; `data_schema` as above. Each `files` filename is a relative `/`-separated path: `..`, absolute paths, backslashes, empty or `.` segments, NUL bytes and file types outside the allow-list return `400`. |
| `POST /v1/developer/extensions/{id}/versions/{vid}/submit` | Draft version ID in the path | Stored manifest is revalidated before the version enters review. |

`data_schema` is the `defineSchema` result of `server/schema.ts` (`{"tables": {"<name>": {"columns": {"<col>": {"type": "string|number|boolean|array|object", "isOptional": bool}}, "storageScope": "instance"}}}`). It is stored once, normalised, with the version; omitted or `null` means the version declares no data. An invalid schema (name rule `^[a-z][a-z0-9_]{0,39}$` without `pg_*` / `ext_*`, at most 32 tables, 64 columns per table, 64 KiB, storage scope `instance` only) returns `422 INVALID_DATA_SCHEMA`. A change that is not additive against the extension's tables (type change, new required column on an existing table, optional → required) returns `422 DATA_SCHEMA_NOT_ADDITIVE` with every violation in `details.violations` (`table`, `column`, `rule`, `applied`, `declared`). The tables are created at approval, not at upload: `POST /v1/extensions/reviews/{id}/approve` (GraphQL `approveExtensionVersion`) provisions the version's schema on the extensions database before the status changes. A version that is no longer additive is not approved: `422 DATA_SCHEMA_NOT_ADDITIVE` with the violation list, which is also stored as the version's review notes. When live queries hold the tables for longer than the lock timeout (three retries), approval returns `503 EXTENSION_TABLES_BUSY` and can be retried. The first install of an approved version re-creates tables an earlier last uninstall removed. See the developer docs → Server Functions → Schema.

Manifest failures return `400 Manifest validation failed: ...`; a version mismatch returns `400 Version '<input>' does not match the manifest version '<manifest>'`. Submission leaves the draft unchanged when validation fails. For a team-owned extension, create and upload require `team-versions:create`, and submit requires `team-extensions:publish`. A member without the role gets `403 Missing team permission: <permission>`; a caller without ownership gets `404` first. The same team-role check applies to editing, deleting, analytics, and tester/access management as described in [Team-Scoped Permissions](./permissions.md#team-scoped-permissions-developer-teams).

> **Developer API keys (`lm_dev_`):**
> These publishing routes accept a **developer API key** (`lm_dev_`) as well as a logged-in user session or account API key. A developer key is bound to a developer profile or team, is **decoupled from the `feature:extension_development` plan gate**, and reaches exactly the ownership-scoped publishing operations here - its own extensions, versions (create / upload / list), analytics, limits, purchases, testers (list / remove), screenshots and the extension's **secrets** (see [Extension secrets](#extension-secrets)). It is **refused** (fail-closed) from:
> 
> - the **first-party** routes - the developer profile / payout / revenue / limit-request surface, plus `POST …/extensions` (create), `…/versions/{vid}/submit`, `…/testers` (invite) and `…/deletion-request`, which require a logged-in user.
> 
> See [Authentication → Developer API Keys](./authentication.md#developer-api-keys).

> **Telemetry retention & availability:**
> Extension telemetry lives in TimescaleDB hypertables with bounded retention policies, so the tables cannot grow without bound - aged chunks are dropped automatically:
> 
> - **Runtime errors** (`extension_errors`, surfaced by `/errors`): **90 days**.
> - **Per-install execution logs** (`extension_install_logs`): **30 days**.
> - **Install/uninstall/config-change analytics** (`extension_events`, feeding `/metrics`): **180 days**.
> 
> A query window wider than a table's retention returns only the rows still inside the window.
> 
> An `extension_errors` row keeps no viewer or account data: account and install IDs are HMAC-hashed, the error message and stack trace are scrubbed of UUIDs, @-mentions, tokens and IPs, the install config is reduced to its key names, and the handler args are stored as **shape only** - their keys and value types (`"<string>"`, `"<number>"`, `"<bool>"`), never the values. The `/errors` endpoint does not return the args.
> 
> The retention policies are active today. `extension_errors` and `extension_install_logs` now have their **writers wired**: the bot-module and automation workers record one row per handler execution (an `extension_errors` row on failure, an `extension_install_logs` row on every run), fail-open, once a worker has a TimescaleDB pool configured. Rows only begin to flow when the workers actually execute handlers against live installs - i.e. once the worker `InstallRegistry` is populated at runtime (tracked separately); until then these tables stay empty even though the writers are present. `extension_events` (install/uninstall/config-change analytics feeding `/metrics`) is still unwired. Where a table has no rows yet, its endpoint returns an **empty result set** - the example payloads below illustrate the response shape, not live data.

### `GET /v1/developer/extensions/{id}/errors`

Returns recent runtime errors for an extension owned by the authenticated developer. Useful for debugging server function failures and trigger handler exceptions.

**Auth:** Account auth (JWT or API key). The caller must be the extension owner or a member of the owning developer team.

**Permission:** `extensions:read` (developer scope)

**Path parameter:** `id` - UUID of the extension.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | integer | Max results (default 50, max 200) |
| `offset` | integer | Pagination offset |
| `since` | ISO-8601 | Only errors after this timestamp |

**Response:**

```json
{
  "data": [
    {
      "id": "uuid",
      "error_type": "handler_timeout",
      "message": "Handler exceeded 10s CPU timeout",
      "stack_trace": "at handler (server/functions.ts:42:5)",
      "occurred_at": "2026-05-20T10:30:00Z",
      "install_id": "uuid",
      "account_id": "uuid"
    }
  ]
}
```

### `GET /v1/developer/extensions/{id}/metrics`

Returns aggregated invocation metrics for an extension owned by the authenticated developer: total invocations, error count, average and 99th-percentile execution time, a per-handler breakdown, and an hourly time series. Metrics are computed from the `extension_install_logs` hypertable, so the counts are empty until installs start emitting execution telemetry.

This endpoint is the REST twin of the GraphQL `extensionMetrics` query - identical fields, permission, and ownership check on both protocols.

**Auth:** Account auth (JWT or API key). The caller must be the extension owner or a member of the owning developer team.

**Permission:** `extension-dev:read`

**Feature:** `feature:extension_development`

**Path parameter:** `id` - UUID of the extension.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `since` | string (RFC 3339) | Optional. Only include data at or after this timestamp. Omit for all-time. |

**Response:**

```json
{
  "data": {
    "total_invocations": 12450,
    "total_errors": 23,
    "avg_execution_ms": 45.2,
    "p99_execution_ms": 280.0,
    "by_handler": [
      {
        "handler": "onMessage",
        "total_invocations": 9800,
        "total_errors": 12,
        "avg_execution_ms": 41.7,
        "p99_execution_ms": 255.0
      }
    ],
    "time_series": [
      {
        "bucket": "2026-05-20T10:00:00+00:00",
        "total_invocations": 512,
        "total_errors": 1,
        "avg_execution_ms": 44.9
      }
    ]
  }
}
```

`by_handler` is ordered by invocation count (descending) and capped at 100 handlers; `time_series` is bucketed to the hour, ordered oldest-first, and capped at 1000 buckets.

### `GET /v1/developer/limits`

Returns the resolved limits for the authenticated developer, including per-category breakdowns with sources and all extension-specific overrides.

**Auth:** Account auth (JWT or API key). The caller must be a developer.

**Permission:** `extension-dev:read`

**Feature:** `feature:extension_development`

**Response:**

```json
{
  "data": {
    "categories": [
      {
        "category": "bundled_sounds",
        "limits": [
          {
            "key": "max_sounds",
            "label": "Sounds per extension",
            "value": 50,
            "source": "default",
            "default_value": 50,
            "configurable": true
          }
        ]
      }
    ],
    "extensions": [
      {
        "extension_id": "uuid",
        "extension_name": "My Extension",
        "limits": { "max_sounds": 100, "max_sounds_source": "extension_override" }
      }
    ]
  }
}
```

### `GET /v1/developer/limit-requests/{id}/events`

Returns the timeline events for a limit request owned by the authenticated developer.

**Auth:** Account auth (JWT or API key).

**Permission:** `extension-dev:read`

**Feature:** `feature:extension_development`

**Response:**

```json
{
  "data": [
    {
      "id": "uuid",
      "request_id": "uuid",
      "event_type": "submitted",
      "actor_id": "uuid",
      "details": null,
      "created_at": "2026-05-30T10:00:00Z"
    }
  ]
}
```

### `GET /v1/developer/extensions/{id}/limits`

Returns the resolved sound limits for an extension owned by the authenticated developer.

**Auth:** Account auth (JWT or API key). The caller must be the extension owner or a member of the owning developer team.

**Permission:** `extension-dev:read`

**Feature:** `feature:extensions`

**Response:**

```json
{
  "data": {
    "max_sounds": 50,
    "max_sounds_source": "default"
  }
}
```

`max_sounds_source` is one of: `"default"` (platform default 50), `"developer_override"` (admin set on developer), `"extension_override"` (admin set on this extension).

### `GET /v1/developer/payout-settings`

Returns the authenticated developer's saved payout settings - payout method, Stripe Connect id, PayPal email, and SEPA bank IBAN/BIC/name - for prefilling the payouts form. Companion read to the `POST /v1/developer/payouts` update (same private `DeveloperProfile` shape, gated on the payout permission). REST twin of the GraphQL `developerPayoutSettings` query. The update (`POST /v1/developer/payouts`) bounds the plaintext with the same rule and error text as GraphQL `updateDeveloperPayoutSettings`: IBAN at most 34 characters not counting spaces (50 with spaces), BIC at most 11, PayPal email and bank name at most 255 each. A longer value is refused with `400` (`IBAN must be at most 34 characters, not counting spaces`, `BIC must be at most 11 characters`, `PayPal email must be at most 255 characters`, `Bank name must be at most 255 characters`) before anything is stored. The four fields are stored encrypted.

**Auth:** Account auth (JWT or API key). The caller must be a developer; a popout/overlay/widget/extension token is rejected with `403 FORBIDDEN` (ZAF-471 first-party gate).

**Permission:** `extension-dev:payouts`

**Feature:** `feature:extension_development`

**Response:**

```json
{
  "data": {
    "id": "uuid",
    "user_id": "uuid",
    "stripe_connect_id": null,
    "paypal_email": "dev@example.com",
    "bank_iban": null,
    "bank_bic": null,
    "bank_name": null,
    "payout_method": "paypal",
    "revenue_balance": 12500,
    "total_earned": 48000,
    "created_at": "2026-08-01T10:00:00Z",
    "updated_at": "2026-09-05T12:00:00Z"
  }
}
```

Returns `404 NOT FOUND` (`Developer profile not found`) if the caller has not applied as a developer.

## Extension Bundle Serving

### `GET /v1/extension-bundles/{extension_id}/{version}/{path}`

Serve a file from an extension version's bundle. The `path` is a catch-all that resolves to a file in the version's `extension_version_files` table.

**Auth:** Published versions are publicly accessible (no auth required). Draft and testing versions require developer authentication (JWT or API key of a developer of the extension, its own extension token, or a system key carrying `bots:internal` - a system key without the grant gets `403 Missing permission: bots:internal`).

**Path parameters:**

| Parameter | Description |
|-----------|-------------|
| `extension_id` | UUID of the extension |
| `version` | Semver version string (e.g. `1.2.0`) |
| `path` | File path within the bundle (e.g. `layer.js`, `styles.css`, `assets/logo-a1b2c3.png`) |

**Security:**
- Path traversal attempts (`..`, null bytes, absolute paths) are rejected with 400
- `source.tar.gz` is never served (returns 403)
- Bundle and source storage keys are derived by the server. Legacy bundle and file records are served only when their key belongs to that extension version's storage namespace.

**Response:** The raw file bytes with the stored `Content-Type` header. Cache headers depend on whether the resolved version is published:

- **Published** - auth-independent bytes, identical for every caller: `Cache-Control: public, max-age=86400, immutable`.
- **Draft / testing** - auth-dependent bytes, resolved only for a developer (via `extension_dev_mode` or an extension token) or a system key carrying `bots:internal`: `Cache-Control: private, no-store` plus `Vary: Authorization, Cookie`. They must never sit in a shared/URL-keyed cache that could serve draft bytes to a non-developer request without re-running the draft-access check.

Every successful bundle response includes `X-Content-Type-Options: nosniff`. HTML, SVG, JSON, source maps, Lottie, and other content outside JavaScript, CSS, raster images, fonts, audio, and video also receive `Content-Security-Policy: sandbox` and `Content-Disposition: attachment`. The dashboard bundle proxy applies the same content-handling headers; SVG remains usable as an image resource.

**Legacy compatibility:** `GET /v1/extension-bundles/{extension_id}/{version}/bundle.js` is preserved as a dedicated route and falls back to the `bundle_key` column for pre-migration versions.

### `GET /v1/extensions/{id}/versions/{version}/files`

List all files in an extension version's bundle.

**Auth:** Published versions are publicly accessible. Draft and testing versions require developer authentication.

**Path parameters:**

| Parameter | Description |
|-----------|-------------|
| `id` | UUID of the extension |
| `version` | Semver version string |

**Response:**

```json
{
  "data": [
    {
      "id": "uuid",
      "version_id": "uuid",
      "file_path": "layer.js",
      "content_type": "application/javascript",
      "size_bytes": 312000,
      "content_hash": "sha256-abc123...",
      "created_at": "2026-05-26T10:00:00Z"
    }
  ]
}
```

> **Protocol parity:** `extensionVersionFiles(extensionId, version)` query in GraphQL -- see [GraphQL](./graphql.md#extension-version-files).

## Extension Upload Endpoints

### `POST /v1/extensions/{extension_id}/uploads`

Upload a file from an extension editor (icons, images). Used by the SDK's `ctx.upload()` method inside extension iframes.

**Auth:** Extension Token (`lm_ext_*`). The token's `extension_id` must match the path parameter.

**Body:** `multipart/form-data` with a `file` field.

**Limits:** Max 256 KB per file. Max 50 uploads per extension per account. Accepted formats: PNG, JPEG, GIF, SVG, WebP, AVIF.

**Deduplication:** Files are deduplicated by SHA-256 content hash. Uploading an identical file returns the existing URL without re-uploading.

**Response:**

```json
{
  "data": {
    "url": "https://api.lumio.vision/v1/extensions/{extension_id}/uploads/{hash}.png"
  }
}
```

### `GET /v1/extensions/{extension_id}/uploads/{filename}`

Serve an uploaded file. Public access (URLs are unguessable due to content-hash filenames).

**Response:** Raw file bytes with correct `Content-Type` and `Cache-Control: public, max-age=86400, immutable`.

## Extension Install Endpoints

Every install object (`GET /v1/extension-installs`, the install, configure, auto-update and pin responses, and GraphQL `InstalledExtension`) carries `targets`: the manifest `targets` of the installed version (`editor`, `layer`), or `[]` when the manifest lists none. The overlay editor offers every install with a `layer` target as a layer, a bot module with a layer included.

`POST /v1/extension-installs` accepts a published extension with `public`, `paid`, `unlisted`, or `system` visibility. A published private extension also needs an access grant for the account or a tester invitation for the acting user. Other targets return `404 Extension not found`, including after a private access grant is revoked. The GraphQL `installExtension` mutation uses the same eligibility check. `POST /v1/extension-purchases` applies it before it creates a Stripe Checkout session or installs through a free-access grant (`404 Extension not found` otherwise), and the payment webhook applies it again before its install. A payment that completes after access was revoked, or after the extension or its version was deleted or unpublished, is recorded without an install and refunded in full in the same webhook pass (a subscription is cancelled at once first); the purchase turns `refunded` when Stripe reports the refund. Purchase has no GraphQL twin.

Installing an extension the account already has returns `409 Extension is already installed`. `DELETE /v1/extension-installs/{id}` removes the install from every install read at once: lists, lookups, the per-install function/action/storage endpoints (`404 Extension install not found`) and the internal bot/automation handler feeds. Unless `delete_data_immediately=true` is passed, the extension's stored data is kept for 30 days. Either way only this account's data is deleted: the extension's database schema `ext_{extension_id}` is shared by every account that installs it, so the account's rows are deleted from it and the schema is dropped only with the extension's last install. The uninstall emits the account-scoped audit event `account:extension_uninstalled` (`extension_id`, `install_id`, `delete_data_immediately`). a `POST /v1/extension-installs` for the same extension within that window restores the install on the latest published version with its saved configuration and returns `201`. GraphQL `installExtension` / `uninstallExtension` behave the same.

### `GET /v1/extension-installs/{install_id}/storage`

All key/value entries of an install's extension storage (`useExtensionStorage()`), ordered by key. Auth: the install's own extension token, or a user session / personal key / service key of the owning account with `extension-store:read`. An overlay token whose overlay renders the install in an extension layer (`ext:{slug}`), or a widget token whose widget renders it, may read too; the install must be runnable (its extension and version not suspended, the install enabled, the account not dissolving), else `404 Extension install not found`. A token of another overlay or widget gets `403 Extension install belongs to a different overlay` / `… widget`; shared overlay links and popout tokens get `401`. Feature: `feature:extensions`. An uninstalled install (pending its 30-day data deletion) answers `404`. GraphQL twin: `extensionStorage(installId)`.

```json
{ "data": [ { "key": "volume", "value": 0.8 } ] }
```

### `POST /v1/extension-installs/{install_id}/query/{function_name}` and `/mutate/{function_name}`

Declarative server functions on the extension's tables, called by name. `function_name` is an export of the extension's `server/functions.ts`; the API looks it up in the functions manifest (`functions.json`) of the version the install runs (its pinned version, else its current one). A version's manifest never changes after upload, so the API parses it once per version and process and keeps it in memory (16 MiB budget); a call costs one database lookup, the install check that also names the version. The body is `{"params": {...}}`: the values for the function's `arg()` references.

- **Resolution:** `query` runs a `queryRows` definition, `mutate` an `insertRow` / `patchRow` / `deleteRow` definition. The definition supplies the table, filters (`=`, `!=`, `>`, `>=`, `<`, `<=`, `like`, `in`), order (default `created_at` ascending), `limit` (default 100, clamped to 1000), `offset` (clamped to 100 000) and row values. `arg()` values are bound as typed SQL parameters, never as SQL text; a value the definition fixes cannot be overridden by `params`. `identity()` is the calling user's id (`null` for token callers). A missing `arg()` is `null` in values and filters, "not set" for `limit` / `offset`, and ``400 missing argument `id` `` for a row id.
- **Errors:** `404 Unknown server function: {name}` (also when the version ships no functions); `400 Server function '{name}' is a mutation, not a query` (and the reverse); `400 Server function '{name}' is a handler; call it through execute`; `400 invalid argument ...` / `row id must be a UUID`.
- **Editor-only:** a definition with `editorOnly: true` runs only for the editor surface. The surface comes from the credential, never from the request: a dashboard session, personal API key or System key is the editor; an extension, overlay or widget token is a rendered extension and gets `403 Editor-only function called outside editor`.
- **Raw operations:** dashboard sessions, personal API keys and System keys may instead send the operation itself. `query`: `table`, `filters` (`[{field, op, value}]`, `op` ∈ `eq|neq|gt|gte|lt|lte|like|in`) and `limit` (newest first). `mutate`: `table`, `function_type` (`insert_row` | `patch_row` | `delete_row`), `args` (the column values) and `row_id` (patch/delete). A request with `table` is a raw operation and `params` is ignored. Extension, overlay and widget tokens get `403 Raw data operations need a signed-in session or an API key; call the server function by name`.
- **Response:** `{rows, affected_count}`; every row is the full row as JSON including `_id`, `_account_id`, `_created_at` and `_updated_at`.
- **Scope:** every statement is limited to the install's account; another account's `_id` matches nothing. `_`-prefixed columns cannot be written or filtered.
- **Validation:** unknown tables/columns and values of the wrong type return `400` (`unknown table: ...`, `unknown column ...`, `invalid value for column ...: expected ...`, `column ... is not nullable`, `cannot order by column ...`). An extension whose installed versions declare no data returns `404 NO_DATA_SCHEMA` (`this extension has no data schema`).
- **Limits:** per install and minute, 100 reads (`query`) and 200 writes (`mutate`), shared with the extension's bot-module `ctx.db`; over the limit `429 RATE_LIMIT_EXCEEDED`. When the rate-limit store is unreachable, reads run and writes return `503 EXTENSION_DATA_UNAVAILABLE` (fail-closed). A statement over 2 s returns `504 EXTENSION_QUERY_TIMEOUT`; no free extensions-database connection within 2 s returns `503 EXTENSION_DATA_UNAVAILABLE` (`db busy`).
- **Callers:** `User` / `ApiKey` of the install's account need `extension-data:read` (query) or `extension-data:edit` (mutate). System keys need `bots:internal`. An extension token works only for its own install; an overlay token only for an install that an extension layer (`ext:{slug}`) of its overlay renders; a widget token only for its widget's install. Shared overlay links and popout tokens are refused.

The manifest is checked when the version is uploaded (`POST /v1/developer/extensions/{id}/versions/upload` with the `functions.json` file, or GraphQL `uploadExtensionVersion` with `functionsManifest`): format version, names, operators, fixed row ids, and every table against the version's data schema. A failed check returns `400` with the reason, e.g. `` functions.json: `getRules` uses table `missing`, which the version's data schema does not declare ``.

**GraphQL twins:** `extensionQuery(input)` and `extensionMutate(input)` (`functionName` + `params`, or the raw fields): same callers, resolution, validation, limits, messages and codes.

### `POST /v1/extension-installs/{install_id}/execute/{function_name}`

Handler server functions: a `query()`, `mutation()` or `action()` export of the extension's `server/functions.ts`. Body: `{"args": {...}}`, passed to the handler as its `args`. The API looks `function_name` up in the functions manifest of the version the install runs; the definition must be a handler (`400 Server function '{name}' is not a handler; call it through query or mutate`). The handler code is that version's `server.js`, never taken from the request. The API sends the call to the Bot Module Worker (`POST {bot_module_worker.url}/v1/server-functions/execute`, `Authorization: SystemKey`), which runs it in a V8 isolate. V8 does not run in the API process.

- **Callers and checks:** as for `query` / `mutate`; an install whose code may not run (its extension or the version it runs suspended, the install disabled, the account in its dissolution grace period) is `404 Extension install not found` for every caller and never reaches the worker. `User` / `ApiKey` need `extension-data:read` for a `query()` handler and `extension-data:edit` for `mutation()` / `action()`. `editorOnly` comes from the definition; tokens get `403 Editor-only function called outside editor`. While the account's extension kill switch is on, every call gets `403 EXTENSIONS_KILLED`.
- **Handler context:** `ctx.db` is the shared data executor on the install's account (same limits as above); a `query()` handler is read-only - its `ctx.db` writes, `ctx.cache` writes and `ctx.defer` jobs are refused inside the handler, so `extension-data:read` never causes a stored write (it can still trigger the handler's own `ctx.realtime.push` broadcasts, under the install's realtime cap); `ctx.auth` is `{userId, accountId, role}` (`userId` is `null` for token callers); `ctx.config` the install's config; `ctx.cache`, `ctx.secrets` and `ctx.defer` as for bot modules; `ctx.fetch` refuses every host (deny-all egress).
- **Limits:** 5 s wall-clock and 256 MB heap per call; per install and minute 100 `query()` calls (shared with `/query`), 50 `mutation()` and 20 `action()` calls (`429 RATE_LIMIT_EXCEEDED`; when the worker's rate-limit Redis fails, calls are refused the same way rather than let through); per worker replica at most 16 handlers at a time and 4 per account (`[server_functions]` in the worker config) - a call that finds no free slot gets `429 RATE_LIMIT_EXCEEDED` at once instead of waiting; `server.js` at most 5 MiB.
- **Realtime:** the worker returns the handler's `ctx.realtime.push(topic, payload)` calls with its value. The API validates them (topic 1-64 characters of `A-Z a-z 0-9 _ . : -` starting with a letter or digit, payload at most 16 KiB serialized, at most 32 pushes per call; the isolate applies the same rules at `ctx.realtime.push`, so a bad push throws inside the handler, and a batch that still arrives invalid is dropped while the call succeeds, since the handler's writes are already committed) and publishes them in order on `lumio:extension_install:{install_id}`, which reaches WebSocket subscribers of `extension_install:{install_id}` (see [WebSocket](./websocket.md)). At most 300 pushes per install and minute (shared with the install's bot-module handlers); pushes over that are dropped and the call still succeeds.
- **Response:** `{"data": <the handler's return value>}`.
- **Errors:** `404 Unknown server function: {name}` / `The installed version has no server bundle`; `404 Extension install not found` (see callers above); `422 HANDLER_ERROR` (the first line of the message the handler threw, at most 500 characters, without its stack trace; `Handler execution failed` for a failure outside the handler's code, whose text never reaches the caller); `422 HANDLER_MEMORY_LIMIT`; `504 HANDLER_TIMEOUT`; `503 EXECUTOR_UNAVAILABLE` (`Server-function executor is unavailable; try again later`) when `[bot_module_worker]` has no `system_key`, the worker is unreachable or fails, or the bundle cannot be read from storage.

**GraphQL twin:** `extensionExecuteHandler(input: {installId, functionName, args})`: same callers, checks, limits, messages and codes.

### `POST /v1/extension-installs/{install_id}/storage`

Set one key. Body: `{ "key": "volume", "value": 0.8 }` (`value` is any JSON). Returns the stored entry and broadcasts `storage:update` on the WebSocket channel `ext-storage:{install_id}`. Auth as above, with `extension-store:configure`. Overlay and widget tokens never write storage: `403 Overlay and widget tokens cannot write extension storage`. A rendered layer that has to change state calls a server function instead. GraphQL twin: `setExtensionStorage`.

Limits per install, checked on every write: key at most 256 bytes (UTF-8, not empty, no `:`; surrounding whitespace is trimmed), value at most 64 KiB of JSON, at most 1 000 keys and 1 MiB in total (keys + JSON values). Overwriting an existing key with a smaller value is always allowed. A rejected write stores nothing and returns `400 BAD_REQUEST` with the same message as GraphQL, e.g. `Bad request: Extension storage is limited to 1000 keys per install`.

The data lives in PostgreSQL (`extension_storage`) and is deleted with the install: immediately on uninstall with `delete_data_immediately`, after the 30-day retention window otherwise, and on account dissolution.

### `GET /v1/extension-installs/{id}/logs`

Returns the newest handler-execution logs (up to 100, newest first) of one bot-module or automation-node install of the caller's active account.

**Auth:** Account auth (JWT, API key, or popout token).

**Permission:** follows the install's extension category — `bot-modules:read` for a bot module, `automations:read` for an automation node. An install of another account, an unknown install, an install of any other category, and a caller without the category's permission all get the same `404` `Install not found`, so the endpoint reveals neither install ids nor categories.

**Path parameter:** `id` - UUID of the extension install.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `since` | RFC 3339 timestamp | Only entries at or after this time |
| `level` | string | Filter by log level: `info`, `warn`, `error` |

**Redaction:** `message` and `stack_trace` are scrubbed of UUIDs, @-mentions, tokens and IPv4 addresses. `args` depends on the category:

- **Bot module** — the positional command arguments, string values scrubbed the same way.
- **Automation node** — `nodeConfig` keeps its values, with every secret-looking key (`key`, `token`, `secret`, `password`, `auth`) masked as `"***"` at any depth; `inputData` (the triggering event: viewer, message, tip, Shopify or custom data) is returned as **shape only** — keys and nesting are kept, every value becomes `"<string>"`, `"<number>"` or `"<bool>"` (`null` stays `null`).

The workers store rows already redacted; rows written before that are redacted when read.

**Response:**

```json
{
  "data": {
    "entries": [
      {
        "time": "2026-10-09T10:30:00+00:00",
        "handler": "onAction",
        "trigger_type": "action",
        "platform": null,
        "level": "info",
        "message": null,
        "stack_trace": null,
        "args": {
          "nodeConfig": { "label": "Tip alert", "webhook_secret": "***" },
          "inputData": { "user": { "name": "<string>" }, "amount": "<number>" }
        },
        "user_name": null,
        "user_role": null,
        "execution_ms": 34,
        "success": true
      }
    ]
  }
}
```

> **Protocol parity:** GraphQL twin `extensionInstallLogs` -- same guard, redaction and error (both call `db::extension_install_logs::read_install_logs`). See [GraphQL](./graphql.md#extension-install-logs).

## Account Bots

The active account's bot list supports `twitch`, `kick` and `youtube`. Responses use the usual `data` envelope and snake_case fields. The [GraphQL twins](./graphql.md#account-bots) enforce the same account-scoped guards and validation.

| Endpoint | Permission | Result |
|----------|------------|--------|
| `GET /v1/account-bots` | `chat-bots:read` | Account entries, newest first: `platform`, `platform_user_id`, `login`, `display_name`, `source`, `added_by`, `added_by_name`, `added_at`. |
| `GET /v1/account-bots/auto-detected` | `chat-bots:read` | Read-only badge, curated-list and own-connection entries with `platform`, `source`, `identity`, `name`. |
| `POST /v1/account-bots` | `chat-bots:edit` | Body: `platform` and exactly one of `platform_user_id` or `name`. A name or `@handle` must resolve before saving. Returns `{ bot, created }` with `201` for an add or `200` and `created: false` for an existing entry. |
| `DELETE /v1/account-bots/{platform}/{platform_user_id}` | `chat-bots:edit` | Returns `{ removed }`; `false` when no entry existed. |

A real add starts background recalculation of retained history sessions. Removing a mark does not restore already recalculated figures. Real changes emit `account:bot_list_updated`; no-op writes do not.

## Stream History

All owner routes require `feature:stream_history` and the permission shown below. The public share routes are anonymous and IP-rate-limited. Structured routes mirror [GraphQL Stream History](./graphql.md#stream-history); the filtered-list file download is REST-only by design.

### `GET /v1/history`

List sessions with `history:read`. `page` defaults to 1; `per_page` defaults to 25 (max 100). Filters `from`, `to` (RFC3339), `session_type` (`single`/`multi`), `platform`, `platforms`, `category`, and `search` combine. `platforms=twitch,youtube` keeps sessions with a broadcast on at least one listed platform; it cannot be combined with `platform`, and `include=sparkline` then sums only the listed platforms. `sort_by` accepts `started_at`, `duration_secs`, `peak_viewers`, `avg_viewers`, `total_messages`, `unique_chatters`, `new_followers`, `new_paid_subs`, or `estimated_revenue`; `sort_dir` is `asc` or `desc` (default date descending). Nullable stats sort last; ties sort newest first. `estimated_revenue` orders by the revenue a row shows (the converted total in `currency`, else the raw estimate), computed over the whole filtered set before paging. Without `history:revenue-read` it is accepted but keeps the default order, so the order never reveals revenue. `include` is a comma-separated set of `sparkline`, `revenue`, `milestones`, `platform_stats`, `shared_chat`; unknown values return `400`. `include=shared_chat` fills `shared_chat` for a session that ran Twitch Shared Chat and omits it otherwise: `host_broadcaster_id` (the host of the newest or running Shared Chat, `null` when unknown), `active` (a Shared Chat of the live session is running now), `channel_count` and `channels` (`platform_channel_id`, `login`, `display_name`, `avatar_url`, `is_host`, `is_own_channel`; host first, then the own channel, then join order). Sessions stored before the Shared Chat timeline list only the partner channels and have no host. `include=platform_stats` fills `platform_stats`: each platform's part of the session (`platform`, `duration_secs`, `peak_viewers`, `avg_viewers`, `new_followers`, `messages`, `paid_subs`, `gifted_subs`). `include=sparkline` fills `viewer_sparkline` (at most 32 total-viewer points, or `null`). `include=revenue` fills `estimated_revenue` only with `history:revenue-read`; otherwise the field is omitted. `include=milestones` fills each session's persisted milestones. Optional `currency` chooses converted revenue currency, defaulting to the user's display currency.

A session summary in the list, report, public share or
`latest_session.session` carries `live` for an unfinalized session started
within the last 48 hours. The object has `computed_at`, nullable `sampled_at`,
`samples`, `chat`, `top_chatters` and nullable `youtube_subscribers`. The state
values are `live`, `unavailable` and `after_stream`. An `unavailable` group
may contain zero or empty-list placeholders; clients must display it as
unknown. YouTube subscriber gain is `after_stream` during a YouTube broadcast.
The session `live` is `null` after finalization or beyond the 48-hour window.
It is distinct from `latest_session.live`, the dashboard snapshot. GraphQL
twin: `HistorySessionSummary.live`.

Every session object (list, report, public share, JSON export) carries `bot_messages` (integer or `null`): the chat messages left out of `total_messages`, `unique_chatters`, the per-platform counts, the top lists and the emote/GIF counts because a bot wrote them. `null` means unknown: the live chat calculation is unavailable, or the session was finalized before bot filtering with its chat log already gone. A live session with a completed chat calculation has a running count. See [Stream History → Bot messages](../features/stream-history.md#bot-messages). GraphQL twin: `botMessages`.

`?shared_chat=with|without` filters sessions that have or never had Twitch
Shared Chat, including live sessions. It combines with the other history
filters and applies to the overview, trend, heatmap and list export. Invalid
values return the same bad-request message as GraphQL `sharedChat`; filter
options expose `has_shared_chat`. No additional permission is required.

### `GET /v1/history/overview`

Return totals, platform counts, month summaries, and activity days with `history:read`. Uses the list filters and optional `time_zone` (IANA; UTC default) and `currency`. A session is grouped by its start in that zone. `months` spans the filtered set; `days` contains today plus the preceding 370 days and ignores `from`/`to` while honoring other filters. An invalid zone is `400`. `estimated_revenue` and `months[].revenue` require `history:revenue-read` and are otherwise absent. GraphQL twin: `channelHistoryOverview`.

`range=today|7d|30d` uses local day boundaries in `time_zone` and fills `range` (`key`, `from`, `to`, `previous_from`, `previous_to`), `current` and `previous` KPIs (`sessions`, `total_duration_secs`, `avg_viewers`, `new_followers`, `messages`, `new_paid_subs`, `gifted_subs`), plus a zero-filled daily `kpi_series`. The overview's existing totals and estimated revenue cover the selected range; `days` still spans 371 days. Combining `range` with `from` or `to` returns 400. `latest_session` always refers to the account's newest session, ignoring filters, and includes `session`, up to 60 `viewer_series` points per platform, `live` sampled totals and `milestones`; it is `null` without sessions. GraphQL computes it only if selected.

`platforms=twitch,youtube` (comma-separated `twitch`, `youtube`, `kick`) is the share filter. It keeps only sessions with a selected platform and counts only the selected platforms' share in the totals, `months`, `days`, `current`, `previous` and `kpi_series`. A session whose every platform is selected keeps its own values, so listing all platforms gives the unfiltered result. Otherwise the stream time is the time at least one selected platform was live. Ø viewers are the selected platforms' stream averages weighted by their live time and divided by that stream time, so concurrent platforms add up. The peak is the sum of their stream peaks. Followers, messages, Subs + Members and gifted Subs come from their `platform_breakdown` entries, and YouTube followers are the subscriber delta. `platforms` in the response lists only the selected ones. `estimated_revenue` and `months[].revenue` cover the whole sessions. `latest_session` becomes the newest session with a selected platform. Its `viewer_series`, `viewer_total` (the combined curve: per bucket the highest per-minute cross-platform sum, on the `viewer_series` bucket times), `live` and follower marks cover only those platforms, while tips stay session-wide, and its `session` carries `platform_stats`. An empty value means no filter. Combining it with `platform` returns 400 `` `platforms` cannot be combined with `platform` ``. An unknown platform returns 400 `` `platforms` must only contain: kick, twitch, youtube ``. Both messages are identical on GraphQL.

`latest_session.shared_chat_series` contains `total` (the highest concurrent
own-plus-partner sum per viewer-series bucket) and `channels` (one partner
curve each, with channel identity and points). A missing partner count makes
a gap, not zero. It is null without Shared Chat, when Twitch is excluded or
after raw samples age out. `latest_session.live.shared_chat` gives
`host_broadcaster_id`, host-first `participants`, `partner_viewers`,
`total_viewers`, `partner_messages`, `session_chat_per_min` and `source`
(`state` or `sample`). The session chat rate adds own and partner messages
over the two latest Twitch samples. It is null until the second sample, never
the own `chat_per_min` as fallback. GraphQL twins:
`latestSession.sharedChatSeries` and `latestSession.live.sharedChat`.

`latest_session.live` has `sampled_at`, `currency`, `viewer_count`, `peak_viewers`, `messages_total`, `chat_per_min`, `new_followers`, `paid_subs`, `gifted_subs`, `bits`, `kicks`, `superchats`, `superstickers`, `tips` and `platforms`. Each money kind has `count`, `by_currency`, `unknown_cents` and `converted_cents`; conversion is `null` if a part has no currency or rate. Tips are session-wide. `chat_per_min` uses the newest two probes; `live` is `null` before the first sample.

### `GET /v1/history/milestones`

Return up to 1,000 persisted milestones under `history:read` and `feature:stream_history`, oldest first. RFC3339 `from` is inclusive and `to` exclusive; reversed bounds return 400. `platforms=twitch,youtube` keeps only those platforms' follower marks; the cross-platform records (`platform: null`) stay, and an unknown platform returns 400. Each item has `id`, `session_id`, `kind` (`viewer_record`, `sub_record`, `biggest_raid`, `follower_mark`), `platform`, `value`, `previous`, and `achieved_at` (session start). The report's `session.milestones` is always present. GraphQL twin: `channelHistoryMilestones(from, to, platforms)`.

### `GET /v1/history/filter-options`

Return the account's distinct `platforms` and `categories` with `history:read`. GraphQL twin: `channelHistoryFilterOptions`.

### Tracked keywords

All keyword endpoints require `feature:stream_history`. Reads and pattern tests need `history:read`; writes need `history:keywords-edit`. Their [GraphQL twins](./graphql.md#stream-history) use the same account-scoped guards, matcher and errors.

| Endpoint | Result |
|----------|--------|
| `GET /v1/history/keywords` | `keywords` (oldest first), `last_session_id`, `last_session_started_at`, `max_keywords` (50). Each entry includes `id`, `keyword`, `match`, `case_insensitive`, `added_by`, `added_by_name`, `added_at`, `last_stream_count`; the last count is `null` when unknown. |
| `POST /v1/history/keywords/test` | Body: `pattern`, `match`, optional `case_insensitive`, `sample` (at most 500 characters). Returns `valid`, `error`, and `matches` with UTF-16 `start`/`end` offsets and `text`; saves nothing. More than 30 calls per minute returns `429`. |
| `POST /v1/history/keywords` | Body: `keyword`, `match`, optional `case_insensitive`. Returns `keyword`, `created`, `changed`; `201` for a new entry, `200` with `created: false` for a duplicate term and mode. |
| `PUT /v1/history/keywords/{id}` | Same body and payload; `changed: false` for an unchanged entry, `404` for an unknown id, `409` for a duplicate. |
| `DELETE /v1/history/keywords/{id}` | Returns `removed: false` when the entry was absent. |

`match` is `word`, `contains` or `regex`; matching ignores case by default. Text modes permit 100 characters. Regex permits 200 characters, rejects empty-text matches and compiles with a 1 MiB size limit. At most 50 entries may be stored. Real writes emit `account:history_keywords_updated` and recount finalized sessions with complete chat logs in the background.

### `GET /v1/history/revenue-settings` and `PUT /v1/history/revenue-settings`

Read the account's revenue assumptions with `history:revenue-read`; when none are saved, the read returns defaults with `updated_at`/`updated_by` null. The response includes `fixed_values`, a read-only list of USD `item`, `amount_cents`, `currency`, `share`, `source`, `source_url` and `note` for Twitch tiers, Prime, Bits, Kick subs and KICKs. Unit prices for these items are not writeable. Both operations also require `feature:stream_history`.

The `PUT` requires `history:revenue-edit`. Send `currency`, `twitch_share_bps`, `kick_share_bps`, `twitch_ad_cpm_cents`, `twitch_ad_share_bps`, and `twitch_ad_free_viewer_bps`. Optional fields are `youtube_share_bps` (Super Chats), `youtube_supersticker_share_bps`, `youtube_membership_share_bps`, `youtube_member_levels` (`[{"name":"Fan","price_cents":499}]`), `kick_ad_cpm_cents`, `kick_ad_share_bps`, `kick_ad_free_viewer_bps`, `youtube_ad_cpm_cents`, `youtube_midrolls_per_hour`, `youtube_ad_share_bps` and `youtube_ad_free_viewer_bps`. All shares are 0–10,000 basis points; money inputs are 0–1,000,000 cents; the mid-roll rate is 0–60 per hour; currency is EUR or an ECB reference currency. The three YouTube creator shares default to 7,000 basis points when omitted. Omitting `youtube_member_levels` keeps the saved list; an empty list clears it. Omitting a Kick or YouTube ad field keeps its saved value; explicit `null` clears a nullable CPM or the mid-roll rate. `twitch_ad_cpm_cents: null` leaves Twitch ads without an amount. At most six membership levels are accepted, with trimmed, non-empty names of at most 100 characters that are unique ignoring case. GraphQL twins: `channelHistoryRevenueSettings` and `updateChannelHistoryRevenueSettings`, with the same validation.

### `GET /v1/history/youtube-revenue/status`

Return the account's YouTube Analytics state without amounts. The response data has `connected` (boolean), `status` (`not_connected`, `not_granted`, `not_in_ypp`, `api_disabled`, `unchecked`, or `ok`), nullable `ypp_checked_at`, and nullable `revenue_auth_verified_at`. It requires `history:revenue-read` and `feature:stream_history`; GraphQL twin: `channelHistoryYoutubeRevenueStatus` with camelCase fields.

### `GET /v1/history/revenue-settings/youtube-member-level-suggestions`

Return up to 50 level names from retained YouTube membership events, most frequent first. Each item has `name`, `events`, `last_seen_at` and `entered` (whether that name is already priced, ignoring case). The account-scoped read requires `history:revenue-read` and `feature:stream_history`. GraphQL twin: `channelHistoryYoutubeMemberLevelSuggestions`.

### `GET /v1/history/reports/{id}`

Return one owned report with `history:read`; optional `currency` controls `session.display_money` and converted revenue. `session.display_money` (`currency`, `donations_cents`, `superchats_cents`, `superstickers_cents`, `rate_date`) converts donations, Super Chats and Super Stickers at the stream-date rate and needs no revenue permission; an amount without a rate (or a known currency) is `null`, and the source amounts stay in `donations_total_cents` / `donations_currency` and `platform_metrics`. On the public share payload its amounts are `null` and `currency` is the link currency. The response includes the session, per-platform streams, chart markers, top lists (`top_emotes` holds up to 20 entries, `top_chatters` and `top_gifs` up to 10; a report keeps the list length it was finalized with), and Twitch `ad_breaks` (`started_at`, `duration_secs`, `automatic`, `viewers_start`, `viewers_after`) plus `ad_stats` (break counts, total/average/min/max seconds, minutes per hour, threshold, estimated impressions, viewer change). `session.estimated_revenue` requires `history:revenue-read` and is otherwise absent. The revenue object contains `currency`, `total_cents`, `lines`, `unpriced`, `actuals`, `grand_total`, and `averages`. A line's `converted` value has `amount_cents`, `currency`, `source_amount_cents`, `source_currency`, `rate`, `rate_date`, and `convertible`. `grand_total` separates estimated and actual cents and lists `not_convertible` amounts. Missing ECB rates within seven days leave an amount in its original currency, outside converted totals. Each stream carries its metadata timeline: `tags` (string list, the tags at stream end, deduplicated, in platform order), `category_changes` (`[{ at, category, category_id }]`, ascending; the first entry is the category at stream start with `at` = the stream's `started_at`, then one entry per category change inside the stream) and `title_changes` (`[{ at, title }]`, same rules). Twitch and Kick fill them from their `stream_update` events and the live tag polls; YouTube returns empty lists, as does any stream whose values were never observed. The finalizer freezes the timeline into the report, so it survives the event-log retention; a live stream derives it on read. A Twitch stream with a Shared Chat also has `shared_viewers_peak` / `shared_viewers_avg` (peak and average of the per-bucket total of own viewers plus partners; `null` without a Shared Chat) and `shared_chat_sources`: `[{ platform_channel_id, message_count, login, display_name, avatar_url, peak_viewers, avg_viewers, active_from, active_to }]`, ordered by `active_from`, then `message_count` descending; `null` without a Shared Chat. The report also carries `links`, `commands` and `keywords` (at most 50 entries each; `null` = unknown, when neither a frozen list nor the complete chat log exists). A link has `url` (normalized), `display` (as first posted), `domain`, `count`, `first_seen_at`, `last_seen_at`, `posters` (top 5: `platform`, `user_id`, `login`, `display_name`, `count`, `is_bot`), `other_posters`, `occurrences` (first 100, oldest first: `at`, `platform`, `user_id`, `login`, `display_name`, `is_bot`) and `occurrences_truncated`; bot posters are included and flagged. A poster or occurrence of an erased chatter (and an erased `top_chatters` entry) carries `erased: true` with `user_id` `null` and empty `login` / name; the key is absent on every other entry ([Stream History → Erased chatters](../features/stream-history.md#links-and-commands)). A command has `name` (prefix + lower-cased name, e.g. `!discord`), `prefix`, `count`, `unique_users`, `first_seen_at`, `last_seen_at`, `posters`, `other_posters`, `top_args` (`[{ args, count }]`, `""` = no arguments), `occurrences` (as for links, plus `args`), `occurrences_truncated` and `known`; bot authors are left out. See [Stream History → Links and commands](../features/stream-history.md#links-and-commands). The public share payload carries the same stream fields and samples. `keywords` contains one row for every tracked keyword, including count zero: `keyword_id`, `keyword`, `match`, `case_insensitive`, `count`, `bot_count`, `unique_users`, `first_seen_at`, `last_seen_at`, `posters`, `other_posters`, `occurrences` and `occurrences_truncated`. Bot posts count and are flagged. A leading command token that matches a keyword counts as a keyword rather than a command. `null` means no frozen list and no complete chat log. GraphQL twin: `channelHistoryReport`.

For a Twitch stream, `shared_chat_timeline` contains the host and the
event-exact session/channel spans, frozen with `shared_chat_sources` at
finalization. Older streams without transition events use minute-sample
boundaries. `shared_chat_insights` contains frozen per-partner activity;
partner keyword, link and command entries hold term and count only, without
poster identities or occurrences. Own-channel chat and all revenue fields
remain scoped to the own channel. The public share omits Whole session
insights and timeline viewer figures.

On an owned report, `session.estimated_revenue.youtube_analytics` contains `status` (`not_granted`, `not_in_ypp`, `api_disabled`, `pending`, `provisional`, or `final`) and nullable `fetched_at`. It is absent or `null` without a YouTube stream and omitted from public shares. `pending` retains the Lumio estimate. With `provisional` or `final`, the lines `youtube_analytics_ads`, `youtube_premium`, and `youtube_transactions` replace YouTube ad and membership estimates and Super Chat/Sticker amounts; `youtube_transactions` is derived from YouTube's reported total. The `note` is `youtube_analytics` or `derived_from_analytics`. The account read needs `history:revenue-read`; the public share report and export use only Lumio's estimate, including the total.

The report also returns `announcements` and `pins` (at most 500 and 200, oldest first), with `announcements_captured`, `pins_captured`, `announcements_truncated` and `pins_truncated`. The capture flags distinguish a session that began before collection from one with zero entries. `null` lists mean unknown or not shared. A pin carries `sender`, `pinned_by`, `planned`, `changes`, `duration_seconds`, `approx`, and `end_reason` (`expired`, `unpinned`, `replaced`, `message_deleted`, `stream_end`, `ran_past_stream_end`, `unknown`, `active`). The lists retain person, time and message ID but do not freeze message text. `text_stored: false` calls for **Text no longer stored**. The GraphQL twin uses camelCase.

### `GET /v1/history/reports/{id}/automod`

The messages Twitch AutoMod held during the session, oldest first, with counts per outcome. Requires `history:read` **and** `chat:automod-read` (a missing one is `403 Missing permission: …`, like GraphQL) and `feature:stream_history`; popout tokens get `403 Popout tokens cannot read the AutoMod log`. Query: `outcome` (`open`, `approved`, `denied`, `expired`; default all), `after` (the previous page's `next_cursor`), `first` (1–100, default 50); anything else is `400`. `data: null` means unavailable: the session has no Twitch broadcast, or it started before the chat retention window. A foreign or unknown session is `404 History session not found`.

`text_retention_days` is the account's effective chat window in days: the entry, text included, is deleted that many days after the hold. Each entry carries `message_id`, `sender` (`user_id`, `login`, `display_name`, and the look at hold time `avatar_url`, `color`, `badges`; `null` = unknown), `text` and `flagged_spans` (code points, `end` inclusive), `emotes` (JSON array in the chat-message `emotes` shape: Twitch emotes `{id, name, url, provider: "twitch", animated}` and cheermotes `{kind: "cheermote", …}`; `null` when none; a cheer the channel's cheermote catalog does not know stays plain text), `text_state` (`stored`, or `not_stored` above the 4 KiB size cap), `reason_kind` and `reason` (`category`, `level`, `terms[{term_id, text}]`), `outcome`, `resolved_via` (`lumio`/`twitch`), `moderator_login`, `moderator_name`, `held_at`, `resolved_at`. A hold nobody decided reads `expired` once the queue TTL has passed, with no moderator and no `resolved_at`. `counts` (`total`, `open`, `approved`, `denied`, `expired`) cover the whole session, independent of `outcome`. The log is never part of the report, share links or exports. GraphQL twin: `automodLog`.

### `GET /v1/history/reports/{id}/stats`

Time-series samples for a session, optionally restricted by `platform`. Requires `history:read`. `live_counters` separates cumulative `gifted_subs`, `bits`, `kicks`, `superchats`, `superstickers` and `tips`; money kinds carry `count`, `by_currency` and `unknown_cents`. Older samples have `live_counters: null`. Tips are session-wide, repeated on each platform sample of the same tick and never summed across platforms. A Twitch sample during a Shared Chat also carries `shared_viewers` (own Twitch plus all partners in that bucket; `null` otherwise) and `shared_chat_viewers` (`[{ platform_channel_id, viewer_count }]`, `[]` outside a Shared Chat). A partner missing from a bucket was not in the Shared Chat then; `viewer_count: null` means it was in it but not live. GraphQL twin: `channelHistoryStats` (`liveCounters`, `sharedViewers`, `sharedChatViewers { platformChannelId viewerCount }`).

### `GET /v1/history/export`

Download the **filtered list** with `history:export`. `format=csv|json`; accepts the same list filters and sorting, plus `time_zone`, `currency`, and `locale`. Maximum 5,000 sessions. CSV is a ZIP containing `streams.csv`, `months.csv`, and `totals.csv`. Revenue columns appear only with `history:revenue-read`. This file-download endpoint intentionally has no GraphQL twin.

### `GET /v1/history/reports/{id}/export`

Download a finalized report with `history:export`. `format=pdf|csv|txt|json`; optional `locale`, `time_zone`, and `currency` set language, dates, and converted amounts. PDF has up to four A4 sections (Overview, Timeline, Revenue & Ads, Chat & Streams) with page headers/footers; empty sections drop out. TXT has the same sections. CSV is a ZIP of report tables, including `revenue.csv` and `ad_breaks.csv` when applicable, and `links.csv` / `link_posts.csv`, `commands.csv` / `command_posts.csv`, and `keywords.csv` / `keyword_posts.csv` when the report carries those lists, plus `announcements.csv` and `pins.csv` when present (times in `time_zone`). `pins.csv` keeps `planned_seconds` and `duration_seconds` as numbers and adds `duration`, the real duration worded in the export language. PDF and TXT word pin durations the way the dashboard does: seconds or minutes under an hour (`12:04 Min.`), hours and minutes from one hour (`1 Std. 8 Min.`), days and hours from one day (`2 Tage 20 Std.`), rounded down. JSON keeps API field names and includes export metadata. Donations, Super Chats and Super Stickers are in the export currency without a revenue permission: the PDF overview lists them, CSV `summary.csv` adds `display_currency`, `display_rate_date`, `*_display_cents` and `*_source` (source amounts per currency), and JSON carries `session.display_money`. Revenue requires `history:revenue-read`. A live session returns `409`. GraphQL `exportHistoryReport` validates the same request and returns this download URL.

### `DELETE /v1/history/reports/{id}`

Delete a stored, finalized session and its share links with `history:delete`. Returns `204`. A session that is not finalized yet (live, in its grace window or waiting for the finalizer) is refused with `409` `This stream session is still live; it can be deleted once it is finalized` and nothing is deleted; GraphQL `deleteChannelHistory` returns the same code and text.

### `GET /v1/history/reports/{id}/shared-links`

List link metadata with `history:share`: expiry, active state, `options`, and `legacy_options`, but never the full token.

### `POST /v1/history/reports/{id}/shared-links`

Create a link with `history:share`. Body has `duration_secs` (3600, 21600, 86400, 604800, or 2592000), optional `password`, `allow_export`, and `options`. `options` accepts `sections` (`chat`, `top_chatters`, `ads`, `revenue`, `links`, `commands`, `keywords`, `announcements`, `pins`), `include_revenue`, and `currency`. `links`, `commands`, `keywords`, `announcements` and `pins` are off unless listed; without them the corresponding public report lists are `null` and the public export leaves those sections out. A revenue option also requires `history:revenue-read`; otherwise both protocols reject it. Omitted options give the legacy view (chat and top chatters; no ads, revenue, links, commands, keywords, announcements or pins). New links with options default to chat and ads, no revenue, links, commands, keywords, announcements or pins. Maximum 20 active links per report. The response returns the plaintext token and URL once.

### `PATCH /v1/history/shared-links/{id}` and `DELETE /v1/history/shared-links/{id}`

Extend a link with `{ "duration_secs": … }` or revoke it, respectively. Both require `history:share`; extending a link that shares revenue also requires `history:revenue-read` (`403`, same message as GraphQL). Delete returns `204`.

### `GET /v1/history/shared/{token}`

Resolve a public link. The response contains the permitted report sections, time-series samples, `options`, `channel` (`display_name`, `avatar_url`, `platform`), `expires_at`, and `allow_export`. A shared sample carries only its time, platform, viewers (`shared_viewers` / `shared_chat_viewers` included), message, follower and sub totals and the money-free `platform_metrics` counts: `donations_total_cents` is `0` and `live_counters` is `null`, with or without `include_revenue`. The shared `top_chatters` and the posters and occurrences of `links`, `commands` and `keywords` are served as frozen, without a read-time chatter mask: chatters the channel had erased appear blanked (`erased: true`, counts kept) because the instructed erasure scrubbed the stored sessions and the channel's suppression list (`account_chatter_suppressions`) blanks them in sessions frozen afterwards. Lumio's global list (`chatter_suppressions`, objections) does not apply to share links. Send a protected link's password in `X-Share-Password`, never the URL. A locked link answers with exactly one of two fixed responses, identical within each class (status, body and headers):

| Case | Status | `error` | `message` |
|------|--------|---------|-----------|
| Malformed, unknown, expired or revoked token | `410` | `SHARE_UNAVAILABLE` | `This share link is no longer available` |
| Active link with a password; password missing or wrong | `401` | `SHARE_PASSWORD_REQUIRED` | `A valid password is required to open this share link` |

The body is `{ "error": …, "message": … }` with nothing about the link: no title, channel, date or expiry. Expiry and revocation are checked before the password, so a dead protected link returns `410` and never asks for a password.

After 10 wrong passwords on one link, or 20 from one client IP, within 15 minutes, a protected link returns `429 RATE_LIMIT_EXCEEDED` to every password attempt until the window ends, including the correct one; a correct password never counts. Attempts are counted before the password is checked, so simultaneous requests cannot exceed the limit, and an IPv6 client is counted per `/64` network. The endpoint is also rate-limited per end-user IP, including when the web app proxies it (see [Authentication → Rate Limits](./authentication.md#rate-limits)), and returns `503` rather than going unthrottled while the rate limiter is unavailable. The public page at `/share/history/{token}` reveals no report metadata until unlocked.

### `GET /v1/history/shared/{token}/export`

Download a shared report when `allow_export` is true, with the same four formats, link section restrictions and frozen chatter lists as the shared read. A protected link needs `X-Share-Password`; optional `locale` and `time_zone` choose output language and date zone (default from `Accept-Language` and UTC). A locked link gets the same `410 SHARE_UNAVAILABLE` / `401 SHARE_PASSWORD_REQUIRED` / `429` responses as the shared read, and shares its password lockout; an open link with `allow_export` off returns `403`.

## Public Stats

Per-channel publicness for the public Stats app. All endpoints require the
`feature:public_stats_page` flag and mirror the GraphQL `channelPublicSettings`
query / `setChannelPublicSettings` mutation exactly (same fields, guards,
validation and errors). Publicness is **opt-out / public-by-default**: a channel
with no settings row is public.

### `GET /v1/public-stats/channels`

List the account's connected channels with their current publicness settings.
Permission: `public-stats:read`. Each entry: `platform`, `platform_channel_id`,
`channel_name`, `is_public`, `show_top_chatters`, `opted_out_via`, `updated_at`.
Channels default to `is_public: true` (opt-out) but `show_top_chatters: false`
(the chatter leaderboard is opt-in - hidden until the broadcaster enables it)
until changed.

### `PUT /v1/public-stats/channels/{platform}`

Toggle a channel's publicness (channel listing opt-out; chatter leaderboard
opt-in). Permission: `public-stats:edit`. Body: `{ "is_public": bool,
"show_top_chatters": bool }`. The channel is resolved to the caller's own
connected channel for `platform` (the channel id is never taken from the client),
so an account can only change a channel it has connected. A missing connection →
`404`; an unsupported platform or a connection whose channel identity is not yet
resolved → `422`. Emits a `public_stats:channel_opted_{out,in}` audit event.

### Public read model (unauthenticated)

The read surface the public Stats app consumes. **No token required** (anonymous,
`OptionalAuth`) and **no per-user data**, so responses are cache-friendly. Gated
globally by the `system:public_stats` kill-switch flag - disabled → `403`. Mirrors
the GraphQL `publicChannelStats` / `publicStreamStats` queries exactly. Serves
**only** the §5 public-safe field set: there is no field for donations,
subscriber/gifter identities, revenue splits, or the raw `platform_metrics` /
`platform_breakdown` JSONB. First-party and crawled rows use the same response
shape, distinguished only by the `source` badge (`first_party` / `external_crawler`).

#### `GET /v1/public-stats/channels/{platform}/{channel}`

A channel's public aggregate, matched by the stable `(platform,
platform_channel_id)` and addressed by the URL handle (`channel` =
`channel_login`, case-insensitive). Returns `platform_channel_id`,
`channel_display_name`, `source`, `stream_count`, `total_duration_secs`,
`peak_viewers`, `avg_viewers`, `total_messages`, `last_streamed_at`,
`broadcaster_type` (Twitch channel type: `"partner"` / `"affiliate"`, else
`null` - no badge; ZAF-841), and `recent_streams` (public stream summaries). A
channel that has **opted out** (`is_public = false`) or has no addressable
streams → `404`. An unsupported platform → `400`.

#### `GET /v1/public-stats/channels/{platform}/{channel}/profile-history`

A channel's **About-box change timeline** (ZAF-836) - bio / social-link / team
changes over time, most-recent first. Query params `limit` (default 50, max 200)
and `offset` (default 0) paginate. Each entry: `change_type` (`bio` / `link` /
`team`), `old_value` / `new_value` (opaque JSON - a string for `bio`, an array
for `link` / `team`; `null` old = initial capture, `null` `bio` new = deletion),
and `changed_at`. Mirrors the GraphQL `publicChannelProfileHistory` query exactly.
A channel that has **opted out** or has no addressable streams → `404`;
unsupported platform → `400`. Public data (founder ruling ZAF-791): no §5
minimisation, no retention cap. The separate `/{channel}/history` page reads this
via `publicGql` (SSR) and is `noindex, follow`;
there is no WebSocket surface.

#### `GET /v1/public-stats/channels/{platform}/{channel}/trends`

A channel's **"Stats"-tab trends** (ZAF-891) - the follower-growth line and the
average-viewers-over-time line. Required query param `range` ∈
`DAYS_30 | DAYS_90 | DAYS_180 | DAYS_365` selects the rolling window; an unknown
value → `400`. Returns `follower_series` (dated follower-total growth) and
`avg_viewer_series` (dated average viewers), each an oldest-first list of day
points: `follower_series` items are `{ date, follower_count }`, `avg_viewer_series`
items are `{ date, avg_viewers }`, with `date` = `YYYY-MM-DD` (UTC). Follower points
are the last recorded follower total per day (dated crawler snapshots); avg-viewer
points are the exact sample-weighted daily mean from the `channel_history_stats_1h`
aggregate scoped to the channel's own sessions. Mirrors the GraphQL
`publicChannelTrends` query exactly. A channel that has **opted out** or has no
addressable streams → `404`; unsupported platform → `400`. Either series is an
empty list (`[]`) when the channel has no history in the window. Aggregate counts
only - no viewer identities. Read via `publicGql` (SSR); no WebSocket surface.

#### `GET /v1/public-stats/channels/{platform}/{channel}/panel-history`

A channel's **ad-panel lifecycle + image-change history** (ZAF-892) for the
"Placements" tab - the ad-marked panels grouped by panel, most-recently-active
first. Each entry: `panel_id`, latest content (`title` / `description` /
`image_url` / `link_url`), full span (`first_seen_at` / `last_seen_at`), lifecycle
(`status` = `"active"` / `"removed"`, `removed_at`), and
`images: [{ image_url, first_seen_at, last_seen_at }]` - the distinct image
versions over time, oldest-first (the slideshow). Mirrors the GraphQL
`publicChannelPanelHistory` query exactly. A channel that has **opted out** or has
no addressable streams → `404`; unsupported platform → `400`; a channel with no
ad-marked panels → `200` with an empty list. `image_url` is the Twitch CDN URL; the
Stats page shows it through its [image proxy](../developer-guide/image-proxy.md). The channel page renders current active panels only; the
`noindex, follow` `/{channel}/history` page renders removed panels and earlier
artwork. Public data: no §5 minimisation, no retention cap; read via `publicGql`
(SSR), no WebSocket surface.

### Sitemap and share-card reads (unauthenticated)

These routes mirror the GraphQL `publicSitemapChannelPageCount`,
`publicSitemapChannels` and `publicChannelCard` queries. No token or RBAC
permission is required. The account-less `system:public_stats` kill switch is
their only gate. When it is off, the count is `0`, a page is `[]`, and the card
is `404 Channel not found`, the REST equivalent of GraphQL `null`.

| Route | `data` in the REST envelope |
|-------|-----------------------------|
| `GET /v1/public-stats/sitemap/channels` | `{ "page_count": number }`, `ceil(candidate channels / 45000)`. Opt-outs are not subtracted from the count, so the final file can be short or empty. |
| `GET /v1/public-stats/sitemap/channels/{page}` | Up to 45,000 `{ platform, channel_login, lastmod }` entries. `page` starts at 0; past the end returns `[]`, while a negative page returns `400` with `page must not be negative`. `lastmod` is the most recent stream-start date, UTC `YYYY-MM-DD`. |
| `GET /v1/public-stats/channels/{platform}/{platform_channel_id}/card` | One card by stable platform channel ID, not by handle. Unknown, opted-out and disabled all return `404 Channel not found`. Unsupported platform returns `400 Unsupported platform: <p>`; an ID outside 1–64 ASCII letters, digits, `_` or `-` returns `400 Invalid platform channel id`. |

The sitemap includes only channel pages on `public_stats.sitemap_platforms`
(default `twitch,kick`) with a login and a stream start in the last 12 months. It
checks opt-outs at read time; clients cannot expand the platform allowlist.
The card checks visibility on each hit. Both sitemap routes return
`Cache-Control: public, max-age=3600, s-maxage=86400` on `200`; the card returns
`public, max-age=600, s-maxage=900, stale-while-revalidate=300` on `200`.

The card has exactly 13 snake_case fields: `platform`, `platform_channel_id`,
`channel_login` (current canonical handle), `channel_display_name`, `is_live`,
`current_viewers`, `follower_count`, `stream_count`, `avg_viewers`,
`peak_viewers`, `watch_seconds` (viewer-seconds), `last_category`, and
`last_streamed_at` (RFC 3339). Unavailable figures are `null`, never zero. No
chatter identity, profile text or change history is present.

#### `GET /v1/public-stats/streams/{platform}/{broadcast_id}`

One stream by its public key `(platform, broadcast_id)`. Returns the stream
`summary`, `emote_count`, `top_emotes`, `gif_count` **and** `top_gifs` (ZAF-968 —
`top_gifs` is `[{ id, url, provider, alt, count }]`, the GIF twin of `top_emotes`;
on the public-stats crawler path `provider`/`alt` are `null`, and both fields are
erased after the 90-day GIF-content retention), de-identified `new_paid_subs` /
`gifted_subs` **counts**, `new_followers`, the `viewer_curve` timeseries, and
`top_chatters` **only** when the channel opted the leaderboard in
(`show_top_chatters = true`) - otherwise `null`. Chatters the channel had erased
appear blanked as frozen; chatters on Lumio's global list (`chatter_suppressions`:
Lumio-level erasures and objections) are blanked in `top_chatters` on read
(`erased: true`, count kept), also on streams frozen before the objection; if
that lookup fails,
`top_chatters` is `null` and the rest of the page is still served. An unknown
stream or an opted-out channel → `404`; unsupported platform → `400`.

Every public stream `summary` (both here and in the channel endpoint's
`recent_streams`) carries `shared_chat_sources` (ZAF-819): a list of
source-channel message counts. It also carries `shared_chat_sessions`: the
public host and participation timeline for a first-party stream. Crawled
streams without EventSub session events return an empty list. No viewer counts
or individual viewer identities occur in that timeline. GraphQL twin:
`PublicStreamSummary.sharedChatSessions`.

`shared_chat_sources` is a list of
`{ platform_channel_id, message_count, display_name, avatar_url }` naming which
**source channels** contributed Twitch **Shared Chat** messages to that broadcast,
and how many each did - so the stream page can show "who these stats are coming
from". `display_name` + `avatar_url` (ZAF-868) are the source channel's public
identity, resolved from the crawler channel-profile store; both are `null` when the
anonymous crawler never captured that channel's identity (fail-open - the client
falls back to the id). Shared-chat messages are attributed to their source channel
rather than counted toward the host, so the host's `message_count` /
`unique_chatters` reflect only its own channel's chat. The list is empty for a
normal (non-shared) broadcast. Attribution is by **channel** (public broadcaster
identity), never by viewer - aggregates only.

#### `GET /v1/public-stats/streams/{platform}/{broadcast_id}/metadata-history`

A broadcast's **stream-metadata change timeline** (ZAF-890) - title / category /
tags changes over time, most-recent first. Query params `limit` (default 50, max
200) and `offset` (default 0) paginate. Each entry: `change_type` (`title` /
`category` / `tags`), `old_value` / `new_value` (opaque JSON - a string for
`title` / `category`, an array of tag strings for `tags`; `null` old = initial
capture, `null` new = emptied field / all tags removed), and `changed_at`. Mirrors
the GraphQL `publicStreamMetadataHistory` query exactly. An unknown stream or an
opted-out channel → `404`; unsupported platform → `400`. Public data (founder
ruling ZAF-791/ZAF-794): no §5 minimisation, no retention cap.

### Cross-channel browse (Form B)

Browse/rank **across all channels** - the metric nav, a Games directory, and
channel search. **No auth**; gated by the account-less `system:public_stats`
kill-switch; edge-cacheable (`Cache-Control` on the 200). Opted-out channels are
excluded. Mirrors the GraphQL `publicChannelBrowse` / `publicGames` queries
exactly. No WebSocket surface (a browse/search directory has no live-push
consumer).

#### `GET /v1/public-stats/browse`

Ranked channel list. Query parameters (all optional): `platform`, `category`
(Games filter), `metric` (`watchtime` (default) / `viewers` / `peak` /
`follower_gain` / `messages` / `recent`), `live` (bool - `true` = only live,
`false` = only offline), `search` (case-insensitive substring on the channel
handle + display name), `page` (1-based, default 1), `limit` (clamped `1..=100`,
default 50). An unknown `metric` → `400`.

Response `data`: `{ "channels": [ { platform, platform_channel_id,
channel_login, channel_display_name, source, last_category, is_live,
stream_count, watch_seconds, avg_viewers, peak_viewers, total_messages,
follower_gain, last_started_at, broadcaster_type } ], "pagination": { page,
limit, total, total_pages, total_capped } }`. `watch_seconds` = Σ avg-viewers·duration;
`follower_gain` = Σ new-followers (absolute follower total is not a browse metric - see the feature doc); `broadcaster_type` is the Twitch channel type (`"partner"`
/ `"affiliate"`, else `null`; ZAF-841). Timestamps are RFC-3339.

#### `GET /v1/public-stats/games`

Games directory. Query parameters (all optional): `platform`, `search`
(case-insensitive substring on the category name), `page`, `limit` (same
clamping). Response `data`: `{ "games": [ { category, channel_count,
stream_count, live_stream_count, peak_viewers, watch_seconds, last_started_at } ],
"pagination": { page, limit, total, total_pages, total_capped } }`.

**Depth cap (both endpoints).** A browse pages at most 10 000 rows deep: `page`
is clamped so the page starts before row 10 000, and the returned `page` is the
clamped value. `total` counts at most 10 000; `total_capped` is `true` when more
rows match (render `total` as "10 000+"). Same cap and fields on GraphQL.

### Cross-channel placements (`/partners`)

#### `GET /v1/public-stats/placements`

Active, broadcaster-marked advertising panels of every public channel, grouped
by advertiser (the panel link's host, lower-cased, leading `www.` stripped).
**No auth**; gated by the `system:public_stats` kill-switch; edge-cacheable
(`Cache-Control` on the 200). Opted-out channels are excluded. Mirrors the
GraphQL `publicPlacementsBrowse` query exactly - same fields, validation and
error messages. No WebSocket surface.

Query parameters (all optional): `platform` (default and only supported value
`twitch`), `domain` (one advertiser), `sort` (`channel_count` (default) /
`last_seen`), `after` (the previous page's `next_cursor`), `limit` (advertisers,
clamped `1..=100`, default 25), `placements_limit` (per advertiser, clamped
`1..=50`, default 10). `400` for an unknown `sort`, an unsupported `platform`
(`Unsupported platform: …`) or an invalid / other-sort cursor (`Invalid cursor`).

Response `data`: `{ "advertisers": [ { domain, channel_count, placement_count,
first_seen_at, last_seen_at, "placements": [ { platform, platform_channel_id,
channel_login, channel_display_name, avatar_url, panel_id, title, image_url,
link_url, first_seen_at, last_seen_at } ] } ], "next_cursor", "has_more" }`.
Timestamps are RFC-3339.

## Watchlist

Per-user **favourite-channel** list for the public Stats app. Unlike the public
read model above, this is an **authenticated per-user** surface - scoped to the
signed-in Lumio-ID viewer (JWT `me`), with **no account/RBAC permission** and **no
plan gate** (a favourite is a personal preference). Mirrors the GraphQL
`myWatchlist` query / `addToWatchlist` / `removeFromWatchlist` mutations exactly
(same fields, validation and errors). There is **no WebSocket surface** (a user's
own single list has no live-push consumer) and **no audit event** (personal
bookkeeping with no security consequence).

### `GET /v1/watchlist`

The viewer's watchlist, newest-first. Response `data`: `{ "items": [ { platform,
platform_channel_id, channel_login, channel_display_name, added_at } ] }` —
`[]` when empty. Not signed in → `401`.

### `POST /v1/watchlist`

Favourite a channel. Body: `{ "platform": string, "channel": string }` where
`channel` is the URL handle/login. The handle is resolved to the stable
`platform_channel_id` server-side (the same resolution the public channel page
uses), and `channel_login` / `channel_display_name` are denormalized. Idempotent
upsert; a per-user cap of **500** channels is enforced. Response `data`: the
stored item. Not signed in → `401`; unsupported platform or cap reached → `400`;
handle that resolves to no addressable channel → `404`.

### `DELETE /v1/watchlist`

Remove a channel by its stable id. Body: `{ "platform": string,
"platform_channel_id": string }`. Idempotent - returns `{ "success": true }`
even when the row was already absent. Not signed in → `401`.

## Emote Directory

Public, **unauthenticated** browse of the cross-platform emote catalog
(`chat_emotes`) for the public Stats app. Read-only and edge-cacheable, gated
**only** by the account-less `system:public_stats` operator kill-switch - no auth
and no RBAC permission. Mirrors the GraphQL `publicEmotes` query exactly (same
fields, filters, pagination and errors). No WebSocket surface (a static browse /
search page has no live-push consumer).

### `GET /v1/public-stats/emotes`

Paginated, filterable, name-searchable browse of the emote catalog. **No auth.**
Query parameters (all optional): `platform` (`twitch`/`youtube`/`kick`),
`provider` (the platforms plus `7tv`/`bttv`/`ffz`), `channel_id`, `animated`
(bool), `search` (case-insensitive substring on the emote `name`), `page`
(1-based, default 1), and `limit` (clamped to `1..=100`, default 50).
Empty-string filters are treated as absent.

Response `data`: `{ "emotes": [ { id, platform, provider, channel_id, name, url,
animated, owner_id, source, first_seen_at, last_seen_at } ], "pagination": {
page, limit, total, total_pages } }`. `channel_id` is `null` for a global
(platform-wide) set; `source` is `api_fetch` | `observed`; timestamps are
RFC-3339. The internal `provider_emote_id` is **not** exposed.

Rate-limiting: the anonymous-tier per-IP limiter that wraps every `/v1` request.
Caching: `Cache-Control: public, max-age=60, s-maxage=300,
stale-while-revalidate=600` on the `200` - public reference data, safe to
edge-cache. When the kill-switch is off the endpoint returns `403
FEATURE_DISABLED` with `Feature 'system:public_stats' is not available` (parity
with the GraphQL guard error).

## Audit Log

Scoped read surfaces over the `audit_events` table - one endpoint per `scope`
column value. They mirror the GraphQL `myAuditLog` / `accountAuditLog` operations
exactly (same fields, permission, validation and errors). The operator audit
surface stays at `GET /v1/admin/audit-log` and can optionally filter by `scope`.

Both endpoints share the same query parameters and paginated response shape:

| Query param | Type | Effect |
|-------------|------|--------|
| `page` | integer | Page number (default 1). |
| `limit` | integer | Page size (default 50, clamped `1..=200`). |
| `type` | string | Exact event-type match. |
| `from` | RFC-3339 timestamp | Only events at/after this instant. An unparseable value is ignored. |
| `to` | RFC-3339 timestamp | Only events at/before this instant. An unparseable value is ignored. |

Response: `{ "items": [...], "total": N, "page": N, "limit": N, "total_pages": N }`.

### `GET /v1/me/audit-log`

The caller's own `scope=user` rows. **Self-only**, no RBAC permission - but a
**first-party principal** is required (a logged-in session or the user's own API
key); a popout/overlay/widget/extension token gets `401`. Returns only the
caller's rows. Current writers record successful logins, failed login attempts
tied to a known user, and OAuth grant consent. Mirrors GraphQL `myAuditLog`.

### `GET /v1/account/audit-log`

The active account's `scope=account` events. Current emitters write
role/permission, member-role, channel-connection, and account-scoped GDPR
erasure rows. Permission: the **account-scope** `audit-log:read` (`403`
otherwise; `401` if no account is active). Returns only the caller's account's
rows. Mirrors GraphQL `accountAuditLog`.

### `GET /v1/me/audit-log/export` and `GET /v1/account/audit-log/export`

Download the personal or the account log as a file, with the same guard as the
matching read above. `format=csv|json` (default `csv`); `columns` is a comma list
of `time, event, ip, device, location, details` (default all); `type`, `from`
and `to` filter like the read. `ids` selects rows: a comma list of at most
**1000** event ids. More ids, an unknown column or format, or a malformed id
returns `400`. A file holds at most 10,000 rows. CSV cells that a spreadsheet
would run as a formula start with `'`. This file-download endpoint intentionally
has no GraphQL twin.

Every audit response item (here, on `GET /v1/me/audit-log`, and on the admin
`GET /v1/admin/audit-log`) carries a `resolved_names` array of
`{ id, kind, display_name }` (`kind` ∈ `user` | `account` | `role`) - read-time
resolutions of the entity UUIDs the event references (actor + an allowlist of
metadata ids), computed once per page. Misses (deleted/unknown entities) are
omitted; the raw UUIDs are never removed. This mirrors the GraphQL `resolvedNames`
field exactly (ZAF-1233).

### `POST /v1/internal/audit-ingest`

Server-to-server ingest for **user-scope** login / 2FA / OAuth-grant security
events. These originate in **apps/id** (NextAuth, TypeScript) at the auth
boundary, but the Rust API is the single audit writer, so apps/id posts them here
after the auth event instead of writing `audit_events` itself.

**Auth: System key only, carrying the narrow `audit:ingest` grant.** Every
non-System principal (session, user API key, popout/overlay/widget/extension
token) is rejected `403`, and an anonymous request `401` - no public/user route
can forge audit rows. A System key without `audit:ingest` (or `audit:*`) is also
`403`; a bare `*:*` does **not** grant it. Provision apps/id's key with
`audit:ingest`.

Request body:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `user_id` | UUID | yes | The subject user the event is about. |
| `type` | string | yes | One of `user:login`, `user:login_failed`, `user:mfa_enabled`, `user:mfa_disabled`, `user:oauth_granted`. Any other value (including an `account:*` / `system:*` type) → `400`. |
| `ip_address` | string | no | The **end-user's** client IP at the auth boundary (this is a server-to-server call, so the request peer is the id service - forward the real client IP here). GeoIP-resolved fail-open into `country`/`city`. |
| `user_agent` | string | no | The end-user's user-agent. |
| `metadata` | object | no | Free-form JSON **object** (defaults to `{}`; a non-object value → `400`). |

The handler **forces** `scope = user`, `user_id = <subject>`, and
`account_id = NULL` - an ingest caller can never widen scope, attach a tenant, or
write a non-user-scope type. On success returns `201 { "id": "<uuid>" }` with the
new row id.

### Passkey and 2FA request fields

Passkey sign-in and assertion challenge responses contain `challenge_id` and browser `options`. Registration options contain browser `options` and, for the first method, `recovery_codes`; the finish call takes `response` without a separate challenge ID. Send the browser's `PublicKeyCredentialJSON` as `response` with that challenge ID to the matching verify route. A passkey second-factor answer uses `passkey_challenge_id` and `passkey_response`; alternatives are `code` and `recovery_code`. The `mfa_methods` list on pending sign-in and step-up responses contains `passkey` and/or `totp` after the first factor. `GET /v1/users/me/mfa` returns `factors[]` with `id`, `kind`, `label`, `created_at`, `last_used_at`, and, for passkeys, `provider`, `backup_eligible`, `backup_state`. The API limits a profile to five apps and ten passkeys. Admin user results report `mfa_app_count` and `mfa_passkey_count` without method names. Invalid labels return `INVALID_MFA_FACTOR_LABEL`; first-passkey completion without the recovery-code acknowledgment returns `RECOVERY_CODES_NOT_STORED`; a missing passkey method returns `PASSKEY_NOT_SET_UP`. Passkey failures include `PASSKEY_INVALID`, `PASSKEY_CHALLENGE_EXPIRED` and `PASSKEY_ALREADY_REGISTERED`; the per-kind limit returns `MFA_FACTOR_LIMIT`.

---

## API Reference / GraphQL

Source: https://docs.lumio.vision/api-reference/graphql

# GraphQL

## Contract declarations

These operations are available at `POST /v1/gql`. GraphQL fields and arguments are `camelCase`; errors carry the same `extensions.code` as the REST twins. Public mutations require a Turnstile token for action `withdraw` or `cancel`, with the same per-IP and global limits as REST.

| Query or mutation | Input / arguments | Guard |
|---|---|---|
| `declarePublicWithdrawal(input: PublicWithdrawalInput!)` | `name`, `email`, `contractReference`; optional `message`, `locale`, `turnstileToken`, `clientRequestId` | Public. |
| `declarePublicCancellation(input: PublicCancellationInput!)` | `name`, `email`, `contractReference`; optional `kind`, `reason`, `effective`, `effectiveDate`, `locale`, `turnstileToken`, `clientRequestId` | Public. |
| `declareWithdrawal(input: WithdrawalInput!)` | `contract` (`plan`, `extension_purchase`, `other`); optional `extensionPurchaseId`, `contractReference`, `message`, `name`, `receiptEmail`, `clientRequestId`, `accountId` | Interactive session; `plan:edit` for plan, `extension-store:uninstall` for purchase, session only for other. The target channel is checked. |
| `withdrawableContracts`, `cancellableContracts` | No arguments; return `[ContractOption!]!` across manageable channels | Interactive session; options require the relevant permission in each channel. |
| `cancelSubscription(kind, reason, effective, effectiveDate, receiptEmail, name, clientRequestId, accountId)` | Plan cancellation; all arguments optional | `plan:edit` in the target channel and interactive session. |
| `cancelExtensionSubscription(purchaseId: UUID!, input: ExtensionCancelInput)` | Extension subscription cancellation; `input.accountId` is optional | `extension-store:uninstall` in the target channel and interactive session; that channel must own the purchase. |
| `adminContractDeclarations(status, kind, first, after)` | Oldest-first `AdminDeclarationPage` (`items`, `nextCursor`); defaults to open and 50 items | Admin `contract-declarations:read`. |
| `adminContractDeclaration(id: UUID!)` | One `AdminDeclaration` | Admin `contract-declarations:read`. |
| `adminCloseContractDeclaration(id: UUID!, input: CloseContractDeclarationInput!)` | `status` (`processed` or `rejected`), optional `note`, `refundReference`, `stripeApplied` | Admin `contract-declarations:edit` and interactive session. |
| `adminMatchContractDeclaration(id: UUID!, input: MatchContractDeclarationInput!)` | `accountId`, `contract`, optional `extensionPurchaseId` | Admin `contract-declarations:edit` and interactive session. |
| `adminExtendContractDeclarationRetention(id: UUID!, retainUntil: String!)` | Later `YYYY-MM-DD` | Admin `contract-declarations:edit` and interactive session. |

`DeclarationReceipt` contains `id`, `reference`, `kind`, `status`, `receivedAt`, `receiptEmail` and nullable `periodEnd`. `ContractOption` identifies a plan or extension purchase and carries `accountId`, `accountName`, the plan or extension name, contract time, paid-period end and `cancelAtPeriodEnd`. The lists put the active channel first, then other manageable channels by switcher name. For signed-in writes, omit `accountId` to use the active channel; supplying it checks the required permission in that channel without switching the active channel. `accountId` is ignored when withdrawing from `other`. A missing permission returns 403; a purchase outside the target channel returns `PURCHASE_NOT_FOUND` (404). `AdminDeclaration` includes the stored declarant and contract snapshot, cancellation terms, receipt status, processing result and `retainUntil`. The `kind` and `effective` values match [REST](/api-reference/rest-api#contract-declarations). Repeating `clientRequestId` for the same declaration returns the first receipt; reusing it for a different declaration (another user, channel, kind, contract or purchase, or another e-mail address on the public forms) fails with code `IDEMPOTENCY_KEY_REUSED` and returns no receipt. An ordinary signed-in cancellation can return `processed` after Stripe accepts it or `open` while Stripe is retried. Public and extraordinary requests remain open for review.

## Abuse reports

`submitAbuseReport(input: AbuseReportInput!)` is public. The input requires `songName`, `artist`, `reporterName`, `reporterEmail` and `reason`; `spotifyTrackId`, `proofUrl` and `turnstileToken` are optional schema fields. The action `abuse` Turnstile token is required when verification is enabled. The mutation returns `AbuseReportResult { id }` and queues the report for operator review without immediately blocking the song. It shares validation, rate limits and errors with [REST](/api-reference/rest-api#abuse-reports): `MISSING_SONG_NAME`, `MISSING_ARTIST`, `MISSING_REPORTER_NAME`, `INVALID_EMAIL`, `MISSING_REASON`, `INVALID_PROOF_URL`, `INVALID_SPOTIFY_TRACK_ID`, `TURNSTILE_REQUIRED`, `TURNSTILE_FAILED`, `RATE_LIMITED` and `TRY_AGAIN` in `extensions.code`.

## Developer balance release (admin)

A developer balance that Lumio cannot pay out — the profile has **no payout method**, or the identity is **not verified** — blocks every delete (`409 DEVELOPER_FUNDS_OUTSTANDING`). On the person's request, an operator releases it as a liability and deletes in one transaction. A payable balance is never released: it goes through the closing payout.

| Mutation | Input / arguments | Guard |
|---|---|---|
| `adminReleaseFundsAndDeleteUser(userId: UUID!, input: AdminReleaseFundsInput!)` | `requestReference` (1–64 characters), `reason` (1–500 characters) | Admin `developer-funds:release-deletion` **and** `users:delete`, interactive session. |
| `adminReleaseFundsAndDeleteDeveloper(id: UUID!, input: AdminReleaseFundsInput!)` | as above | Admin `developer-funds:release-deletion` **and** `developer-verification:edit`, interactive session. |

Both return `AdminReleasedFundsDeletion { deleted, releasedBalanceId, amount, currency, releaseCase, mailSent, claimCode }`. `releaseCase` is `not_verified` (checked first) or `no_payout_method`; the server decides it, never the client. A zero balance deletes without a release (`releasedBalanceId: null`). The person receives the claim code by e-mail after the commit; `claimCode` is returned **only** when that mail could not be sent (`mailSent: false`) and cannot be shown again. `requestReference` and `reason` must not contain names, e-mail addresses or contact data.

Errors (same codes and messages as REST): `INVALID_REQUEST_REFERENCE` / `INVALID_RELEASE_REASON` (400), `DEVELOPER_FUNDS_PAYABLE` (409, use the closing payout), `DEVELOPER_FUNDS_OUTSTANDING` (409, a payout is `pending` or `processing`), not found (404), `Missing permission: …` (403). Each successful call writes `developer:funds_deletion_released` (when a balance was released) and `system:user_deleted` / `system:developer_deleted`.

### Settling a released balance

When the person comes back with the claim code from the release mail:

| Mutation | Input | Guard |
|---|---|---|
| `adminStartReleasedBalanceClaim(input: AdminReleasedBalanceClaimInput!)` | `claimCode` (separators, spaces and case are ignored) | Admin `developer-funds:settle`, interactive session. |
| `adminSettleReleasedBalance(input: AdminSettleReleasedBalanceInput!)` | `claimCode`, `developerId` (the person's new profile) | Admin `developer-funds:settle`, interactive session. |

`adminStartReleasedBalanceClaim` sets `claim_started_at` once and returns `AdminReleasedBalanceClaim { releasedBalanceId, amount, currency, releaseCase, releasedAt, claimStartedAt, newlyStarted }`; from then on the record is kept until the claim is settled. `adminSettleReleasedBalance` requires a verified identity on the target profile, adds the amount to its balance (not to `totalEarned`) and marks the record settled, in one transaction; it returns `AdminReleasedBalanceSettlement { releasedBalanceId, amount, currency, developerId, settledAt, newBalance }`.

Errors (same codes and messages as REST): `INVALID_CLAIM_CODE` (400), `DEVELOPER_VERIFICATION_REQUIRED` (403), `RELEASED_BALANCE_NOT_FOUND` / developer profile not found (404), `RELEASED_BALANCE_SETTLED` (409), `Missing permission: …` (403). They write `developer:funds_released_claim_started` (only the call that starts the claim) and `developer:funds_released_settled`.

## Profile security and data operations

These operations use `POST /v1/gql`; GraphQL names and fields are `camelCase`. Public sign-in operations can return a pending 2FA challenge. The API issues no session token or PKCE code for a pending challenge until `verifyMfaChallenge` succeeds; `verifyPasskeySignIn` completes both steps directly. A fresh step-up means a successful confirmation on the same interactive session within ten minutes; 2FA-enabled users confirm with a passkey, authenticator app code or recovery code.

| Query | Returns | Guard |
|---|---|---|
| `turnstileConfig` | Runtime site key and widget requirement | Public |
| `emailLoginStatus` | Email sign-in state | Interactive session |
| `mfaStatus` | 2FA state, recovery-code count, trusted devices and `factors` (apps and passkeys) | Interactive session |
| `stepUpOptions` | Confirmation methods and freshness | Interactive session |
| `supportCode` | Current hourly support code | Interactive session |
| `dataExports` | Personal export requests | Interactive session |
| `adminSupportCodeChecks(userId)` | Recent code checks | Admin `support:verify` |

| Mutation | Purpose |
|---|---|
| `register`, `resendRegistration`, `verifyEmailLogin` | Email registration, resend and clicked-link confirmation. Confirmation does not sign in and needs no session; a link opened while signed in as another profile fails with `LINK_OTHER_PROFILE`. |
| `passwordLogin`, `requestPasswordReset`, `completePasswordReset` | Email sign-in and password recovery. A completed reset ends earlier sessions. |
| `verifyMfaChallenge` | Finish a pending sign-in with an app code, recovery code or passkey assertion before a token or PKCE code is issued. |
| `passkeySignInOptions`, `verifyPasskeySignIn` | Get a public, rate-limited challenge and sign in without a password. |
| `passkeyMfaOptions`, `stepUpPasskeyOptions`, `stepUpPasskey` | Get a passkey challenge for a pending second step or session confirmation, then confirm the session. |
| `stepUpOauth`, `stepUpPassword`, `stepUpMfa` | Confirm identity on an interactive session. |
| `requestEmailLogin`, `changeEmailLogin`, `setEmailLoginPassword`, `cancelEmailLogin`, `removeEmailLogin` | Set up, change or remove email sign-in. Request/resend needs Turnstile; method changes need a fresh step-up. |
| `changePassword`, `clearProfileEmail` | Change the password; remove a profile email that came from a platform sign-in. The email sign-in address cannot be removed here (`EMAIL_FROM_SIGN_IN`); change or remove the email sign-in instead. |
| `startMfaSetup`, `confirmMfaSetup`, `enableMfa`, `disableMfa` | Set up an authenticator app, or turn off all methods; a passkey can confirm disable. Start and enable require fresh step-up. |
| `startPasskeyRegistration`, `finishPasskeyRegistration` | Create a passkey; first-method options include ten recovery codes and finish requires `recoveryCodesStored: true`. |
| `renameMfaFactor`, `removeMfaFactor` | Rename or remove an app or passkey; removal accepts a passkey assertion, app code or recovery code. |
| `regenerateRecoveryCodes`, `revokeTrustedDevice`, `revokeAllTrustedDevices` | Replace recovery codes or revoke trusted devices. |
| `requestDataExport`, `cancelDataExport(exportId)`, `dataExportDownloadLink` | Request `user` or `user_channels` data; cancel an own export while it is `pending` or `running` (no step-up, status becomes `cancelled`, a cancelled export does not count towards the 24-hour limit as long as it had not started yet - once the job had started it (`running`), it counts; another user's export answers `NOT_FOUND`, a finished one `EXPORT_NOT_CANCELLABLE`); issue a five-minute file link after fresh step-up. The ZIP download itself is REST-only. |
| `scheduleProfileDeletion(graceDays: Int)`, `cancelProfileDeletion` | Schedule deletion after `graceDays` (0, 7 or 30; default 30) or cancel it. See below. |
| `scheduleAccountDissolution(accountId, graceDays)`, `cancelAccountDissolution(accountId)` | Dissolve a channel after a grace period (or at once) or cancel the scheduled dissolution. See **Scheduled dissolution** below. |
| `setAccountIdentitySource(accountId, kind, connectionId)`, `updateAccountName(accountId, name)`, `removeAccountAvatar(accountId)` | Choose where the channel's name and picture come from, set the own name, remove the own picture. See **Channel name and picture** below. |
| `adminResetUserMfa(userId, reason)` | Reset 2FA; mandatory reason and admin `users:edit`. |
| `adminRevealSupportCode`, `adminCheckSupportCode` | Reveal or verify a code; admin `support:verify`, audited. |
| `submitContactMessage(input: ContactMessageInput!)` | Public contact form; see **Contact form** below. |

`disconnectLoginConnection` and platform sign-in linking require fresh step-up, with an exception for reconnecting the same provider account. The REST twins call the same security service and use the same guards and error codes. A stale confirmation returns `STEP_UP_REQUIRED`. Account audit exports and ZIP file downloads have REST file endpoints rather than GraphQL file fields.

`StepUpConnection` (in `stepUpOptions.connections`) carries `connectedAt` (RFC 3339, when the sign-in was added) and `lastUsedAt` (RFC 3339, the last platform sign-in or step-up through exactly this connection; `null` when unknown, e.g. a connection that was only linked). `DataExport` carries `status` (`pending`, `running`, `ready`, `failed`, `expired`, `cancelled`) and `progressPercent` (0–100 while the archive is built, only ever rising; `null` while `pending`). `MeResult.accounts[].platforms` (`AccountMembership.platforms: [String!]!`) lists the distinct platforms of the channel's connections - channel connections, not sign-ins - in the order `twitch`, `youtube`, `kick`, then the rest alphabetically; a connection waiting for a reconnect counts, a removed one does not, and a channel without connections has `[]`.

`scheduleProfileDeletion` returns `ProfileDeletion { scheduledFor, deleted, closingPayoutCents }`. `graceDays` other than 0, 7 or 30 fails with `INVALID_GRACE` ("grace_days must be 0, 7 or 30"); every value needs a fresh step-up (`STEP_UP_REQUIRED`). `graceDays: 0` deletes the profile at once (export files, uploaded avatar, the user row with its sessions, `system:user_deleted` with `self_service: true`) and returns `scheduledFor: null, deleted: true`. Owning a channel fails with `OWNS_CHANNELS` unless every owned channel is scheduled for dissolution on or before the profile deletion date; `graceDays: 0` requires owning no channel. With `graceDays` 7 or 30 a developer revenue balance above 0 is paid out as the closing payout for the whole balance, even below the minimum payout amount; `closingPayoutCents` carries the amount (`null` when nothing was owed). `DEVELOPER_FUNDS_OUTSTANDING` ("The developer profile still has a revenue balance or a payout in progress. It can be deleted once Lumio has paid it out") refuses every value while a payout is `pending` or `processing`, `graceDays: 0` while any money is owed, and a balance that cannot be paid out (no payout method, no verified developer identity). The closing payout carries its self-billed credit note like every payout, so incomplete tax details fail with `TAX_DETAILS_REQUIRED` and an incomplete `[billing.issuer]` with `CREDIT_NOTE_ISSUER_NOT_CONFIGURED` (same texts as `requestPayout`); nothing is paid out or scheduled then. `adminDeleteUser` and `adminDeleteDeveloper` fail with the same code while money is owed. The job holds a due deletion until the profile is paid out and retries it every run. The reminder goes out 7 days before the end of a 30-day period and 1 day before the end of a 7-day period. `cancelProfileDeletion` returns `deleted: false`; it works only before the date and fails with `DELETION_IN_PROGRESS` ("The deletion is already running") once the date has passed, and with `NO_DELETION_SCHEDULED` when nothing is scheduled. REST twin: `POST`/`DELETE /v1/users/me/deletion`, same codes.

`Account.dissolutionScheduledFor` and `AccountMembership.dissolutionScheduledFor` (in `me.accounts[]`) are an ISO-8601 string while the channel is scheduled for dissolution, otherwise `null`. The dashboard reads the membership value for the dissolution banner and the account-switcher label.

**Profile email.** It is set in one place only, the email sign-in. With an email sign-in, `me.email` is always the confirmed sign-in address (`emailSource: "email_login"`), and it follows a changed sign-in address. Without one it is the address of a platform sign-in (`platform:<provider>`, filled only when empty; `platform:unknown` for older addresses), otherwise `null`. Removing the email sign-in brings back the platform address it replaced, or leaves none. `setEmailLoginPassword` returns `EmailLoginActivated { email }`.

`SignInResult` carries `mfaRequired`, `mfaMethods` (`passkey` and/or `totp`) and a one-use `mfaToken` while a 2FA challenge is pending; it carries session tokens or a PKCE code only after completion. `Session` includes `authMethod`, `mfaVerifiedAt`, `lastUsedAt`, `country`, and `city`. `MeResult` exposes `emailSource`, `nameSourceKind`, and scheduled-deletion state. `billingStatus` reports `billingEnabled`, `billingInterval` and `cancelAtPeriodEnd`. Admin user results expose `mfaAppCount` and `mfaPasskeyCount` without method names. The corresponding REST fields use `snake_case`.

**Contact form.** `submitContactMessage(input: { name, email, subject, message, turnstileToken })` is public and returns `ContactMessageResult { status }` (`"sent"`). It forwards the message to the Lumio inbox (`[contact] recipient`) as an e-mail with `Reply-To` set to `email`; nothing is stored. `name` is optional (at most 100 characters), `subject` is one of `general`, `privacy`, `legal`, `billing`, `other`, `message` has 1 to 5000 characters, and `turnstileToken` is a Turnstile token for action `contact` from a web-app hostname. Errors (`extensions.code`, message): `INVALID_EMAIL` "Enter a valid email address", `INVALID_CONTACT_NAME` "The name can have at most 100 characters", `INVALID_CONTACT_SUBJECT` "Choose a subject: general, privacy, legal, billing or other", `INVALID_CONTACT_MESSAGE` "The message needs 1 to 5000 characters", `TURNSTILE_REQUIRED`, `TURNSTILE_FAILED`, `RATE_LIMITED` (5 per IP per hour, 100 per hour in total, with `retryAfterSecs`) and `TRY_AGAIN`. REST twin: `POST /v1/contact`, same codes and texts.

Lumio provides a GraphQL endpoint for flexible data querying.

## Endpoint

```
POST /v1/gql
```

## Base URLs

| Environment | URL |
|-------------|-----|
| Production         | `https://api.lumio.vision/v1/gql` |
| Production Preview | `https://lumio.api.prod.zaflun.dev/v1/gql` |
| Staging            | `https://lumio.api.staging.zaflun.dev/v1/gql` |

## Interactive Explorer

**GraphiQL** is available at `/v1/graphiql` when the API is running (gated behind `graphql.playground = true` in config). Use it to explore the schema, build queries, and test mutations.

## Schema Download

Download the GraphQL SDL schema:

```bash
curl -o schema.graphql https://api.lumio.vision/v1/schema
```

## Example Query

```graphql
query {
  overlays {
    id
    name
    key
    width
    height
  }
}
```

## Errors

Resolver errors carry a machine-readable `extensions.code` that mirrors the REST [`error` codes](./rest-api.md#error-format) for the same failure (`UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`, `CONFLICT`, `RATE_LIMIT_EXCEEDED`, `VALIDATION_ERROR`, …) with an identical client-facing `message` (5xx detail scrubbed, 4xx verbatim). Both protocols route through the shared `ApiError`, so a given failure returns the same `code` + `message` on GraphQL and REST — including upstream-integration resolvers such as Spotify, whose rate limits surface as `RATE_LIMIT_EXCEEDED` and expired tokens as `UNAUTHORIZED`. The web dashboard's proxy layer translates these codes back into HTTP status classes (e.g. `RATE_LIMIT_EXCEEDED` → `429`) for the browser. Extra error data rides in further extensions that mirror REST `details`: `retryAfterSecs` (REST `details.retry_after_secs`) and `signedInAs` (REST `details.signed_in_as`, the platform account a `WRONG_PLATFORM_ACCOUNT` OAuth flow came back with).

For `spotifyState`, `spotifySearch`, and Spotify mutations that call Spotify, an upstream 429 returns `message: "Spotify rate limit reached. Try again shortly."`, `extensions.code: "RATE_LIMIT_EXCEEDED"`, and `extensions.retryAfterSecs` with Spotify's wait in seconds (at least 1). The [REST Spotify routes](./rest-api.md#error-format) return HTTP 429 with the same code and message, plus `details.retry_after_secs` and a `Retry-After` header. The dashboard and popout proxy map the GraphQL code to browser HTTP 429 so the [music player](/user-guide/music) can wait and resume automatically.

`refreshToken` returns the same codes and messages as REST `POST /v1/auth/refresh`: an empty token is `BAD_REQUEST` (`Bad request: refresh_token is required`); a bad signature or expired token, a token that is not a refresh token, a missing or expired session (logged out, revoked, or the token was already rotated) and a session/user mismatch are all `UNAUTHORIZED` (`Unauthorized: Invalid or expired refresh token`, `Unauthorized: Not a refresh token`, `Unauthorized: Session not found or expired - please log in again`, `Unauthorized: Session user mismatch`, `Unauthorized: Session already refreshed - please use the latest refresh token`). Only database or signing faults return `DATABASE_ERROR` / `INTERNAL_SERVER_ERROR`. A client treats `UNAUTHORIZED` as "sign in again".

The API logs expected client errors (`NOT_FOUND`, `UNAUTHORIZED`, …) at `info`, not `warn`; see [Error tracking → GraphQL request log levels](../developer-guide/error-tracking.md#graphql-request-log-levels).

Billing without Stripe (`stripe.enabled = false`): `invoices`, `validateCoupon`, `createCheckout`, `createPortal` and `cancelSubscription` fail with `extensions.code: "BILLING_DISABLED"` and the message `Billing is not enabled` (REST: `409` with the same `error` code and message), after their permission or session guard. `billingStatus` never fails for this reason; it reports `billingEnabled: false`, so a client checks that first and does not ask for invoices.

`createCheckout(planSlug, interval, couponCode, acceptWithdrawalWaiver: Boolean!)` creates a Stripe session only when `acceptWithdrawalWaiver` is `true` (the buyer ticked the withdrawal-waiver checkbox). `false` fails with `VALIDATION_ERROR` "You must accept the withdrawal waiver (accept_withdrawal_waiver) before checkout", the same contract as REST `POST /v1/billing/checkout`; omitting the argument is a schema error. `createPortal` opens the customer portal without plan changes. Details: [Billing → Withdrawal waiver and order confirmation](../features/billing.md#withdrawal-waiver-and-order-confirmation).

Scrubbing a 5xx is a wire-level rule, not a reason to discard the cause: `graphql::errors::to_graphql_error` logs the full `ApiError` server-side for every 5xx, mirroring what REST's `ResponseError::error_response` already did. Both protocols therefore leave the same record in the API log, and an `INTERNAL_SERVER_ERROR` the browser sees as `An internal server error occurred` is always diagnosable from that log alone.

## Feature Flags & Status

### Queries

#### `me { featureStatuses }`

Returns merged feature-flag statuses for the current user. Includes account-scope flags (all non-`system:*` categories) **and** the user-scope `system:account_creation` flag. Available on the `MeResult` type returned by `me { ... }`.

#### `accountFeatures { enabledFeatures featureStatuses }`

Returns feature flags scoped to the caller's active account. Requires authentication (no `account:read` permission needed - works with popout-token auth).

- `enabledFeatures: [String!]!` - list of flag keys that are enabled for this account (excludes `system:*` flags).
- `featureStatuses: [FeatureStatusGql!]!` - full status list with `key`, `enabled`, and `reason` for each flag (excludes `system:*` flags).

```graphql
query {
  accountFeatures {
    enabledFeatures
    featureStatuses {
      key
      enabled
      reason
    }
  }
}
```

#### `me { ownedAccountCount }` and `me { maxAccounts }` - multi-account limits

The `MeResult` type exposes two fields for multi-account management:

- `ownedAccountCount: Int!` - the number of Lumio accounts the authenticated user owns (i.e. where they hold the Owner role).
- `maxAccounts: Int!` - the maximum number of accounts this user may own, derived from the user's plan and any admin overrides.

These fields are used by the dashboard onboarding flow and account-creation gate to surface upgrade prompts when the user is at their account limit.

#### `me { adminMfaRequired }` - admin access needs 2FA

`adminMfaRequired: Boolean!` is `true` when the user holds admin grants (`adminPermissions` is not empty) but has no 2FA factor (authenticator app or passkey). Such a session keeps its account and user-level permissions, but every admin resolver refuses it with `extensions.code = "ADMIN_MFA_REQUIRED"` and the message `Admin access requires two-factor authentication. Turn on an authenticator app or a passkey in Settings › Security`. `adminPermissions` still lists the granted admin permissions. The REST equivalent is the `admin_mfa_required` field on `GET /users/me`, and REST admin routes answer `403 ADMIN_MFA_REQUIRED`. Details: [Admin panel → Two-factor authentication](../admin/admin-roles.md#two-factor-authentication-required).

#### `me { isDeveloper }` - developer status

`isDeveloper: Boolean!` is `true` when the authenticated user has a row in the `developer_profiles` table OR has the `extension_dev_mode` admin override enabled. This field drives access to the developer dashboard and extension management features in the web app. The REST equivalent is the `is_developer` field on `GET /users/me`.

#### `me { extensionDevMode }` - Extension Developer Mode

`extensionDevMode: Boolean!` - when `true`, extension bundle serving loads the latest draft/testing version instead of the published version for extensions the user develops. Toggle via `updateMe(input: { extensionDevMode: true })`. The REST equivalent is the `extension_dev_mode` field on `GET/PATCH /users/me`.

#### `me { locale timezone dateFormat timeFormat }` - display preferences

The user-global display preferences (all `String!`), applied across the webapp (multichat, events, music, …):

| Field | Values | Meaning |
|-------|--------|---------|
| `locale` | `auto` · `en` · `de` | UI language; `auto` uses the request-time fallback (`locale` cookie if valid, otherwise default language) |
| `timezone` | `auto` or an IANA name (`Europe/Berlin`, …) | `auto` uses the browser-detected zone mirrored into `lumio-tz`; server render falls back to `UTC` until that mirror exists |
| `dateFormat` | `auto` · `dmy_dot` · `dmy_slash` · `mdy_slash` · `ymd_dash` | Numeric date format: automatic language-locale format, `31.12.2026`, `31/12/2026`, `12/31/2026`, or `2026-12-31` |
| `timeFormat` | `auto` · `h12` · `h24` | Numeric time format: automatic format-locale hour cycle, `11:30 PM`, or `23:30` |

Set them with `updateMe(input: { locale: "de", timezone: "Europe/Berlin", dateFormat: "dmy_dot", timeFormat: "h24" })`. An invalid value is rejected with a GraphQL error (fail-closed, byte-identical message to the REST twin), never silently coerced to `auto`. Changing them emits **no audit event** (a display preference is neither security- nor lifecycle-relevant). The REST equivalents are the `locale` / `timezone` / `date_format` / `time_format` fields on `GET/PATCH /users/me`.

#### `me { displayCurrency effectiveDisplayCurrency }` - history display currency

`displayCurrency` is `auto` or EUR/one of the ECB reference currencies. `auto` resolves to EUR for German and USD otherwise (an automatic language uses the detected locale); `effectiveDisplayCurrency` is the resolved code. Set it with `updateMe(input: { displayCurrency: "EUR" })`. It is a personal display preference with no RBAC permission or audit event. REST exposes `display_currency` and `effective_display_currency` on `GET/PATCH /v1/users/me`.

#### `me { seasonLookEnabled seasonStrength seasonMotion seasonCreatures seasonBannerDismissed }` - seasonal look

The user-global preferences for the seasonal dashboard look (e.g. Halloween). They live on the user profile, so they follow the user to every device and into popouts (also inside OBS):

| Field | Type | Default | Values |
|-------|------|---------|--------|
| `seasonLookEnabled` | `Boolean!` | `true` | One switch for every season |
| `seasonStrength` | `String!` | `full` | `full` · `subtle` |
| `seasonMotion` | `String!` | `auto` | `auto` (animations play unless the OS asks for reduced motion) · `off` |
| `seasonCreatures` | `JSON!` | `{}` | Object `{ "<creature>": Boolean }`; an absent key means the creature's registry default (spider off, bat on). Keys `[a-z_]{1,32}`, at most 32 entries |
| `seasonBannerDismissed` | `[String!]!` | `[]` | Dismissed season banners as `<seasonId>:<year>` (season id `[a-z0-9-]{1,32}`, the year the season window starts in), oldest first |

Set them with `updateMe(input: { seasonLookEnabled: true, seasonStrength: "subtle", seasonMotion: "off", seasonCreatures: { spider: true }, seasonBannerDismissed: ["halloween:2026"] })`. `seasonCreatures` and `seasonBannerDismissed` **replace** the stored value (send `{}` / `[]` to reset). An invalid preset, a non-object or non-boolean creature map, a bad creature key, more than 32 creatures, or a malformed banner entry is rejected with a GraphQL error (fail-closed, byte-identical message to the REST twin, never coerced). The banner list is de-duplicated and capped at 50 entries; beyond that the **oldest** entries are dropped rather than the request rejected. Changing them emits **no audit event** (a display preference). The REST equivalents are the `season_*` fields on `GET/PATCH /users/me`; popouts read them via `popoutSession`.

#### `me { motionPreference }` - animations in Lumio

The user-global **"Animations in Lumio"** preference. It lives on the user profile, so it follows the user to every device and into popouts (also inside OBS), which read it via `popoutSession`:

| Field | Type | Default | Values |
|-------|------|---------|--------|
| `motionPreference` | `String!` | `system` | `system` (full motion unless the OS asks for reduced motion) · `reduced` · `off` |

There is deliberately no "always on": the OS reduced-motion request is never overridden. It is independent of `seasonMotion`; the stricter of the two applies to the seasonal decoration. It covers the dashboard and its popouts, never widgets or overlays.

Set it with `updateMe(input: { motionPreference: "reduced" })`. Any other value is rejected with a GraphQL error (fail-closed, byte-identical message to the REST twin, never coerced), e.g. `Invalid motion_preference 'auto': allowed values are system, reduced, off`. A popout session cannot change it (`updateMe` is first-party gated). Changing it emits **no audit event** (a display preference). The REST equivalent is the `motion_preference` field on `GET/PATCH /users/me`.

#### `me { nameSourceConnectionId nameSourceKind }`, `setNameSourceConnection`, `updateDisplayName`, `removeAvatar` - name/avatar source

A user's Lumio `displayName` + `avatarUrl` come from one of two sources, exposed as `me { nameSourceKind }`:

- **`connection`** - mirrored on every login from a single *name-source* login connection: the one the user explicitly picks, or, when none is picked, their first-ever-connected login (`login_connections.createdAt` ascending). A login via a *secondary* platform therefore never rewrites the name or avatar.
- **`own`** - the user's own details. Sign-ins never overwrite them; the name is set with `updateDisplayName`, the picture is uploaded over REST. E-mail-only profiles always use `own`.

Operations (all session-only; the REST twins share the service code, the validation, the error codes and messages, and the audit event):

- `me { nameSourceConnectionId }` (`UUID`) exposes the currently-pinned source connection, or `null` when it follows the first-connected login (always `null` with `own`). REST parity: `name_source_connection_id` / `name_source_kind` on `GET /users/me`.
- `setNameSourceConnection(loginConnectionId: UUID, kind: String): NameSourceResult!` - `kind` is `"connection"` (default) or `"own"`; anything else returns `INVALID_NAME_SOURCE`.
  - `connection` pins (or, with `loginConnectionId: null`, clears) the source and immediately re-materializes the name/avatar from it. An uploaded own picture is deleted from storage. The connection must belong to the caller (ownership-checked; a foreign id is rejected with the same message as the REST twin). A profile without any platform sign-in gets `NO_LOGIN_CONNECTION`.
  - `own` keeps the current name and picture as the starting values.
- `updateDisplayName(displayName: String!): NameSourceResult!` - only with `own` (otherwise `NAME_SOURCE_NOT_OWN`). The name is trimmed and NFC-normalised and needs 2-32 characters without control or invisible characters (zero-width spaces/joiners, bidi controls, BOM): `DISPLAY_NAME_TOO_SHORT`, `DISPLAY_NAME_TOO_LONG`, `DISPLAY_NAME_INVALID_CHARACTERS`.
- `removeAvatar: NameSourceResult!` - only with `own` (otherwise `NAME_SOURCE_NOT_OWN`). Shows initials instead and deletes an uploaded file.
- **No GraphQL upload.** The picture is binary multipart data, so the upload is REST-only: [`POST /v1/users/me/avatar`](./rest-api.md#post-usersmeavatar). This is the one deliberately single-protocol operation of the group.

`NameSourceResult` is `{ displayName, avatarUrl, nameSourceConnectionId, nameSourceKind }` (REST twin `NameSourceResponse`).

Audit: switching between `own` and `connection`, changing the own name, and uploading or removing the own picture write `user:profile_identity_changed` (scope `user`). Metadata is `changed` (a list of `source`, `display_name`, `avatar`) and, for a source switch, `source` = `own` / `connection`. It never contains a name or a picture URL. Choosing among one's own connections (`connection` → `connection`) is a display preference and is not audited.

`displayName` is **not** settable through `updateMe` - the field was removed. Use `updateDisplayName` with own details.

#### `me { loginConnections }` / `account { channelConnections }` / `account { botConnections }` - platform filtering

Login connections, channel connections, and bot connections filter by the corresponding platform flag (`platform:{x}:login`, `platform:{x}:channel`, `platform:{x}:bot`). A platform whose flag is disabled globally is excluded from these lists. This filtering also applies to the REST equivalents (`GET /users/me/login-connections`, `GET /connections/channel`, `GET /bot-connections`).

Each `channelConnections` row carries its `id: UUID!` — the value `setAccountIdentitySource(connectionId:)` takes; the REST twin `GET /v1/connections/channel` carries the same `id`.

Each `channelConnections` row exposes both `channelName` — the platform **display name**, which may be localized (`こさむん`) — and `channelLogin` — the URL-safe **login / handle** (Twitch `login`, Kick slug; `null` for YouTube/Spotify and legacy rows not yet backfilled). Build a profile URL and any IRC-facing name from `channelLogin`, not `channelName` (ZAF-1461). The REST twin `GET /v1/connections/channel` carries the same `channel_login`.

Each `channelConnections` row also carries `missingScopes: [String!]!` — the **base** scopes the stored grant lacks (e.g. `["kicks:read", "channel:rewards:read"]` for a Kick connection made before those scopes were required). `[]` when nothing is missing **and** when the grant was never recorded (`scopes` is `null`). YouTube's optional `yt-analytics-monetary.readonly` never appears in `missingScopes`; its revenue area checks the grant separately. A non-empty list means the owner should reconnect via `authorizeChannel`. Same guard as `scopes` (`feature:connections` + `connections:read`); the REST twin carries the identical `missing_scopes`, computed by the same helper.

`channelOAuthScopes(platform: String!): ChannelOAuthScopes!` returns `{ platform required optional }` with full provider scope names for Twitch, YouTube, Kick or Spotify. `required` contains base scopes; `optional` contains scopes requested on every authorization but not counted by `missingScopes`. YouTube's optional list contains `https://www.googleapis.com/auth/yt-analytics-monetary.readonly`. It requires `feature:connections` and `connections:read`, like REST `GET /v1/connections/oauth-scopes/{platform}`. An unknown platform returns `Unsupported platform: X` on both protocols. Kick's required list includes `ads:read` for ad-break status.

`channelConnections { followerCount }` returns an optional `Int` for each channel. It is fetched only when selected, under `feature:connections` and `connections:read`. Twitch uses its follower total, YouTube returns an approximately rounded subscriber count, Kick accepts its string-valued follower count, and Spotify returns `null`. Counts are cached for 10 minutes, failed lookups for 2 minutes; stored public metrics provide a fallback. REST selects the same field with `GET /v1/connections/channel?include=follower_count`.

`channelConnections { paidSubscriberCount }` returns an optional `Int`: the channel's **current paid subscribers**. It is fetched only when selected and only for callers holding `history:read` (the permission of the Stream History "Subs & Members" metric). Without it the field is `null`, not an error, so a role with only `connections:read` still lists its connections. Twitch returns Helix `GET /subscriptions` `total` (gifted subs included; needs the channel scope `channel:read:subscriptions`, and an older grant without it returns `null` until the owner reconnects). Twitch does not document whether the broadcaster's own channel sub is part of `total`, so the number is passed through unchanged. Kick returns `active_subscribers_count` from the official `GET /public/v1/channels`. YouTube always returns `null`: channel memberships are not readable (Data API `members.list` is restricted to approved partners, InnerTube has no member count), and YouTube "subscribers" are its followers, reported in `followerCount`. Spotify returns `null`. The number is never estimated from events. Counts are cached for 10 minutes, unavailable ones for 2 minutes. The field is named *paid* because `subscriberCount` elsewhere in this API (`PublicChannelStats.subscriberCount`) means YouTube subscribers. REST selects the same field with `GET /v1/connections/channel?include=paid_subscriber_count`.

`channelStatus` requires `connections:read`, as does `GET /v1/channel-status`. The separate `spotifyManualStatus` operation still requires `spotify:read`.

`channelSchedule(from: DateTime, to: DateTime): [ScheduledStream!]!` (permission `connections:read`) returns the stream plan of the account's connected channels, starting inside `from..to` and sorted by `startsAt`. `from` defaults to now, `to` to `from` + 30 days; a window with `to <= from` or longer than 60 days fails with `BAD_REQUEST`. Each `ScheduledStream` carries `platform`, `title` (empty when none), `category`, `startsAt`, `endsAt` (nullable), `isRecurring`, `url` (YouTube watch page; Twitch/Kick channel page) and `source` (`youtube_broadcast`, `twitch_schedule`, `kick_schedule`). YouTube comes from the worker's scheduled-broadcast rows, Twitch from Helix `GET /schedule` (cancelled and vacation segments dropped), Kick from the undocumented kick.com calendar. A platform that is unavailable contributes nothing instead of failing the list, and the slot covering *now* is left out while that platform is live. Twitch/Kick are cached for 10 minutes. REST twin: `GET /v1/channels/schedule`. Details: [Channel Status → Stream plan](../features/channel-status.md#stream-plan).

#### `connectionStatuses` - health-aware connection overview

`connectionStatuses` (permission `connections:read`) returns one `ConnectionStatus` per supported channel platform - the overview feature surfaces read (Music control, Events, Multichat, incl. popouts). `isConnected` is **health-aware**: it is `true` only when a connection exists *and* is not flagged `reconnectRequired` (ZAF-754), so a dead-grant connection never appears usable. `ConnectionStatus` also carries `reconnectRequired` and `expiresAt`; a connection exists iff `isConnected || reconnectRequired`. The REST counterpart is `GET /v1/connections/status` (same fields, permission and `feature:connections` gate). Popout tokens carrying `connections:read` may read this query; the first-party-only `flaggedConnections` query (ZAF-469) is unaffected.

`ConnectionStatus` additionally carries the acting user's **personal login-grant** health per platform (ZAF-1045), reported *separately* from the channel signal because the Multichat sends with the login grant, not the channel connection: `loginConnected` (login grant exists and is healthy) and `loginReconnectRequired` (login grant exists but is flagged - the send will fail until reconnected). Both are `false` with no login grant, no user context (fail-closed), or a platform not sent-to via a login grant. The channel `isConnected` / `reconnectRequired` are unchanged - the login fields are additive. `loginMissingScopes` (REST `login_missing_scopes`, same value) lists the scopes Lumio's login asks for that the acting user's stored login grant lacks (for example `moderator:manage:automod`); it is empty when nothing is missing, when the stored scopes are unknown (an empty array on older grants) or when there is no grant. OpenID identity scopes (`openid`, `email`, `profile`) are never reported.

`sendChatToPlatform` returns `GqlSendResult { sent, messageId, error, errorCode, platform }`. `errorCode` is a machine-readable code the client translates instead of parsing `error`: `login_reconnect_required` (the sender's login grant is dead - flagged `reconnect_required`, no crypto/DB internals in `error`), `internal_error` (scrubbed internal failure), or `send_failed` (the platform rejected the send; `error` carries its message). Absent on success. The REST twin `POST /v1/chat/send` returns the identical `error_code` + `platform`.

For `platform: "kick"`, `sendChatToPlatform` converts every word that exactly matches a known Kick emote into Kick's `[emote:ID:NAME]` markup before sending (same shared function as REST `POST /v1/chat/send`).

`emotes(platform, channelId)` (`feature:multichat` + `chat:read`) returns `GqlEmoteSet { provider, emotes, section }` with `GqlEmote { id, name, url, provider, animated, ownerId, subscribersOnly }`. `section` is set only for Kick's native sets (`channel` | `global` | `emojis`, `null` otherwise); `subscribersOnly` marks Kick sub-only emotes. The REST twin `GET /v1/emotes/{platform}/{channel_id}` returns the same values as `section` / `subscribers_only`. For Kick, every `channel`-section emote has `ownerId = "kick:<user id>"` (namespaced so it never collides with a numeric Twitch owner id) and `owners` lists that channel owner as `GqlEmoteOwner { id, displayName, avatarUrl }` (Kick `username` / `profile_pic`); `owners` is `null` when no set has an owner, and REST returns the same entries as an `owners` map keyed by id.

#### `platformCredentialModes` - where each connection's OAuth client comes from

`platformCredentialModes` (permission `connections:read` + `feature:connections`) returns one `PlatformCredentialMode` per `(platform, kind)` that has an OAuth mode. It is the backend truth the frontend reads instead of hardcoding which platforms Lumio operates with a global OAuth app. Fields:

- `platform` - platform slug.
- `kind` - `CHANNEL` or `BOT`. Channel and bot can differ per platform (e.g. YouTube channel is `ACCOUNT`, YouTube bot is `SYSTEM`).
- `mode` - `SYSTEM` (global Lumio app) or `ACCOUNT` (per-account `app_credentials`). This is the *configured* intent, before fail-safe degradation.
- `systemConfigured` - whether global OAuth keys are actually configured. **Not** derivable from `mode`: `SYSTEM` + `systemConfigured=false` means "should be Lumio-managed but is not set up" (it degrades to `ACCOUNT` at runtime).

Platforms without an OAuth mode for a kind are omitted (Spotify has no bot; Discord has no channel connection). The Discord bot has a `BOT` row: `mode` is always `SYSTEM` (the one global bot; an `"account"` override in `[platform_credentials.bot]` is ignored with a warning) and `systemConfigured` is `true` once `[auth].discord_bot_client_id` and `discord_bot_client_secret` are set. The REST twin is `GET /v1/connections/credential-modes` - identical payload, kind included, same guard.

#### `me { activeAccountId }` - stale-membership filtering

If the JWT carries an `accountId` the user is no longer a member of (e.g. the
account owner removed them after the token was issued), the resolver returns
`activeAccountId: null` rather than the stale claim. Permissions are computed
against the corrected scope. The dashboard shell reads this signal and routes
the user to onboarding instead of rendering an account context they can no
longer access.

The REST `DELETE /v1/accounts/{id}/members/{membership_id}` (admin kick) and `POST /v1/accounts/{id}/leave` (self-leave) endpoints invalidate the Redis permission cache for the removed user, matching the existing GraphQL `removeMember` mutation behaviour - two-protocol parity for cache invalidation.

### Mutations

#### `adminUpdateUserAccountCreationOverride(userId: UUID!, override: AccountCreationOverride!): AdminUser!`

Set or clear the per-user `system:account_creation` override. Requires `users:edit` admin permission. Invalidates the cached override for the user immediately. Returns the updated `AdminUser`.

### Types

#### `FeatureStatusGql`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Feature flag key (e.g., `feature:bots`) |
| `enabled` | `Boolean!` | Whether the feature is enabled for this caller |
| `reason` | `FeatureDisabledReasonGql` | Why the feature is disabled; `null` when enabled |

#### `FeatureDisabledReasonGql` (enum)

| Value | Meaning |
|-------|---------|
| `GLOBAL_OFF` | The flag is turned off globally by an admin kill-switch |
| `PLAN_LOCKED` | The account's plan does not include this feature |
| `ACCOUNT_OVERRIDE` | An explicit per-account override blocks this feature |
| `USER_OVERRIDE` | An explicit per-user override blocks this feature (`system:account_creation` only) |

#### `AccountCreationOverride` (enum)

| Value | Description |
|-------|-------------|
| `DEFAULT` | Inherit the global `system:account_creation` flag setting |
| `ALLOW` | User is always allowed to create accounts (overrides global OFF) |
| `DENY` | User is always blocked from creating accounts (overrides global ON) |

#### `AdminUser.accountCreationOverride: AccountCreationOverride!`

Available on the `AdminUser` type returned by `adminUser(id)` and the user-list query. Reflects the stored per-user override value.

> **Protocol parity:** All queries and mutations above have matching REST endpoints - see [REST API](./rest-api.md#feature-flags--status).

## User API Keys

User API keys are personal `lm_usr_` bearer credentials for API and CLI access. They are bound to the current user and active account, and the requested permissions must be a subset of the creator's current permissions. The full key is returned only from `createUserApiKey`.

> **First-party session required (ZAF-1017 / ZAF-469):** personal API keys are a first-party surface - `userApiKeys`, `createUserApiKey`, `updateUserApiKey` and `deleteUserApiKey` all key off the acting user's own identity and require a logged-in user session or a user's own API key. A popout/overlay/widget/extension token - whose `user_id` is bound at token-create time and could be the account owner - is rejected with a `FORBIDDEN` error, so a permission-capped member can never list/mint/rename/revoke a key **bound to the owner**. Same gate and status behaviour as the REST `/v1/api-keys` twins. `createUserApiKey` and `rotateUserApiKey` are stricter still - **session-only** (ZAF-1742): they mint a secret, so a user's own `lm_usr_` key is refused with `FORBIDDEN` `This action requires an interactive sign-in session` (see [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces)).

### Queries

#### `apiKeyAssignablePermissions(kind: ApiKeyKind!): [ApiKeyPermission!]!`

List the scopes assignable to an API key of the given `kind` (`PERSONAL` or `SERVICE`). Requires `feature:apikeys` and `apikeys:read`. Parity with REST `GET /v1/api-keys/permissions`.

The registry is **derived** from the RBAC registries minus a small deny-list - an API key may carry any permission the principal behind it holds, not the narrow popout-token list (ZAF-1169):

- `PERSONAL` (`lm_usr_`) → the 129 account permissions left after the four-key API-key deny-list **plus** the 10 user-scoped `ideas:*` permissions (**139** assignable scopes). A personal key acts with its member's user identity.
- `SERVICE` (`lm_svc_`) → those 129 assignable account permissions only (an account-owned key has no user identity).
- **Deny-list (both):** `apikeys:create`, `apikeys:edit`, `tokens:create` (credential minting) and `account:delete` (tenant destruction) are never assignable.

Each field is `{ key, label, category }`, grouped by `category` for the picker. Scopes are validated against this registry on create (unknown/deny-listed → `Invalid permission: {perm}`) and are **immutable after creation**.

```graphql
query {
  apiKeyAssignablePermissions(kind: PERSONAL) {
    key
    label
    category
  }
}
```

#### `userApiKeys: [UserApiKey!]!`

List the current user's own API keys for the active account. Requires `feature:apikeys` and `apikeys:read`.

```graphql
query {
  userApiKeys {
    id
    userId
    accountId
    keyPrefix
    label
    permissions
    createdAt
    expiresAt
    lastUsedAt
  }
}
```

### Mutations

#### `createUserApiKey(input: CreateUserApiKeyInput!): CreateUserApiKeyResult!`

Create a user API key for the current user and active account. Requires `feature:apikeys` and `apikeys:create`.

```graphql
mutation {
  createUserApiKey(
    input: {
      label: "CI/CD pipeline"
      permissions: ["events:read", "overlays:read"]
      expiresAt: "2026-09-01T00:00:00Z"
    }
  ) {
    key
    apiKey {
      id
      keyPrefix
      label
      permissions
      expiresAt
    }
  }
}
```

#### `rotateUserApiKey(id: UUID!): CreateUserApiKeyResult!`

Rotate one of the current user's own API keys - regenerate its secret in place. Requires `feature:apikeys` and `apikeys:edit`. The key id, label, scopes and expiry are unchanged, the old secret stops working immediately, and the new full `lm_usr_` key is returned in `key` **once** (same [`CreateUserApiKeyResult`](#createuserapikeyresult) shape as create - `{ key, apiKey }`). Emits the `user:api_key_rotated` audit event (metadata `api_key_id`, `old_key_prefix`, `new_key_prefix`). Parity with REST `POST /v1/api-keys/{id}/rotate`.

#### `deleteUserApiKey(id: UUID!): DeleteTokenResult!`

Revoke one of the current user's own API keys by hard-deleting it. Requires `feature:apikeys` and `apikeys:delete`.

### Types

#### `CreateUserApiKeyInput`

| Field | Type | Description |
|-------|------|-------------|
| `label` | `String!` | Required display name |
| `permissions` | `[String!]!` | Permission subset granted to the key |
| `expiresAt` | `String` | Optional RFC3339 expiry; `null` means no expiry |

#### `CreateUserApiKeyResult`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Full `lm_usr_` key, returned once |
| `apiKey` | `UserApiKey!` | Stored key metadata |

#### `UserApiKey`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Key ID |
| `userId` | `UUID!` | Owning user |
| `accountId` | `UUID!` | Owning account |
| `keyPrefix` | `String!` | Display prefix for identification |
| `label` | `String!` | Display name |
| `permissions` | `[String!]!` | Granted permission subset, as stored |
| `effectivePermissions` | `[String!]!` | The stored scopes the owner's current role still grants - what authorizes requests now. A scope missing here is dormant and returns when the owner regains it. Same as REST `effective_permissions` |
| `createdAt` | `String!` | Creation timestamp |
| `expiresAt` | `String` | Optional expiry timestamp |
| `lastUsedAt` | `String` | Last successful use, when known (minute precision: rewritten at most once a minute) |

#### `ApiKeyKind`

`PERSONAL` (`lm_usr_`) or `SERVICE` (`lm_svc_`). Used as the argument to `apiKeyAssignablePermissions`, as the discriminator on the [Admin API Key](#admin-api-key-management) mutations, and as the [`AdminApiKey`](#adminapikey) `kind` field.

#### `ApiKeyPermission`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Permission string (`resource:action`) |
| `label` | `String!` | Human-readable label |
| `category` | `String!` | Grouping category for the picker |

## Account Service Keys

Account service keys are `lm_svc_` bearer credentials owned by the **account** - for CI/CD and long-lived integrations that must **survive the departure of the member who created them**. Unlike personal `lm_usr_` keys they carry no member identity. They share the `feature:apikeys` flag and the `apikeys:*` permission family with personal keys, and create enforces the same permission-subset guard. The full key is returned only from `createAccountServiceKey`. Parity with REST `/v1/service-keys`.

### Queries

#### `accountServiceKeys: [AccountServiceKey!]!`

List the account's service keys. Requires `feature:apikeys` and `apikeys:read`.

### Mutations

#### `createAccountServiceKey(input: CreateAccountServiceKeyInput!): CreateAccountServiceKeyResult!`

Create a service key owned by the active account. Requires `feature:apikeys`, `apikeys:create` and an **interactive sign-in session** (a logged-in user only - a popout/overlay/widget/extension token, a personal `lm_usr_` key, a service `lm_svc_` key or a system key is rejected with `FORBIDDEN` "This action requires an interactive sign-in session"; ZAF-1742 rule, applied to service keys by ZAF-1740 C3). Parity with REST `POST /v1/service-keys`.

```graphql
mutation {
  createAccountServiceKey(
    input: {
      label: "CI/CD deploy"
      permissions: ["events:read", "overlays:read"]
    }
  ) {
    key
    serviceKey {
      id
      keyPrefix
      label
      permissions
      expiresAt
    }
  }
}
```

#### `updateAccountServiceKey(id: UUID!, label: String!): AccountServiceKey!`

Rename a service key (label only; key material, permissions and expiry are immutable). Requires `feature:apikeys` and `apikeys:edit`.

#### `rotateAccountServiceKey(id: UUID!): CreateAccountServiceKeyResult!`

Rotate a service key - regenerate its secret in place. Requires `feature:apikeys`, `apikeys:edit` and an **interactive sign-in session** (same session-only gate as create, checked before the key is looked up), and the caller must hold every scope on the key - the same ceiling as create, rejected with `FORBIDDEN` "Cannot grant permission '…'" otherwise (ZAF-1740 M5). The key id, label, scopes and expiry are unchanged, the old secret stops working immediately, and the new full `lm_svc_` key is returned in `key` **once** (same [`CreateAccountServiceKeyResult`](#createaccountservicekeyresult) shape as create - `{ key, serviceKey }`). Emits the `account:service_key_rotated` audit event (metadata `service_key_id`, `old_key_prefix`, `new_key_prefix`). Parity with REST `POST /v1/service-keys/{id}/rotate`.

#### `deleteAccountServiceKey(id: UUID!): DeleteTokenResult!`

Revoke a service key by hard-deleting it. Requires `feature:apikeys` and `apikeys:delete`.

### Types

#### `CreateAccountServiceKeyInput`

| Field | Type | Description |
|-------|------|-------------|
| `label` | `String!` | Required display name |
| `permissions` | `[String!]!` | Permission subset granted to the key |
| `expiresAt` | `String` | Optional RFC3339 expiry; `null` means no expiry |

#### `CreateAccountServiceKeyResult`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Full `lm_svc_` key, returned once |
| `serviceKey` | `AccountServiceKey!` | Stored key metadata |

#### `AccountServiceKey`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Key ID |
| `accountId` | `UUID!` | Owning account |
| `createdBy` | `UUID` | Member who minted the key; `null` once they leave the account |
| `keyPrefix` | `String!` | Display prefix for identification |
| `label` | `String!` | Display name |
| `permissions` | `[String!]!` | Granted permission subset |
| `createdAt` | `String!` | Creation timestamp |
| `updatedAt` | `String!` | Last modification timestamp |
| `expiresAt` | `String` | Optional expiry timestamp |
| `lastUsedAt` | `String` | Last successful use, when known (minute precision: rewritten at most once a minute) |

## Developer API Keys

Developer API keys (`lm_dev_`, ZAF-1176) are the publishing credential for extension developers. Unlike account service keys they are **not** account-owned: a developer key is bound to a developer **profile** or **team**, carries no account and no member identity (so it survives the minting member's departure), and can carry **only** the `extension-dev:*` permission family. Eligibility is approved-developer status, not the Pro plan - the create path is **not** gated on `feature:apikeys`. Management is **first-party only** (`require_first_party_user`): a `lm_dev_` key can never mint or revoke another developer key. `createDeveloperApiKey` is **session-only** (`require_session_user`, ZAF-1742): a user's own `lm_usr_` key cannot mint one either. The full key is returned only from `createDeveloperApiKey`. Parity with REST `/v1/developer/api-keys`.

### Queries

#### `developerApiKeys: [DeveloperApiKey!]!`

Lists the caller's developer keys - their own profile keys plus keys on teams they belong to.

### Mutations

- `createDeveloperApiKey(input: CreateDeveloperApiKeyInput!): CreateDeveloperApiKeyResult!` - mint a key; scopes are validated against the developer-key registry (the `extension-dev:*` family) and the creator-subset guard. A `teamId` binds the key to a developer team and requires the team's `team-secrets:edit` right; omit it to bind to your own developer profile.
- `updateDeveloperApiKey(id: UUID!, label: String!): DeveloperApiKey!` - rename (label only).
- `revokeDeveloperApiKey(id: UUID!): DeleteTokenResult!` - soft-revoke; the auth layer then fails closed on the revoked key.

Rename and revoke share one authorization path with REST: a missing or foreign key fails with `Not found: Developer key not found` (code `NOT_FOUND`); a **team** key additionally requires the caller's current developer-team right `team-secrets:edit` on that team, else `Missing team permission: team-secrets:edit` (code `FORBIDDEN`) - membership alone (e.g. the default **Member** role) is not enough for either action. A **profile** key is managed by its owner.

Lifecycle changes emit the **user-scoped** audit events `user:developer_api_key_created` / `user:developer_api_key_updated` / `user:developer_api_key_revoked`.

### Types

#### `CreateDeveloperApiKeyInput`

| Field | Type | Description |
|-------|------|-------------|
| `label` | `String!` | Required display name |
| `permissions` | `[String!]!` | Subset of the `extension-dev:*` family to grant |
| `teamId` | `UUID` | Bind to a developer team you belong to; `null` = your own developer profile |
| `expiresAt` | `String` | Optional RFC3339 expiry; `null` means no expiry |

#### `CreateDeveloperApiKeyResult`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Full `lm_dev_` key, returned once |
| `developerApiKey` | `DeveloperApiKey!` | Stored key metadata |

#### `DeveloperApiKey`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Key ID |
| `developerId` | `UUID` | Owning developer profile (`null` for a team key) |
| `teamId` | `UUID` | Owning developer team (`null` for a profile key) |
| `createdBy` | `UUID` | Member who minted the key; `null` once they leave |
| `keyPrefix` | `String!` | Display prefix for identification |
| `label` | `String!` | Display name |
| `permissions` | `[String!]!` | Granted `extension-dev:*` subset |
| `createdAt` | `String!` | Creation timestamp |
| `updatedAt` | `String!` | Last modification timestamp |
| `expiresAt` | `String` | Optional expiry timestamp |
| `lastUsedAt` | `String` | Last successful use, when known (minute precision: rewritten at most once a minute) |

## Admin Role Management

The following queries and mutations are admin-scope: they check the caller's **admin permissions** (not account permissions) and return errors for unauthenticated or unauthorized requests.

### Queries

#### `adminRoles: [AdminRole!]!`

List all admin roles with their permissions and member counts. Requires `admin-roles:read`.

#### `adminRole(id: UUID!): AdminRole!`

Get a single admin role by ID. Requires `admin-roles:read`. Returns `"Admin role not found"` if the ID does not exist.

#### `adminRoleMembers(roleId: UUID!): [AdminRoleMember!]!`

List all users assigned to an admin role. Requires `admin-roles:read`.

#### `allAdminPermissions: [AdminPermissionInfo!]!`

Return the full catalog of admin-scope permissions with their category labels. Requires `admin-roles:read`. Source: `lo_auth::rbac::all_admin_permissions()`. Used by the permission picker UI.

#### `adminSystemKeyPermissions: [AdminPermissionInfo!]!`

Return every scope assignable to a [System key](../admin/system-keys.md), each with its category. Requires `system-keys:read`. Source: `lo_auth::rbac::system_key::get_assignable_permission_infos()` - the derived registry (admin ∪ account ∪ user minus the credential-minting / tenant-destruction deny-list, ZAF-1213), the same set `adminCreateSystemKey` validates against. Guarded on `system-keys:read` (not `admin-roles:read`) so the operator who mints keys can read it. Parity: REST `GET /v1/admin/system-key-permissions`.

### Mutations

#### `adminCreateRole(input: CreateAdminRoleInput!): AdminRole!`

Create a new admin role. Requires `admin-roles:create`.

- Auto-injects `admin:access` into the permissions list if not present
- Validates all permissions against `all_admin_permissions()` - rejects unknown permissions with `"Invalid permission: <perm>"`
- Returns `"Role name already in use"` on duplicate name

#### `adminUpdateRole(id: UUID!, input: UpdateAdminRoleInput!): AdminRole!`

Update an existing admin role. Requires `admin-roles:edit`.

- Fields are optional: omit to leave unchanged
- `description: null` clears the description; omitting it leaves it unchanged
- Permissions are applied as a diff against known permissions (unknown/legacy permissions are preserved)
- Same validation as create; `is_system = true` roles are fully editable (not protected from edits)

#### `adminDeleteRole(id: UUID!): Boolean!`

Delete an admin role. Requires `admin-roles:delete`.

- Returns `true` if deleted
- Rejects with `"Cannot delete system admin role"` if `is_system = true`
- Cascades to `admin_role_permissions` and `user_admin_roles`

#### `adminAssignUserRole(userId: UUID!, roleId: UUID!): Boolean!`

Assign a user to an admin role. Requires `admin-roles:edit`. Idempotent - returns `true` if a new assignment was created, `false` if already assigned.

#### `adminUnassignUserRole(userId: UUID!, roleId: UUID!): Boolean!`

Remove a user's admin role assignment. Requires `admin-roles:edit`. Returns `true` if removed.

### Types

#### `AdminRole`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Role ID |
| `name` | `String!` | Display name |
| `description` | `String` | Optional description |
| `isSystem` | `Boolean!` | System roles cannot be deleted |
| `permissions` | `[String!]!` | Sorted permission strings |
| `memberCount` | `Int!` | Number of assigned users |
| `createdAt` | `String!` | ISO-8601 timestamp |
| `updatedAt` | `String!` | ISO-8601 timestamp |

#### `AdminRoleMember`

| Field | Type | Description |
|-------|------|-------------|
| `userId` | `UUID!` | User ID |
| `displayName` | `String!` | User display name |
| `email` | `String` | User email |
| `avatarUrl` | `String` | User avatar URL |
| `assignedAt` | `String!` | ISO-8601 timestamp |

#### `AdminPermissionInfo`

| Field | Type | Description |
|-------|------|-------------|
| `permission` | `String!` | Permission string (e.g., `admin-roles:read`) |
| `category` | `String!` | Category label (e.g., `Admin Role Management`) |

#### `CreateAdminRoleInput`

| Field | Type | Required |
|-------|------|----------|
| `name` | `String!` | Yes |
| `description` | `String` | No |
| `permissions` | `[String!]!` | Yes (may be empty) |

#### `UpdateAdminRoleInput`

| Field | Type | Notes |
|-------|------|-------|
| `name` | `String` | Optional; trimmed |
| `description` | `String` | `null` = clear, omit = leave unchanged |
| `permissions` | `[String!]` | Optional; replaces via diff |

> **Protocol parity:** All queries and mutations above have matching REST endpoints under `/v1/admin/admin-roles` and `/v1/admin/admin-permissions` - see [REST API](./rest-api.md).

## Admin API Key Management

Platform-operator management of **any** account's or user's API keys, for support and incident response. These are **admin-scope** (checked against the caller's admin role via `AdminPermissionGuard`, the `account-apikeys:*` family) - distinct from the account-scope `apikeys:*` a member uses on their own keys ([`userApiKeys`](#user-api-keys) / [`accountServiceKeys`](#account-service-keys)). No field ever exposes a key's secret except the one-time `adminRotateApiKey` result. `kind` is the [`ApiKeyKind`](#apikeykind) enum - `PERSONAL` (`lm_usr_`, in `api_keys`) or `SERVICE` (`lm_svc_`, in `account_service_keys`). Parity with the REST endpoints under [`/v1/admin/.../api-keys`](./rest-api.md#admin-api-keys).

### Queries

#### `adminAccountApiKeys(accountId: UUID!): [AdminApiKey!]!`

List an account's API keys - **both** kinds (its members' personal `lm_usr_` keys and the account's `lm_svc_` service keys). Requires `account-apikeys:read`. Each item is an [`AdminApiKey`](#adminapikey) carrying non-secret metadata only - never the secret.

#### `adminUserApiKeys(userId: UUID!): [AdminApiKey!]!`

List a user's personal `lm_usr_` API keys (service keys have no owning user). Requires `account-apikeys:read`.

### Mutations

#### `adminUpdateApiKey(kind: ApiKeyKind!, id: UUID!, label: String!, permissions: [String!]!): AdminApiKey!`

Edit a key's `label` and `permissions` (scopes). Requires `account-apikeys:edit`. Scope edits validate against the assignable-scope registry for the key's `kind` (ZAF-1170) - an unknown, deny-listed, or user-scoped-on-a-`SERVICE`-key scope is rejected. For a `PERSONAL` key the scopes are additionally capped to the key **owner's** own grantable permissions; for a `SERVICE` key the account is the principal, so the registry minus the deny-list is the ceiling - an operator can never push a key above its own principal. A blank label is rejected. Emits `system:api_key_updated`.

#### `adminRotateApiKey(kind: ApiKeyKind!, id: UUID!): AdminApiKeyRotated!`

Rotate a key - regenerate its secret in place (id, label and scopes unchanged; old secret invalidated immediately). Requires `account-apikeys:rotate`. Returns an [`AdminApiKeyRotated`](#adminapikeyrotated) `{ key, apiKey }`: `key` is the new full secret (`lm_usr_` / `lm_svc_`), returned **once**; `apiKey` is the updated non-secret metadata. Emits `system:api_key_rotated` (metadata `old_key_prefix`, `new_key_prefix`).

#### `adminDeleteApiKey(kind: ApiKeyKind!, id: UUID!): Boolean!`

Revoke (hard-delete) a key. Requires `account-apikeys:delete`. **Idempotent** - deleting an already-gone key resolves to the same not-found result. Emits `system:api_key_revoked`.

All three mutations emit a **system-scope** audit event with the operator as the actor (`user_id`) and the target `kind` / `api_key_id` / `account_id` / (personal only) `user_id` in metadata; these rows land only in the operator log, never in the target account's or user's own audit log.

### Types

#### `AdminApiKey`

A tenant/user API key as seen by a platform operator - never exposes the secret. Covers both kinds via the `kind` discriminator.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Key ID |
| `kind` | `ApiKeyKind!` | `PERSONAL` (`lm_usr_`) or `SERVICE` (`lm_svc_`) |
| `accountId` | `UUID!` | Owning account |
| `userId` | `UUID` | Key owner (personal keys); `null` for service keys |
| `createdBy` | `UUID` | Member who created a service key; `null` once they leave / for personal keys |
| `keyPrefix` | `String!` | Display prefix (e.g. `lm_usr_ab`); the full key is never returned by list |
| `label` | `String!` | Display name |
| `permissions` | `[String!]!` | Granted scopes |
| `createdAt` | `String!` | Creation timestamp |
| `expiresAt` | `String` | Expiry; `null` = never |
| `lastUsedAt` | `String` | Last successful use, when known (minute precision: rewritten at most once a minute) |

#### `AdminApiKeyRotated`

Result of `adminRotateApiKey` - the new full key, shown exactly once.

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | New full `lm_usr_` / `lm_svc_` key, returned once |
| `apiKey` | `AdminApiKey!` | The rotated key's updated non-secret metadata |

## Admin Account Membership

These fields use admin-scope permissions. The role read and member mutation have matching REST endpoints under `/v1/admin/accounts/`.

### `adminAccountRoles(accountId: UUID!): [AdminAccountRole!]!`

List the account's roles in sort order for the add-member role picker. Requires `accounts:read`. Returns `"Not found: Account not found"` when the account does not exist. Each `AdminAccountRole` carries `id`, `slug`, `name`, nullable `color`, `isSystem`, `isDefault`, and `sortOrder`. The API includes the Owner role; the admin dialog excludes it from its choices.

### `adminAddAccountMember(accountId: UUID!, userId: UUID!, roleId: UUID!): AdminAccountDetail!`

Add a user to an account with a required role belonging to that account. Requires `accounts:edit`. A missing `roleId` fails GraphQL input validation; a role from another account or an unknown role returns `"Not found: Role not found for this account"`. On success, returns the account detail and emits `system:account_member_added` with the selected `role_id`; adding a user who is already a member changes nothing and emits no event.

## Admin Account Limits

`adminSetAccountLimits(accountId, input)` requires `accounts:edit`. The optional `input.chatRetentionDays` override must be 0–1095 days; values outside that range return `"chat_retention_days must be between 0 and 1095 days (the published maximum)"`. Omit the field to keep the existing override. The retention sweeps use the account override when set, otherwise the plan value. Its REST twin is `PUT /v1/admin/accounts/{id}/limits`.

## Plan Management

Admin-scope queries and mutations for managing subscription plans. All check `plans:*` admin permissions.

### Queries

#### `adminPlans: [AdminPlan!]!`

List all plans with their feature assignments and account counts. Requires `plans:read`.

### Mutations

#### `adminCreatePlan(input: AdminCreatePlanInput!): AdminPlan!`

Create a new plan. Requires `plans:create`.

- Validates `slug` against regex `^[a-z0-9]+(?:-[a-z0-9]+)*$`, length 2–40 chars. Returns `"Invalid slug format"` on failure.
- Rejects duplicate slugs with `"Plan slug already in use"`.
- Rejects negative prices / limits with `"Price cannot be negative"` / `"Limit cannot be negative"`. `chatRetentionDays` must be 0–1095; outside that range the error is `"chat_retention_days must be between 0 and 1095 days (the published maximum)"`. `0` is not unlimited: it means the 1095-day maximum for all channel data.
- `currency` defaults to `"USD"` if omitted.
- Stripe IDs are optional free-text strings. Lumio does not call Stripe - paste IDs from the Stripe dashboard.

#### `adminUpdatePlan(id: UUID!, input: AdminUpdatePlanInput!): AdminPlan!`

Update an existing plan. Requires `plans:edit`.

- `slug` is **immutable** and is not part of `AdminUpdatePlanInput`. To change a slug, create a new plan, migrate accounts, then delete the old one.
- All input fields rewrite the plan's editable state. `chatRetentionDays` must be 0–1095; outside that range the error is `"chat_retention_days must be between 0 and 1095 days (the published maximum)"`.
- On success, invalidates the feature cache for every account currently on the plan.
- Returns `"Plan not found"` if no plan has the given ID.

#### `adminDeletePlan(id: UUID!): Boolean!`

Delete a plan. Requires `plans:delete`. Returns `true` on success.

- Returns `"Plan not found"` if no plan has the given ID.
- Returns `"Cannot delete plan: N account(s) still reference it. Migrate them to a different plan first."` if any accounts are still on the plan.
- Cascades to `plan_features` via the FK constraint.

### Types

#### `AdminPlan`

```graphql
type AdminPlan {
  id: UUID!
  slug: String!
  name: String!
  description: String
  priceMonthly: Int!
  priceYearly: Int!
  currency: String!
  isPublic: Boolean!
  sortOrder: Int!
  maxOverlays: Int!
  maxStorageBytes: Int!
  maxUploadSizeBytes: Int!
  maxIntegrations: Int!
  chatRetentionDays: Int!
  maxSettingPresets: Int!
  stripeProductId: String
  stripeMonthlyPriceId: String
  stripeYearlyPriceId: String
  features: [AdminPlanFeature!]!
  accountsUsing: Int!
}
```

#### `AdminPlanFeature`

```graphql
type AdminPlanFeature {
  featureId: UUID!
  featureKey: String!
  label: String!
  enabled: Boolean!
}
```

#### `AdminCreatePlanInput`

```graphql
input AdminCreatePlanInput {
  slug: String!
  name: String!
  description: String
  priceMonthly: Int!
  priceYearly: Int!
  currency: String
  isPublic: Boolean!
  sortOrder: Int!
  maxOverlays: Int!
  maxStorageBytes: Int!
  maxUploadSizeBytes: Int!
  maxIntegrations: Int!
  chatRetentionDays: Int!
  maxSettingPresets: Int!
  stripeProductId: String
  stripeMonthlyPriceId: String
  stripeYearlyPriceId: String
}
```

#### `AdminUpdatePlanInput`

```graphql
input AdminUpdatePlanInput {
  name: String!
  description: String
  priceMonthly: Int!
  priceYearly: Int!
  currency: String!
  isPublic: Boolean!
  sortOrder: Int!
  maxOverlays: Int!
  maxStorageBytes: Int!
  maxUploadSizeBytes: Int!
  maxIntegrations: Int!
  chatRetentionDays: Int!
  maxSettingPresets: Int!
  stripeProductId: String
  stripeMonthlyPriceId: String
  stripeYearlyPriceId: String
}
```

`AdminUpdatePlanInput` intentionally has no `slug` field - slugs are immutable after creation.

> **Protocol parity:** All queries and mutations above have matching REST endpoints under `/v1/admin/plans` - see [REST API](./rest-api.md#admin-plan-management).

## Public Pricing

Public, auth-optional queries used by the marketing pricing surfaces (`/pricing`, landing page, dashboard onboarding, `/dashboard/settings/channel/subscription`).

### `plans`

Returns every plan where `is_public = true`, ordered by `sort_order`. Admin-only `is_public = false` plans are filtered out.

```graphql
type BillingPlan {
  id: UUID!
  slug: String!
  name: String!
  description: String
  priceMonthly: String!
  priceYearly: String!
  currency: String!
  isPublic: Boolean!
  sortOrder: Int!
  maxOverlays: Int!
  maxStorageBytes: String!
  maxUploadSizeBytes: String!
  maxIntegrations: Int!
  chatRetentionDays: Int!
  features: [PlanFeature!]!
}

type PlanFeature {
  featureId: UUID!
  featureKey: String!
  label: String!
  enabled: Boolean!
  "True when the underlying feature_flag kill-switch is on. Effective availability = enabled && globallyEnabled."
  globallyEnabled: Boolean!
}
```

**`features[]` semantics:** Only flags whose `category` is in `('feature', 'widget', 'integration', 'bot_module')` are returned - `platform:*`, `system:*`, `automation:*`, `copyright_provider:*`, and `event:*` are admin/infrastructure concerns and stay off the pricing card. The query uses a `LEFT JOIN` on `plan_features` with `COALESCE(pf.enabled, false)` - a flag without an explicit `plan_features` row renders as struck-through on every plan card (fail-closed). To include a flag in a plan, add a matching `plan_features` row via migration (see `apps/api/migrations/20260415000008_backfill_plan_features_matrix.up.sql` for the canonical pattern).

### `enabledPlatforms`

```graphql
extend type Query {
  enabledPlatforms: [String!]!
}
```

Returns the list of streaming platform slugs whose kill-switch is globally enabled AND which have an enabled `:login` or `:bot` sub-flag. Used by the "Supported Platforms" badge row on every pricing card.

Integration-only platforms (currently Spotify - channel-OAuth only, no login and no chat bot) are **intentionally excluded** so they don't appear as streaming destinations on pricing cards, even though their kill-switch is on.

The companion resolver `enabledProviders(connectionType: "login" | "channel" | "bot")` returns the full per-subtype list and is what the ID app's login page and the `/dashboard/settings/security/login` use.

## Public Songs and Playlists

These unauthenticated reads use the fail-closed `feature:copyright_detection` gate. The feature is resolved for the caller's account when one is signed in, otherwise globally. A disabled feature returns `FEATURE_DISABLED`; no `copyright:*` permission is required. REST twins are listed in [Public REST endpoints](/features/copyright#public-rest-endpoints).

| Query | Arguments | Result |
|---|---|---|
| `publicSafeSongs`, `publicBlockedSongs` | Optional `search`, `limit`, `offset` | Paginated global safe or blocked songs. |
| `publicSong` | `id: UUID!` | One global safe or blocked song, or `null` for an unknown or account-owned ID; twin of `GET /v1/songs/{id}`. |
| `publicSongSitemap` | Optional `after: UUID`, `first: Int` | `items { id lastmod }` and `hasMore`; twin of `GET /v1/songs/sitemap`. |
| `publicSystemPlaylists` | None | System-curated playlist summaries. |
| `publicSystemPlaylist` | `id: UUID!` | One system-curated playlist, or `null` for an unknown ID; twin of `GET /v1/playlists/{id}`. |
| `publicSongStatus` | Optional `spotifyTrackId`, `isrc`, `title`, `artist` | Global copyright status. |

For `publicSongSitemap`, pass the last item's `id` as `after` while `hasMore` is true. `first` defaults to and is capped at 5,000. The server determines which global lists to include (safe and blocked); `lastmod` is the song's `created_at` or `null`. The public music detail pages read `publicSong` and `publicSystemPlaylist` by ID.

## Shopify

The account connection operations need `integration:shopify` plus the listed permission; `hideShopifyOrderName` needs `events:edit` without the plan flag. REST twins in [REST → Shopify](./rest-api.md#shopify) use the same guards, fields and messages. Details: [Shopify](/features/shopify).

| Operation | Permission | Returns |
|-----------|-----------|---------|
| `shopifyConnection` | `connections:read` | `ShopifyConnectionStatus { configured, appStoreUrl, connection: ShopifyConnection }` |
| `shopifyLinkRequest(handle: String!)` | `connections:create`, interactive session | `ShopifyLinkRequest { shopHost, state }` — the store a link request comes from; a request another user confirmed is deleted (`CONFLICT`, as REST `409`) |
| `shopifyLinkConfirm(handle: String!)` | `connections:create`, interactive session, not cross-site | `ShopifyLinkRequest` — binds the request to the active account; a request confirmed for another account is deleted (`CONFLICT`) |
| `updateShopifySettings(customerDisplay: String, showItems: Boolean, showPrice: Boolean)` | `connections:edit` | `ShopifyConnection` — at least one argument |
| `disconnectShopify` | `connections:delete` | `Boolean!` |
| `hideShopifyOrderName(eventId: UUID!, createdAt: String!)` | `events:edit` (no plan gate) | `Boolean!` — removes the buyer label of one Shopify order (both of its events); `false` when there was none left |

`ShopifyConnection` has `shopHost`, `shopName`, `status` (`connected` / `needs_reconnect`), `customerDisplay`, `showItems`, `showPrice`, `scopes`, `enabled`, `connectedAt`. `customerDisplay` defaults to `none`; `showItems` defaults to `true`, `showPrice` to `false`. Settings affect later orders: `raw.line_items` is absent when `showItems` was off, and `raw.total_price`, `raw.currency` and item `price` are absent when `showPrice` was off. `shopifyLinkConfirm` refuses a browser request whose `Sec-Fetch-Site` is not `same-origin`, like its REST twin. The embedded app's endpoints (`/v1/shopify/embedded/*`, Shopify ID token) are REST-only: their caller is not a Lumio principal ([REST → Embedded app](./rest-api.md#embedded-app-v1shopifyembedded)).

## Discord Bot Connections

`authorizeBot(platform: "discord")` returns the verified invite URL for the one global Lumio bot. It requires `bot-connections:create`, `feature:bots`, and an interactive session. The invite uses `bot applications.commands identify`; after the unified callback verifies the Discord code, it links the server ID returned by Discord to the active account. The equivalent REST authorize endpoint is `GET /v1/bot-connections/discord/authorize`.

`discordGuildConnections` requires `bot-connections:read` and returns each server with `botRemoved` and `missingPermissions`. `disconnectDiscordGuild(guildId)` requires `bot-connections:delete` and removes the server mapping and settings. Their REST twins are `GET /v1/discord-guilds` and `DELETE /v1/discord-guilds/{guild_id}`; they enforce the same account guards and emit the same disconnect audit event. See [Bot Connections](/features/bot-connections#discord-servers).

## Login Assignments

Login assignments link an assignable login connection to a specific Lumio account, enabling multi-account ownership from a single user identity. Discord is sign-in-only and cannot be assigned.

> **Own assignments are always allowed without permissions.** The `login-assignments:*` permissions only apply when managing assignments on behalf of another user.

### Queries

#### `accountLoginAssignments(userId: UUID): [GqlLoginAssignment!]!`

List all login assignments for the caller's active account. When `userId` is supplied, returns the assignments for that specific user (requires `login-assignments:read`). When omitted, returns the caller's own assignments.

```graphql
query {
  accountLoginAssignments {
    provider
    loginConnectionId
    userId
    assignedAt
  }
}
```

### Mutations

#### `assignLoginConnection(loginConnectionId: UUID!, provider: String!, userId: UUID, accountId: UUID): GqlLoginAssignment!`

Assign a login connection to an account. `userId` defaults to the authenticated user when omitted. Requires `login-assignments:create` to assign on behalf of another user; own assignments are always allowed. If either the requested provider or the stored connection provider is Discord, it fails with `This sign-in method is login-only and cannot be assigned to a channel` (`BAD_REQUEST`), byte-identical to the REST twin. A successful assignment emits `account:login_connection_assigned`.

#### `removeLoginAssignment(provider: String!, userId: UUID, accountId: UUID): Boolean!`

Remove the login assignment for the given provider from an account. `userId` defaults to the authenticated user. Requires `login-assignments:delete` to remove another user's assignment; own assignments are always allowed. Returns `true` on success, and emits `account:login_connection_removed` when a row was actually removed.

> **Which account is targeted.** `accountId` defaults to the caller's **active** account. A user-centric surface (the Profile page, and the ID App after an OAuth link) must always send the account the user picked, otherwise the assignment follows the account switcher instead of the UI (ZAF-1495). A supplied `accountId` must be an account the caller belongs to: on the caller's **own** login connection any account from their membership list is accepted — the same list the account picker offers; with `userId` set to another user the target is pinned to the active account, because `login-assignments:*` resolves against the active account's roles. Anything else fails with `You do not have access to the target account`. Identical decision on the REST twins.

#### `disconnectLoginConnection(loginConnectionId: UUID!): LogoutResult!`

Delete a login connection by UUID. The connection must belong to the authenticated user. No special permission required beyond ownership. Returns `true` on success.

**Step-up:** after the "last sign-in method" check, the calling session needs a step-up in the last 10 minutes; otherwise the error carries `extensions.code` `STEP_UP_REQUIRED` ("Please confirm that it's you first") and nothing is deleted. Same code and message as `DELETE /v1/login-connections/{id}`. `startMfaSetup` and `enableMfa` need the same step-up. See [Authentication → Step-up before sign-in changes](../features/auth.md#step-up-before-sign-in-changes).

> **First-party user surface (ZAF-469):** `me`, `updateMe`, `disconnectLoginConnection`, `assignLoginConnection`, `removeLoginAssignment`, `setNameSourceConnection`, `flaggedConnections`, the session and notification operations, `myDeveloperApplication` / `submitDeveloperApplication`, `developerVerificationStatus` / `submitDeveloperVerification`, `createAccount` / `dissolveAccount` / `leaveAccount`, and the JWT-minting `issueWsToken` are all keyed on the acting user's *own* identity. The first-party gate admits a logged-in user session or the user's own API key; the identity-changing operations and `issueWsToken` listed in the session-only note below require an interactive session. A popout/overlay/widget/extension token - whose `user_id` is bound at token-create time and could be the account owner - is rejected with a `FORBIDDEN` error (so it can never obtain an owner-bound JWT). Same gate and status behaviour as the REST twins.

> **Session-only (ZAF-1742):** `disconnectLoginConnection`, `assignLoginConnection`, `removeLoginAssignment`, `setNameSourceConnection`, `updateDisplayName`, `removeAvatar` and `issueWsToken` refuse a user's own API key too. The channel name/picture mutations `setAccountIdentitySource`, `updateAccountName`, `removeAccountAvatar` and the deprecated `updateAccount` need an interactive session as well (see **Channel name and picture** below). `updateMe` does not set the profile email: `email` is deprecated and refused for every caller with `EMAIL_MANAGED_BY_LOGIN` (`Set your e-mail under Security › Sign-in › E-mail & password`). The account switch / clear (`activeAccountId`, `clearActiveAccount`) is session-only too, since it re-mints the session JWT (ZAF-1922). The other `updateMe` fields keep the first-party gate, and a non-session caller never receives a `token`. A JWT is only minted for a caller that already holds a session: `createAccount` returns `token: null` (`CreateAccountResult.token` is a nullable `String`) to a caller without one, and `dissolveAccount` returns no token at all. `dissolveAccount` needs a step-up as well, which only a session can hold (see below), so a user API key cannot dissolve an account. A user JWT without a `session_id` is not a session. The same session-only gate covers `createUserApiKey`, `rotateUserApiKey`, `createDeveloperApiKey`, `authorizeChannel` and `authorizeBot`. Provider linking has no GraphQL twin (REST `POST /v1/auth/link`, session-only). See [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces).

**`dissolveAccount` step-up (ZAF-2052):** after the `account:delete`, owner and `confirmName` checks, the calling session needs a step-up in the last 10 minutes; otherwise the error carries `extensions.code` `STEP_UP_REQUIRED` ("Please confirm that it's you first") and nothing is deleted. A user API key, service key or popout token cannot hold a step-up and is refused even with `account:delete`. Same code and message as `DELETE /v1/accounts/{id}`. See [Authentication → Step-up before sign-in changes](../features/auth.md#step-up-before-sign-in-changes).

`dissolveAccount` also refuses with `ACTIVE_SUBSCRIPTION` (a running Stripe subscription not set to cancel at period end) before the step-up.

**Scheduled dissolution (ZAF-2116):** `scheduleAccountDissolution(accountId: UUID!, graceDays: Int): AccountDissolution!` is guarded by `PermissionGuard("account:delete")`. `graceDays` is 0, 7 or 30 (default 30). The checks run in the same order and with the same codes as `POST /v1/accounts/{id}/dissolution`: first-party user (popout tokens refused, `FORBIDDEN`), `INVALID_GRACE`, `accountId` must be the active account (`FORBIDDEN`), owner only ("Only the account owner can dissolve an account"), `DISSOLUTION_ALREADY_SCHEDULED`, `ACTIVE_SUBSCRIPTION` ("Cancel it in the billing settings first"), then a fresh step-up (`STEP_UP_REQUIRED`; a user API key cannot hold one). `AccountDissolution { dissolutionScheduledFor, dissolved }`: `graceDays: 0` dissolves at once and returns `dissolutionScheduledFor: null, dissolved: true`.

`cancelAccountDissolution(accountId: UUID!): AccountDissolution!` (`AuthGuard`) is owner only and needs an interactive session (no API key, no popout token) but no step-up. It fails with `PROFILE_DELETION_SCHEDULED` while the owner's own profile is scheduled for deletion, with `DISSOLUTION_IN_PROGRESS` ("The dissolution is already running") once the date has passed, and with `NO_DISSOLUTION_SCHEDULED` when nothing is scheduled. It works while the channel is suspended, up to the end of the grace period. REST twin: `DELETE /v1/accounts/{id}/dissolution`.

**Channel name and picture (ZAF-2118):** a channel's name and picture come from one source - `connection` (one of the channel's own Twitch, YouTube or Kick channel connections, never Spotify) or `own` (an editable name and an optional uploaded picture; without one `avatarUrl` is `null` and the initial is shown). New channels start with `own`. Background: [Accounts › Channel name and picture](../features/accounts.md#channel-name-and-picture).

```graphql
type AccountIdentity {
  sourceKind: String!          # "connection" | "own"
  sourceConnectionId: UUID     # null with own
  sourcePlatform: String       # "twitch" | "youtube" | "kick"; null with own
  name: String!
  avatarUrl: String            # null = show the initial
}
```

- `Account.identity: AccountIdentity!` and `AccountMembership.identity: AccountIdentity!` (in `me.accounts[]`) carry the resolved name and picture. `AccountMembership.accountName` is the same name. `AccountMembership.ownerAvatarUrl` is deprecated and equals `identity.avatarUrl` (no fallback to the owner's profile picture). REST twins: `AccountResponse.identity`, `accounts[].identity` on `GET /v1/users/me`.
- `setAccountIdentitySource(accountId: UUID!, kind: String!, connectionId: UUID): AccountIdentity!` - `kind` `connection` needs a `connectionId`, `own` must not have one; an unknown kind, a missing or superfluous id or a Spotify connection fail with `INVALID_SOURCE`; another channel's or an unknown connection with `Connection not found`. Switching to `own` keeps the current name and starts with the initial; switching back to a connection deletes an uploaded picture. REST twin: `PUT /v1/accounts/{id}/identity-source`.
- `updateAccountName(accountId: UUID!, name: String!): AccountIdentity!` - only with `own` (`SOURCE_NOT_OWN`). Trimmed, NFC-normalised, 2-50 characters, no control or invisible characters: `NAME_TOO_SHORT`, `NAME_TOO_LONG`, `NAME_INVALID_CHARACTERS`. REST twin: `PATCH /v1/accounts/{id}/name`.
- `removeAccountAvatar(accountId: UUID!): AccountIdentity!` - only with `own` (`SOURCE_NOT_OWN`); shows the initial and deletes the files. REST twin: `DELETE /v1/accounts/{id}/avatar`.
- **No GraphQL upload.** The picture upload is REST-only: [`POST /v1/accounts/{id}/avatar`](./rest-api.md#post-v1accountsidavatar).
- `updateAccount(id: UUID!, name: String!): Account!` is deprecated and follows exactly the `updateAccountName` rules (own only, 2-50 characters, interactive session, audited).

Guard for all of them: `PermissionGuard("account:edit")` (owner and administrator by default), an interactive sign-in session (a user API key or popout token is refused with `FORBIDDEN` `This action requires an interactive sign-in session`), and `accountId` must be the session's active channel (`FORBIDDEN` `Account id does not match the active account`). During a dissolution grace period they fail with `CHANNEL_DISSOLVING`. Same guard, validation and codes as the REST twins. An effective change writes `account:identity_changed` (scope `account`) with metadata `changed` (`source` / `name` / `avatar`), `source_kind` and `source_platform`; never a name or URL.

While a dissolution is scheduled the channel is suspended: a member's session keeps its identity but holds no account permission, so permission-gated resolvers fail with `extensions.code = "CHANNEL_DISSOLVING"` and `extensions.dissolutionScheduledFor`. Channel-bound credentials (API keys, service keys, popout, overlay, widget and extension tokens) are refused outright; `createCheckout` fails with `CHANNEL_DISSOLVING`; every feature flag resolves off; the channel drops out of `botChannels` and `discordBotGuilds`. `me`, profile operations, switching or leaving accounts and `cancelAccountDissolution` keep working. Details: [REST API → Channels being dissolved](./rest-api.md#channels-being-dissolved).

> **First-party session required - extension developer surface (ZAF-471):** the developer-identity surface includes `myDeveloperProfile`, `developerRevenue`, `developerPayoutSettings`, `developerPayouts`, `developerLimits`, `developerLimitRequests`, `developerLimitRequestEvents`, `developerExtensions` and the ownership-scoped `developerExtension*` reads, `updateDeveloperPayoutSettings`, `requestPayout`, `requestDeveloperLimitIncrease`, `createExtension` / `submitExtensionVersion` / `requestExtensionDeletion` / `inviteExtensionTester` and their ownership-scoped siblings, the `developerTeam*` reads and `DeveloperTeamMutation` operations, and `grantExtensionAccess` / `createExtensionAccessInvite`. A popout token's `user_id` is the user it is bound to - possibly the owner - not the person presenting it, so the first-party and ownership checks keep a permission-capped popout from acting as that developer. First-party operations admit a logged-in user session or the user's own API key; `updateDeveloperPayoutSettings` and `requestPayout` instead require an interactive session (ZAF-1750). Ownership-scoped extension operations can also admit developer keys under their separate guard, as described below. A popout/overlay/widget/extension token is rejected with `FORBIDDEN` on both protocols; this includes the extension **secrets** resolvers, which are ownership-scoped (secrets belong to the extension, not to an account).

> **What happens to a requested payout (ZAF-1257):** the payout is `pending` and the balance is debited. The payout cycle sends Stripe and PayPal payouts within about 15 minutes; SEPA payouts and payouts with an unknown provider answer are settled by an operator (`completeDeveloperPayout` / `failDeveloperPayout`). Every request emits `developer:payout_requested` (user scope), as on REST. See [Developer Payouts](../features/developer-payouts.md).

> **Payouts need a verified developer (ZAF-2804):** `requestPayout` fails with `DEVELOPER_VERIFICATION_REQUIRED` ("Payouts require a verified developer identity. Complete the verification in the developer settings first") until the developer verification is `verified`; the automatic payout cycle skips unverified developers. REST twin: `POST /v1/developer/payouts/request`, `403` with the same code and text.

> **Closing payout (ZAF-2825):** `requestPayout(closing: true)` pays out the whole balance even below the method's minimum payout amount, but only while the user has a profile deletion scheduled (grace period running, or held by the deletion job); otherwise it fails with `CLOSING_PAYOUT_REQUIRES_DELETION` ("A closing payout below the minimum payout amount is only possible while a profile deletion is scheduled"). A balance of 0 still fails with the below-minimum error. Payout method, verified identity and the interactive session stay required. REST twin: `POST /v1/developer/payouts/request` `{ "closing": true }`, `409` with the same code and text.

> **Every payout carries a self-billed credit note (ZAF-2807):** `requestPayout` issues the payout's credit note in the same transaction; the payout `amount` is its gross amount (19 % VAT on top for a German developer who charges VAT). It fails with `TAX_DETAILS_REQUIRED` while the verification's tax details are incomplete and with `CREDIT_NOTE_ISSUER_NOT_CONFIGURED` while `[billing.issuer]` is incomplete, with the same texts as REST; nothing is booked. See [Developer Credit Notes](#developer-credit-notes).

> **Money-moving mutations are session-only (ZAF-1750):** `updateDeveloperPayoutSettings`, `requestPayout`, `createCheckout`, `createPortal` and `cancelSubscription` require an **interactive sign-in session**. A user's own API key is refused with `FORBIDDEN` `This action requires an interactive sign-in session`, whatever its scopes, before any row is written or Stripe is called (the billing mutations check the session before they check whether billing is enabled). The reads (`developerPayoutSettings`, `developerPayouts`, `developerRevenue`, `billingStatus`, `invoices`) keep the first-party gate. Stripe Connect onboarding has no GraphQL twin (REST `POST /v1/developer/stripe-connect/onboard`, session-only). REST twins identical. See [Authentication → Session-only Surfaces](./authentication.md#session-only-surfaces).

> **Developer API keys (`lm_dev_`, ZAF-1176):** a developer key is **not** a first-party user session, so it is refused from the developer-application surface above (profile / revenue / payouts / limits, and `createExtension` / `submitExtensionVersion` / `requestExtensionDeletion` / `inviteExtensionTester`) with the same `FORBIDDEN`. It **is** admitted - where a popout is rejected - to the ownership-scoped `developerExtension*` reads and their mutations (update / delete extension, create / upload version, testers list & remove, analytics, limits, purchases, screenshots, and the extension **secrets** `developerExtensionSecrets` / `setExtensionSecret` / `deleteExtensionSecret` - see [REST → Extension secrets](./rest-api.md#extension-secrets) for the shared rules): those resolve the key's bound developer/team identity via the shared `resolve_ownership` helper and are gated on the key's `extension-dev:*` scope, decoupled from the `feature:extension_development` plan gate.

> **Note:** This mutation supersedes the previous provider-based disconnect operation. The old form accepted a `provider` string; the new form accepts a `loginConnectionId` UUID to uniquely identify the connection even when a user has multiple connections to the same platform.

### Types

#### `GqlLoginAssignment`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Assignment ID |
| `accountId` | `UUID!` | Account the login is assigned to |
| `userId` | `UUID!` | ID of the owning user |
| `loginConnectionId` | `UUID!` | ID of the linked login connection |
| `provider` | `String!` | Platform slug (e.g. `"twitch"`, `"google"`) |
| `createdAt` | `String!` | ISO-8601 timestamp |

> **Protocol parity:** All operations above have matching REST endpoints - see [REST API](./rest-api.md#login-assignments).

## Discord Servers

The global Lumio Discord bot serves the Discord servers connected to an account (one server belongs to one account, an account can have several).

- **Connect / reconnect:** `authorizeBot(platform: "discord")` (`feature:bots` + `bot-connections:create`, session-only) returns the Discord invite URL: scopes `bot applications.commands identify`, `integration_type=0`, targeted permissions (never Administrator), `redirect_uri` = the unified callback `/api/connections/oauth/discord/callback`. The exchange runs on REST `POST /v1/connections/oauth/discord/exchange` only (browser callback): the server is taken from Discord's token response, never from the callback query. Inviting a server the account already has reconnects it and keeps its settings. Without `[auth].discord_bot_client_id` / `discord_bot_client_secret` the call fails with `The Discord bot is not fully configured: …` on both protocols. `feature:custom_bot` does not apply to Discord.
- **`discordGuildConnections`** (`bot-connections:read`) - `DiscordGuildConnection { id, guildId, guildName, guildIcon, permissions, createdAt, updatedAt, botRemoved, missingPermissions }`. `botRemoved`: the bot was removed from the server on Discord's side; the row and its settings stay until a reconnect (or are deleted 90 days later). `missingPermissions`: the server granted fewer permissions than the bot needs. REST twin: `GET /v1/discord-guilds`.
- **`disconnectDiscordGuild(guildId)`** (`bot-connections:delete`) - deletes the connection and its settings, returns `{ success }`. REST twin: `DELETE /v1/discord-guilds/{guild_id}`.

Errors of the connect step: `This Discord server is already connected to another account.` (the bot is still on that server; a server whose bot was removed can be taken over, with its settings reset), `Discord did not confirm the server invitation. Please add the bot again.`, `Discord did not report which server the bot was added to. Please add the bot again.`

## Notifications

User-scoped notifications with read/unread tracking and actionable items. See [Notifications](../features/notifications.md) for the full feature documentation, queries, and mutations.

The `invite` notification carries `data.inviteId` (the account invite row ID) and offers `accept_invite` and `decline_invite`. A `developer_team_invite` carries `data.invite_id` (the team invite row ID, never its secret code) and offers `accept_team_invite` and `decline_team_invite`. `executeNotificationAction(id: UUID!, action: String!): Notification!` dispatches these four actions for the owning first-party user and marks the notification acted. Team acceptance uses the same feature, expiry, use-limit and membership checks as `acceptDeveloperTeamInvite` by code; team decline deletes only an unused single-use invite and treats a missing invite as handled.

Actions with a `url` are navigation actions, including `view_idea`, `view_developer_application`, `view_developer`, `view_extension`, and `install_extension`. The bell opens their page; passing one to `executeNotificationAction` yields `NOTIFICATION_ACTION_NAVIGATES`. Errors use the same message as the [REST action endpoint](./rest-api.md#notifications), with its stable code in `extensions.code`: `NOTIFICATION_NOT_FOUND`, `NOTIFICATION_NO_ACTIONS`, `NOTIFICATION_ACTION_NOT_AVAILABLE`, `NOTIFICATION_ACTION_NAVIGATES`, `NOTIFICATION_ALREADY_HANDLED`, `NOTIFICATION_UNKNOWN_ACTION`, `INVALID_INVITE_ID`, `INVITE_NOT_FOUND`, `INVITE_EXPIRED`, `INVITE_FULL`, `ALREADY_MEMBER`, `INVITE_NO_LONGER_VALID`, and `FEATURE_DISABLED`. An absent or foreign notification uses `NOTIFICATION_NOT_FOUND`.

### Notification preferences

| Operation | Args | Returns | Permission |
|-----------|------|---------|------------|
| `notificationPreferences` | - | `[NotificationPreference!]!` | Auth only |
| `updateNotificationPreference(notificationType: String!, channel: String!)` | - | `NotificationPreference!` | Auth only |

`channel` accepts `"off"`, `"in_app"`, `"email"`, or `"in_app_email"`. Updating a locked type (e.g. `invite`) returns an error.

### Idea participant autocomplete

| Query | Args | Returns | Permission |
|-------|------|---------|------------|
| `ideaParticipants(ideaId: UUID!, search: String)` | - | `[GqlIdeaAuthor!]!` | Signed-in user session or personal API key |

Returns the union of the idea author, voters, and commenters, filtered by the optional `search` string. Used to populate the @mention autocomplete dropdown in idea comments.

Anonymous callers receive `UNAUTHENTICATED`. Popout, overlay, widget, extension, shared-overlay, service, developer, and system credentials receive `FORBIDDEN`. The REST participant endpoint applies the same first-party user check.

> **Protocol parity:** Both operations have matching REST endpoints - `GET /v1/notifications/preferences`, `PATCH /v1/notifications/preferences/{type}`, and `GET /v1/ideas/{id}/participants` - see [REST API](./rest-api.md).

## YouTube Member Badges

Account-scoped read query and a system-admin-scoped erasure mutation. See [Member Badges](../features/memberships.md) for the underlying architecture.

### Queries

#### `youtubeMembershipTiers: [GqlYoutubeMembershipTier!]!`

List YouTube member-tier badges observed for the caller's account, sorted by first-observation order. Returns `[]` when the cache has not been populated yet (e.g. before the first member message of the very first stream). Requires `chat:read`.

Fields on `GqlYoutubeMembershipTier`: `tooltip` (raw English InnerTube tooltip - uniquely identifies the badge artwork at this loyalty milestone), `tierName`, `badgeUrl`, `durationValue`, `durationUnit` (`GqlDurationUnit`: `MONTH`/`MONTHS`/`YEAR`/`YEARS`), `memberMonthsMin`, `sortOrder`, `firstSeenAt`, `lastSeenAt`.

### Mutations

#### `eraseYoutubeMemberData(input: EraseYoutubeMemberDataInput!): GqlEraseYoutubeMemberResult!`

GDPR Art. 17 - erase one YouTube member channel on one channel's instruction. Input `EraseYoutubeMemberDataInput`: `memberChannelId`, `accountId` (the instructing channel), `instructionReference` (ticket or e-mail id, at most 200 characters) and `initiatedBy` (`channel` or `subject`, as for `eraseChatSubjectData`), all required. Two parts: Lumio's own member cache - all `lumio:yt:member:*:{memberChannelId}` rows and the matching `lumio:yt:refresh_lock:*:{memberChannelId}` debounce locks - is cleared across every account (Lumio's YouTube API client cache, not channel data); the member's channel data (`platform = 'youtube', user_id = memberChannelId`) is erased in `accountId` only, exactly as `eraseChatSubjectData` below. It does **not** touch the emote catalog (`chat_emotes`): an emote shortcode plus its public CDN URL is cross-channel branding reference data, not personal data of the erased member, and falls outside Art. 17 (founder ruling - ZAF-580). Audit-logged as exactly one `system`-scoped `youtube_member_erasure` row naming the target account and the instruction reference, never the member channel id (see [audit log](../admin/audit-log.md#youtube_member_erasure)). Requires `admin:privacy-erase`.

Result fields: `erasedKeyCount` and `erasure` (`ChatSubjectErasureResult`, below). Errors (same code and text as REST): `member_channel_id required`, `account_id is required`, `instruction_reference is required`, `instruction_reference must be at most 200 characters`, `initiated_by is required`, `initiated_by must be one of: channel, subject`, `Not found: Account not found`.

> **Protocol parity:** mirror at `GET /v1/youtube/memberships/tiers` and `DELETE /v1/admin/privacy/youtube/member/{id}` - see [REST API](./rest-api.md#endpoints-overview).

#### `eraseChatSubjectData(input: EraseChatSubjectInput!): ChatSubjectErasureResult!`

GDPR Art. 17 - erase one data subject's chat data **in one channel**, on that channel's instruction. Channel data belongs to the channel (founder ruling ZAF-2626), so there is no cross-account erasure: other channels keep the same person's data. In the instructing account it hard-deletes the subject's `platform_chat_messages` rows, their `platform_users` row, the moderator notes about them, their AutoMod history log (`platform_automod_messages` and its `automod_allow` / `automod_deny` moderation-log rows), every other moderation-log row targeting them (rows where they are the acting moderator stay) and their `account_bots` entry, blanks their entries in the account's frozen stream-history lists, announcements and pins included (counts stay, `erased: true`), and closes their still-open messages in the channel's live AutoMod held queue. Events (`platform_event_logs`) stay. It also records the subject in the account's suppression list (`account_chatter_suppressions`), so the channel's later sessions freeze them blanked. Audit-logged as exactly one `system`-scoped `chat_pii_erasure` row (see [audit log](../admin/audit-log.md#chat_pii_erasure)). Requires `admin:privacy-erase`.

Input `EraseChatSubjectInput`: `accountId` (the instructing channel), `instructionReference` (ticket or e-mail id, trimmed, at most 200 characters), `reason` (why the subject is erased, trimmed, at most 500 characters, written to the audit event) and `initiatedBy` (`channel` when the channel initiated the erasure, `subject` when the person asked for it; stored on the channel's suppression entry, only a `channel` entry can later be withdrawn, and a `subject` entry is never downgraded) are required; the subject is **exactly one** of `lumioUserId` (a registered Lumio user), or both `platform` + `userId` (a platform chatter such as a YouTube `UC…` channel id). Errors (same code and text as REST): `provide either lumio_user_id or (platform and user_id)`, `platform and user_id must be provided together`, `provide exactly one of lumio_user_id or (platform and user_id), not both`, `account_id is required`, `instruction_reference is required`, `instruction_reference must be at most 200 characters`, `reason is required`, `reason must be at most 500 characters`, `initiated_by is required`, `initiated_by must be one of: channel, subject`; an unknown account is `Not found: Account not found`. Only support operators (`admin:privacy-erase`) call it.

Result fields (`ChatSubjectErasureResult`): `accountId`, `caseId` (Lumio's id of this erasure, also in the audit event; its first 8 characters are the case number in the owner's confirmation e-mail), `deletedMessageCount`, `deletedPlatformUserCount`, `deletedUserNoteCount`, `deletedAutomodMessageCount`, `deletedAutomodModerationLogCount`, `deletedModerationLogCount`, `scrubbedHistorySessionCount`, `deletedAccountBotCount`, `removedHeldQueueEntryCount` (the subject's still-open messages closed in the channel's live AutoMod held queue; best-effort, 0 when Redis is unreachable), `suppressed`.

> **Protocol parity:** mirror at `POST /v1/admin/privacy/chat/erase` - see [REST API](./rest-api.md#endpoints-overview). Account deletion (dissolution and `adminDeleteAccount`) erases the account's chat, events, chatter profiles, notes and moderation log automatically.

#### `withdrawChannelChatterSuppression(input: WithdrawChannelChatterSuppressionInput!): ChannelSuppressionWithdrawalResult!`

Withdraw one channel's erasure instruction for one chatter: deletes the chatter's row in that account's suppression list (`account_chatter_suppressions`), so the channel's stream reports frozen from then on name the chatter again. What the erasure deleted or blanked stays gone - nothing is restored. Other channels' lists and the global Lumio list (`chatter_suppressions`, Lumio Stats) are not touched. Input `WithdrawChannelChatterSuppressionInput`: `accountId`, `platform` (`twitch`, `youtube` or `kick`), `userId` and `instructionReference` (ticket or e-mail id of the withdrawal) are all required. Only an erasure the channel initiated can be withdrawn: an entry the person asked for (`initiatedBy: subject`, and every entry recorded before the initiator was stored) is refused with `CONFLICT` and stays. Errors (same code and text as REST): the `addChatterObjection` validation texts, `account_id is required`, `instruction_reference is required`, `instruction_reference must be at most 200 characters`, `Not found: Account not found`, `Not found: no channel erasure is recorded for this chatter` and `Conflict: this erasure was requested by the person, not initiated by the channel; it cannot be withdrawn on the channel's instruction`. Result fields (`ChannelSuppressionWithdrawalResult`): `accountId`, `platform`, `suppressed` (always `false`). Requires `admin:privacy-erase-withdraw`. Audit-logged on success as one `system`-scoped `privacy:channel_suppression_withdrawn` row (metadata: account, instruction reference and platform, never the user id or login).

> **Protocol parity:** mirror at `POST /v1/admin/privacy/chat/erase/withdraw` - same validation, error codes and texts, guard and audit event.

#### `eraseChatSubjectAtLumio(input: EraseChatSubjectAtLumioInput!): LumioErasureResult!`

Erase one person on Lumio's own surfaces only (ZAF-2640 R2): an `erasure` entry in the global Lumio list (`chatter_suppressions`), which masks them on the public Lumio Stats leaderboard, and on YouTube Lumio's member cache across every account. No channel's chat, profiles, logs or stream reports are touched - those are erased only on the channel's instruction (`eraseChatSubjectData`). Idempotent; an existing objection becomes an erasure entry. Input `EraseChatSubjectAtLumioInput`: `platform` (`twitch`, `youtube` or `kick`), `userId`, `instructionReference` and `reason` (trimmed, at most 500 characters, written to the audit event) required, `login` optional (Twitch and Kick). Errors as `addChatterObjection` plus `instruction_reference is required` / `instruction_reference must be at most 200 characters` / `reason is required` / `reason must be at most 500 characters`. Only support operators call it. Result fields: `platform`, `suppressed`, `erasedKeyCount`. Requires `admin:privacy-erase`. Audit-logged as one `system`-scoped `chat_pii_erasure` row with `target: "lumio"`, never the user id or login.

> **Protocol parity:** mirror at `POST /v1/admin/privacy/lumio/erase` - same validation, error texts, guard and audit event.

#### `eraseChatRecord(input: EraseChatRecordInput!): ChatRecordErasureResult!`

Erase **one record** in one channel on that channel's instruction (ZAF-2640 R11 target i). The record is looked up by its id **and** `accountId`: a record of another account is `Not found: Record not found`, the same answer as for one that does not exist. No suppression entry is written, and Lumio Stats is not touched. Requires `admin:privacy-erase`. Audit-logged as one `system`-scoped `chat_pii_erasure` row with `target: "record"` per erased record (see [audit log](../admin/audit-log.md#chat_pii_erasure)); a record that is not found writes none.

Input `EraseChatRecordInput`: `kind`, `accountId`, `instructionReference` (at most 200 characters) and `reason` (at most 500 characters) are always required. By `kind`:

| `kind` | Fields | Removes |
|---|---|---|
| `chat_message` | `recordId`, `createdAt` (matched within ±1 s) | the message (hard delete) and its text copy in the moderation log (`details.message`; the moderation-log row stays) |
| `user_note` | `recordId` | the moderator note |
| `moderation_log` | `recordId` | the moderation-log entry, with any message text in it |
| `automod_log` | `recordId` | the AutoMod-log entry, its `automod_allow` / `automod_deny` moderation-log rows, and a still-open entry of the live held queue |
| `bot_list` | `recordId` | the bot-list entry |
| `stream_report` | `sessionId`, `platform`, `userId`, optional `login` (Twitch/Kick) | the person's entries in that report's top chatters, links, commands and keywords, and their slots in its announcements (author, deleter) and pins (sender, pinner): place and counts stay, the identity goes ("Deleted user"); an announcement or pin they wrote also loses its message id. The report must be finalized (else `Conflict: the stream report is not finalized yet; erase the person once it is`) |

A chat message's text can also sit in its stream report (a command's arguments, a posted link). `chat_message` does not reach the report; erase the person in that report with `stream_report` as well. Later recounts from the chat log (a keyword-list change, a bot-list change) leave a report with erased entries as it is, so the name does not come back.

Errors (same text as REST): `kind must be one of: chat_message, user_note, moderation_log, automod_log, bot_list, stream_report`, `account_id is required`, `instruction_reference is required`, `instruction_reference must be at most 200 characters`, `reason is required`, `reason must be at most 500 characters`, `record_id is required`, `created_at is required for a chat_message`, `session_id is required for a stream_report`, the chatter errors of `addChatterObjection`, `Not found: Account not found`, `Not found: Record not found`.

Result fields (`ChatRecordErasureResult`): `accountId`, `caseId` (also in the audit event), `kind`, `deletedRecordCount` (1, or 0 for `stream_report`), `moderationLogTextRemovedCount` (`chat_message`), `deletedModerationLogCount` and `heldQueueEntryRemoved` (`automod_log`), `scrubbedEntryCount` (`stream_report`; 0 when the person was not in the report).

> **Protocol parity:** mirror at `POST /v1/admin/privacy/records/erase` - same validation, error texts, guard, result fields and audit event.

#### `addChatterObjection(input: ChatterObjectionInput!): GqlChatterObjectionResult!`

GDPR Art. 21 - record a chatter's objection in the global Lumio list (`chatter_suppressions`). It acts on Lumio Stats only: the public Stats leaderboard (`publicStreamStats.topChatters`) is masked at read time, so the objection also covers streams published earlier. Nothing is erased, and no channel's stream reports, exports, history share links or AutoMod log change. Idempotent. Requires `admin:privacy-objection-create`. Audit-logged as `privacy:chatter_objection_added` (`system` scope, metadata without the user id or login).

Input `ChatterObjectionInput`: `platform` (`twitch`, `youtube` or `kick`) and `userId` are required; `login` (Twitch and Kick only) also covers the chatter's entries without a user id. Result fields: `platform`, `suppressed`, `reason` (`objection`, or `erasure` when the chatter's global entry is an erasure entry).

#### `removeChatterObjection(input: ChatterObjectionInput!): GqlChatterObjectionResult!`

Lift a chatter's objection: the public Stats leaderboard names the chatter again at once (it was only masked on read). `login` is ignored. Errors when no objection is recorded, or when the global entry is an erasure entry (it cannot be lifted). Requires `admin:privacy-objection-delete`. Audit-logged as `privacy:chatter_objection_removed`.

> **Protocol parity:** mirrors `POST /v1/admin/privacy/chat/objections` and `DELETE /v1/admin/privacy/chat/objections/{platform}/{user_id}` - same validation, error texts, guard type and audit event - see [REST API](./rest-api.md#endpoints-overview).

#### `adminSweepOrphanedExtensionUploads(apply: Boolean! = false): OrphanSweepReport!`

One-off repair for extension upload files that no `extension_uploads` row references any more - left behind by uninstalls and extension deletes before those queued their files (see [Uploads](../features/uploads.md#extension-uploads-deletion-with-the-install-or-the-extension)). Lists `extensions/{extension_id}/uploads/` for every existing extension and counts the unreferenced files. `apply: false` (the default) is a dry run that changes nothing; `apply: true` queues the files in `storage_deletion_queue` (reason `orphaned`) for the hourly delete, which re-checks each file under its per-file lock, and records a `system:orphaned_storage_swept` audit event. Requires `admin:privacy-erase`. Fails with `Storage not configured` when no storage backend is set up.

Result fields: `applied`, `extensionsScanned`, `extensionsFailed` (listing failed, skipped), `orphanedObjects`, `queuedObjects` (0 on a dry run).

> **Protocol parity:** mirror at `POST /v1/admin/storage/orphaned-extension-uploads/sweep` - see [REST API](./rest-api.md#endpoints-overview).

## Emote catalog and hover-card details

`emotes(platform, channelId)` and `userEmotes` return emote sets for the chat picker. An `Emote` has `id`, `name`, `url`, `provider`, `animated`, nullable `ownerId`, `subscribersOnly`, nullable `ownerName`, and nullable `scope`. `ownerName` is a creator display name when 7TV, FFZ, or BTTV supplies one; `scope` is `channel` or `global` for a third-party set, and `null` when unknown or for native sets. The `emotes` and `userEmotes` queries require `feature:multichat` and `chat:read`. Their REST counterparts and guard differences are described under [Emotes](./rest-api.md#emotes).

### `emoteInfo`

```graphql
query EmoteInfo($platform: String!, $items: [GqlEmoteInfoItemInput!]!) {
  emoteInfo(platform: $platform, items: $items) {
    emoteId
    animated
    owner { ownerId login displayName avatarUrl }
  }
}
```

`platform` is `twitch`, `youtube`, or `kick`. Each input item requires `emoteId`; `ownerId` and `url` are optional. At most 50 items are accepted, and results follow input order. An empty list returns `[]`. An empty or over-200-character emote ID, an owner ID over 200 characters, or a URL over 2048 characters is a validation error; unsupported platforms and more than 50 items are also validation errors. GraphQL and REST use the same resolver and validation messages.

`owner` is `null` when it cannot be resolved. When present, it contains the platform owner ID, nullable login, display name, and nullable avatar URL. Twitch uses a fragment owner ID (`0` denotes a global emote); YouTube can derive the `UC…` channel ID from an emote ID; Kick accepts its namespaced `kick:<id>` owner ID. Owner lookup uses the active account's platform profile service. Without an account context, owner details are `null`.

`animated` is nullable. It is always `null` for Twitch; Kick and YouTube use a server-side image probe. Kick's URL is built from its numeric emote ID and ignores the supplied `url`. YouTube requires an HTTPS image URL on `yt3.ggpht.com`; without it, the result is `null`. The probe reads at most 512 KiB within 2 seconds, follows at most three same-origin redirects, and returns `null` when it cannot decide. A decided result is cached for 30 days; an undecidable probe is cached for one hour.

One request resolves at most 10 distinct owners and probes at most 10 images; items beyond those caps return `owner: null` / `animated: null`. Probe results are cached by the fetched image URL (hashed), not by the client's emote id.

**Guard:** authentication, no `chat:read` or feature gate. Dashboard sessions, API / service / developer keys, popout tokens and System keys are allowed; overlay, shared overlay, widget and extension tokens get `FORBIDDEN` `Emote details are not available to overlay, widget or extension tokens`. The REST twin is [`GET /v1/emotes/info`](./rest-api.md#get-v1emotesinfo). Twitch badge JSON on chat messages can carry `image_url_hd`, the Helix 4x image, alongside `image_url` when available; badges written without it still render with the ordinary image.

## Twitch Shared Chat session

`sharedChatSession: SharedChatSessionView!` reads the account's current Twitch
session with `chat:read` and `feature:multichat`; popout tokens with those
grants can read it. `status` has three cases: `SESSION` (the own channel is in
a session), `NONE` (no session), and `UNKNOWN` (Redis or Helix could not
determine it). An `UNKNOWN` read must not clear the client's last known state.
`revision` is strictly increasing and null only for `UNKNOWN`. The view also
contains `sessionId`, `hostBroadcasterId`, `ownBroadcasterId`, `startedAt`,
`updatedAt`, `participants` and `totalViewers`. A participant carries its
broadcaster ID, name, avatar, join time, optional viewers/category/title/
followers, and `inferred`, `isHost`, `isOwnChannel`. The total adds the last
known channel counts; it can count one multi-channel viewer several times.
REST twin: [`GET /v1/chat/shared-chat`](./rest-api.md#get-v1chatshared-chat).

## Chat Moderation

### Announcements and current pins

`ChatMessage.messageType` is `announcement` for an own or Shared Chat Twitch
announcement. `ChatMessage.announcementColor` is `primary`, `blue`, `green`,
`orange` or `purple` for those rows and `null` for ordinary messages. A missing
or unrecognised Twitch colour becomes `primary`. The field persists through
`chatHistory` and `mergedChatHistory`; the REST twin is `announcement_color`.

`chatPins: ChatPins!` reads the active account's current `twitch` and `kick`
pins with `chat:read` and `feature:multichat`, including from a popout token.
`available: false` means the state could not be read, so two `null` pins do
not establish that nothing is pinned. A `ChatPin` has `platform`, `channelId`,
`messageId`, `sender`, `pinnedBy`, `text`, `emotes`, `sentAt`, `startsAt`,
`endsAt` and `updatedAt`. `sentAt` is when the sender wrote the message, or
`null` when unknown; it is not the pin time. `endsAt: null` means until stream
end. Each person has `platform`, `userId`, `login`, `displayName`, `avatarUrl`,
`color` and `badges`.

| Mutation | Permission | Effect |
|----------|------------|--------|
| `pinChatMessage(platform, messageId, durationSeconds)` | `chat:pin` + `feature:multichat` | Pin an ordinary Twitch message, replacing the current pin. |
| `updateChatPin(platform, messageId, durationSeconds)` | `chat:pin` + `feature:multichat` | Change the current Twitch pin's duration, counted from now. |
| `unpinChatMessage(platform, messageId)` | `chat:pin` + `feature:multichat` | Remove the current Twitch pin. |

`durationSeconds` is 30–1,800 or `null` for until stream end. The acting
member's Twitch login needs moderation rights and
`moderator:manage:chat_messages`; Kick actions return `success: false` with
`errorCode: "pin_platform_unsupported"`. A `ChatPinActionResult` carries
`success`, `platform`, `messageId`, `action`, `errorCode` and `details`.
GraphQL and REST use the same validation, guard and result service.

Account-scoped moderation across the supported chat platforms. Queries for chat history / user info live in the chat module - see [Chat](../features/chat.md) for the full surface, including `chatHistory`'s keyword `search` filter (`ChatFilterInput.search`, mirrored by the REST `search` query parameter), its bounded paging (`chatHistory` and `events` read the 30 days before `to`/now unless `from` is given; `total` is capped at 10 000 with `totalCapped: true` meaning more match, and is counted only when `total`/`totalCapped`/`pages` is selected — [Chat → Bounded list reads](../features/chat.md#bounded-list-reads)) and `mergedChatHistory` — the server-merged messages+events+AutoMod timeline paged by a single keyset cursor (mirrored by the REST `GET /v1/chat/history/merged`; one request reads at most 30 days below its cursor, so a page can be short or empty with `hasMore: true` — page until `hasMore` is `false`), which independently gates each stream (`chat:read` for messages, `events:read` for events, `feature:multichat` + `chat:read` + `chat:automod-read` for Twitch AutoMod holds — the account's full chat window with `history:read`, else the last 24 hours; popout tokens are scoped like a member, other token kinds and anonymous callers get none; skipped for a non-Twitch `platform` and for a `liveChatId`). `ChatHistoryItemKind` is `MESSAGE`, `EVENT` or `AUTOMOD`; an `AUTOMOD` item carries `ChatHistoryItem.automod: AutomodLogEntry` (the `automodLog` entry type), its `id` is the log row id and its `createdAt` is `heldAt`. A reply on a `ChatMessage` carries the parent author as both `replyParentUsername` (display name) and `replyParentLogin` (login/handle twin, ZAF-1452 F1; `null` where the platform has no distinct login) - the REST twin is `reply_parent_login` and the field is also on the `chat:message` WebSocket payload. `ChatMessage.messageType` is `channel_points_custom_reward` for a Twitch message sent through a channel-points reward with text input ([Chat → Channel-points messages](../features/chat.md#channel-points-messages)). `Event.raw` is returned as stored, including the Twitch Shared Chat partner-event fields `is_shared_chat`, `source_channel` and `shared_chat_notice_type` ([Events → Twitch Shared Chat partner events](../features/events.md#twitch-shared-chat-partner-events)).

### Twitch AutoMod held messages

`heldChatMessages: HeldMessageList!` reads the active channel's holds, oldest first. It requires `chat:automod-read` and `feature:multichat`. `messages` contains `platform`, `messageId`, `sender` (optional `avatarUrl`, `color` and `badges`: the look at hold time from Lumio's chatter record, absent for a chatter Lumio has not seen), `text`, optional `fragments`, optional `emotes` (Twitch emotes and cheermotes in the `ChatMessage.emotes` shape; absent when none or the fragments were dropped for size), `reasonKind`, `reason`, `flaggedSpans`, `heldAt` and optional `expiresAt`. `reasonKind` is `automod`, `blocked_term` or `blocked_link`; each span uses Unicode code-point offsets with an inclusive `end`. `queueAvailable: false` means the Redis queue could not be read, so an empty `messages` array does not establish that no holds exist. Twitch currently supplies no expiry deadline; clients show elapsed waiting time.

`allowHeldChatMessage(messageId: String!): HeldMessageDecisionResult!` needs `chat:automod-allow`; `denyHeldChatMessage(messageId: String!): HeldMessageDecisionResult!` needs `chat:automod-deny`. Both also need `feature:multichat` and act through the caller's own Twitch login as a channel moderator. The result has `success`, `messageId`, `decision`, `errorCode` and `details`. A refused decision returns `success: false`, for example `already_handled_or_expired`, `automod_queue_unavailable` or `login_scope_missing` (the caller's stored Twitch login scopes are known and lack `moderator:manage:automod`, checked without a Helix call; an empty stored set is unknown and Helix decides; a Helix `401` maps to the same code); the same codes and messages appear in REST. An allowed message is later published with a new ID. Popout tokens can carry the three live AutoMod permissions. The session history log has a separate `history:read` gate and refuses popout tokens. REST twins: `GET /v1/chat/automod/held` and `POST /v1/chat/automod/held/{message_id}/allow|deny`.

### `moderateChat(input: ModerationInput!): GqlModerationResult!`

Perform a moderation action on `twitch`, `youtube`, or `kick`. Requires the `feature:multichat` flag (same gate as the REST twin `POST /v1/chat/moderate` and the live `chat:{account_id}` WebSocket stream). Permission depends on the action: `chat:ban` for `BAN`, `chat:timeout` for `TIMEOUT`, `chat:delete` for `DELETE`.

The action runs on the **acting moderator's login token** for the platform (Twitch login, Google login, Kick login). The token is refreshed on demand before the call. Both protocols share one implementation (`services::chat_moderation`), so they return the same results and errors.

Two kinds of failure:

- **Request errors** (GraphQL error with a `code` extension, REST HTTP status): validation (`VALIDATION_ERROR`), an unsupported platform, a non-numeric Kick `userId`, a Kick timeout above 7 days, a missing login or channel connection (`BAD_REQUEST`).
- **Refused actions** (`result.success = false`): `result.details` carries a readable message and `result.errorCode` a stable code that the frontend translates:

| `errorCode` | Meaning |
|-------------|---------|
| `login_scope_missing` | The moderator's login grant lacks the provider scope for this action, checked before the call for Kick (and for Twitch AutoMod Allow/Deny, `moderator:manage:automod`), or the provider answered `401`. Fix: log in with that platform again. |
| `login_reconnect_required` | The login grant is dead (revoked, undecryptable, or expired with no refresh token). It is flagged `reconnect_required`. |
| `moderation_forbidden` | Kick answered `403`: the account has no moderation rights in this channel. |
| `moderation_failed` | Any other provider error. `details` carries the provider message. |
| `internal_error` | The login credential could not be read. The cause is logged, not returned. |

`ModerationInput` fields:

- `action: ModerationActionGql!` - `BAN`, `TIMEOUT`, or `DELETE`
- `platform: String!` - `"twitch"`, `"youtube"`, or `"kick"`
- `userId: String` - platform user ID (required for `BAN` / `TIMEOUT`)
- `messageId: String` - required for `DELETE`
- `durationSecs: Int` - timeout length in seconds, **required for `TIMEOUT`** (validation rejects a `TIMEOUT` without it, identically on REST; YouTube accepts `1`–`86400`)
- `reason: String` - optional moderator reason (logged to `moderation_log`)
- `liveChatId: String` - only used by YouTube. Optional: when omitted the server resolves the active broadcast's `liveChatId` from the polling worker's Redis cache (`lumio:youtube:active_streams:{account_id}`). Pass it explicitly when the broadcaster runs multiple concurrent broadcasts and you want to target a specific one.

Per-platform behaviour:

| Platform | Supported actions | Notes |
|----------|-------------------|-------|
| `twitch` | `BAN`, `TIMEOUT`, `DELETE` | Calls Helix; needs `moderator:manage:banned_users` / `moderator:manage:chat_messages` scope on the moderator's login token |
| `youtube` | `BAN`, `TIMEOUT`, `DELETE` | `BAN`/`TIMEOUT` use `liveChatBans.insert` (`type=permanent` vs `type=temporary` + `banDurationSeconds`); `DELETE` uses `liveChatMessages.delete`. Returns 403 if the target is the broadcaster or another moderator - Lumios UI hides the buttons for those targets to surface the limitation as missing UI rather than a failed request. |
| `kick` | `BAN`, `TIMEOUT`, `DELETE` | Official public API. `DELETE` → `DELETE /public/v1/chat/{message_id}` (login scope `moderation:chat_message:manage`); `BAN`/`TIMEOUT` → `POST /public/v1/moderation/bans` with `broadcaster_user_id` = the Kick channel connection's channel id (login scope `moderation:ban`). A timeout is sent in whole minutes, **rounded up** (90 s → 2 min, minimum 1). Anything above 10 080 min (7 days) is rejected, not clamped. `reason` is cut to 100 characters. `userId` must be the numeric Kick user id. The stored login scopes are checked before the call; a missing scope returns `errorCode = login_scope_missing` without calling Kick. |

After a successful `BAN` or `TIMEOUT` the server soft-deletes every message from the affected user and broadcasts a `chat:clear_user` event to the chat WebSocket channel - see the [WebSocket reference](./websocket.md#chat-sub-types) for the payload. Every successful action (including `DELETE`) also writes a moderation-log row and broadcasts the matching `chat:moderation_log` event with `duration_secs` / `ends_at`, the same payload the platform webhooks produce. For Kick the logged duration is the applied one (whole minutes). The Kick `moderation.banned` webhook that echoes a Lumio-issued ban/timeout within 60 s is deduplicated.

> **Protocol parity:** mirror at `POST /v1/chat/moderate` - see [REST API](./rest-api.md).

### `refreshPlatformUserProfile(platform: String!, platformUserId: String!): GqlUnifiedProfile!`

Force a fresh enrichment of a platform user's profile, bypassing the normal 24h/14-day staleness interval. Returns the same `GqlUnifiedProfile` type as the `platformUserProfile` query.

**Permission:** `chat:refresh_user`

**Rate limit:** One refresh per (account, platform, user) triple every 10 minutes. When the cooldown is active the mutation returns an error with extension `{ "code": "REFRESH_COOLDOWN", "retry_after_seconds": N }`.

Platforms: `"twitch"`, `"youtube"`, `"kick"`.

`GqlUnifiedProfile` enrichment fields (all nullable - `null` means the platform does not expose the value or it has not been fetched yet): `description`, `broadcasterType`, `isFollower`, `followedAt`, `accountCreatedAt`, `followerCount: Int` (the user's **own** follower count; filled on Twitch, best-effort on Kick and may be `null` there, `null` on YouTube), `enrichedAt`. See [Profile Service](../features/profile-service.md#multi-platform-enrichment) for what each platform fills.

> **Protocol parity:** mirror at `POST /v1/chat/users/{platform}/{platform_user_id}/refresh` - see [REST API](./rest-api.md#chat-moderation).

### `searchPlatformUsers(query: String!, platforms: [String!], limit: Int): [GqlPlatformUserSearchResult!]!`

Prefix-search the account's known chatters (the `platform_users` table) by `username` **or** `displayName` for the multichat filter name-completion. Same guard as `platformUserProfile` - `feature:multichat` + `chat:userinfo` - so it never surfaces a user the caller could not already inspect (and without `chat:userinfo` it returns nothing, so the search leaks no data).

- **`query`** - case-insensitive prefix. Shorter than 2 characters (after trimming) returns an **empty list, not an error** (the UI queries per keystroke). `%`, `_`, and `\` match literally.
- **`platforms`** - optional platform filter; omit for all platforms.
- **`limit`** - optional (default 10), **hard-capped at 25** regardless of the requested value.
- Ordered `lastSeenAt DESC, messageCount DESC`. Each row is the slim `{ platform, platformUserId, username, displayName, avatarUrl, lastSeenAt, messageCount }`.

> **Protocol parity:** mirror at `GET /v1/chat/users/search?q=&platform=&limit=` - same fields, validation, and empty-below-2-chars behaviour. See [REST API](./rest-api.md#chat-user-search) and [Chat](../features/chat.md#name-completion-searchplatformusers).

## Chatter List

Who is in the chat right now, per platform — see [Chatter List](../features/chatter-list.md).

### `chatters(platforms: [String!]): ChattersSnapshot!`

**Guard:** `chat:read` + feature `feature:chat-viewer-list` (identical on REST and the WebSocket channel). Popout tokens with `chat:read` are accepted.

- **`platforms`** - optional filter; omit (or pass `[]`) for every supported platform. An unknown platform is a `BAD_REQUEST` error `Bad request: Unsupported chatter platform: <name>`. A registered platform hidden for this account (Kick without a usable channel connection) returns no entry when explicitly requested.

```graphql
{
  chatters {
    supportedPlatforms
    platforms { platform available reason total truncated updatedAt }
    chatters { platform userId login displayName avatarUrl color role lastMessageAt present firstSeenAt lastSeenAt }
  }
}
```

| Type | Field | Notes |
|---|---|---|
| `ChattersSnapshot` | `supportedPlatforms: [String!]!` | Registered providers visible for this account: Twitch, plus Kick when a usable Kick channel is connected |
| | `platforms: [ChatterPlatformStatus!]!` | One per requested platform |
| | `chatters: [Chatter!]!` | Present chatters first, sorted broadcaster → moderators → bots → VIPs → viewers, then by display name; then the recently-left entries (`present: false`) in the same order |
| `ChatterPlatformStatus` | `platform`, `available: Boolean!`, `reason: String` | `reason` = `missing_scope` \| `not_connected` \| `disabled` \| `source_unavailable` when not available. `source_unavailable` means the list source failed; recent writers still appear |
| | `total: Int`, `truncated: Boolean!`, `updatedAt: DateTime` | Platform count of the last snapshot (people in the chat — never recently-left entries); `truncated` when the platform lists fewer entries than its full count or Lumio’s cap applies. Kick’s ordinary chatter group is capped at 100. `total` is `null` and `truncated` is `false` when the source is unavailable; count `present: true` entries |
| `Chatter` | `platform`, `userId`, `login`, `displayName`, `avatarUrl`, `color`, `role`, `lastMessageAt` | Key = (`platform`, `userId`). `role` = `broadcaster` \| `moderator` \| `bot` \| `vip` \| `viewer` |
| | `present: Boolean!` | `false` = recently left: kept for `recently_left_retention_secs` (30 min) after `lastSeenAt`, then dropped |
| | `firstSeenAt: DateTime` | When the person (re)entered the chat in the current stream; stable while they stay, new after a rejoin. `null` only for entries written before this field existed |
| | `lastSeenAt: DateTime` | Later of the last snapshot that listed them and their last message; frozen once `present` is `false`. For present rows it may be up to 5 min old — render "since" from `firstSeenAt` |

No field is platform-specific.

> **Protocol parity:** mirror at `GET /v1/chat/chatters` ([REST API](./rest-api.md#chatter-list)); live updates on the `chatters:{account_id}` channel ([WebSocket](./websocket.md#chatters-channel)).

## Ideas Hub

Community idea board with voting, comments, moderation, categories, and tags. All GET queries use `OptionalAuth` - they are public and return data for unauthenticated callers too. Mutations require the `system:ideas_hub` feature flag to be enabled on the account.

### Queries

| Query | Arguments | Returns | Permission |
|-------|-----------|---------|------------|
| `ideas` | `filter: IdeaFilterInput, sort: IdeaSortInput, limit: Int! = 20, offset: Int! = 0` | `GqlIdeaConnection!` | Public |
| `idea` | `id: UUID!` | `GqlIdea` | Public |
| `ideaComments` | `ideaId: UUID!` | `[GqlIdeaComment!]!` | Public |
| `ideaCategories` | - | `[GqlIdeaCategory!]!` | Public |
| `ideaTags` | `search: String` | `[GqlIdeaTag!]!` | Public |
| `ideaVoters` | `ideaId: UUID!` | `[GqlIdeaVoter!]!` | Public |
| `ideaTimeline` | `ideaId: UUID!` | `[GqlIdeaTimelineEntry!]!` | Public |
| `ideaParticipants` | `ideaId: UUID!, search: String` | `[GqlIdeaAuthor!]!` | Signed-in user session or personal API key |

`ideaParticipants` returns the union of the idea author, voters, and commenters filtered by the optional `search` string. Used to populate the @mention autocomplete dropdown in idea comments.

### Mutations

| Mutation | Arguments | Returns | Permission |
|----------|-----------|---------|------------|
| `createIdea` | `input: CreateIdeaInput!` | `GqlIdea!` | `ideas:create` |
| `updateIdea` | `id: UUID!, input: UpdateIdeaInput!` | `GqlIdea!` | `ideas:edit` or `ideas:moderate_edit` |
| `deleteIdea` | `id: UUID!` | `Boolean!` | `ideas:delete` or `ideas:moderate_delete` |
| `voteIdea` | `id: UUID!, voteType: String!` | `GqlIdea!` | `ideas:vote` |
| `removeVote` | `id: UUID!` | `GqlIdea!` | `ideas:vote` |
| `createIdeaComment` | `input: CreateIdeaCommentInput!` | `GqlIdeaComment!` | `ideas:comment_create` |
| `updateIdeaComment` | `id: UUID!, body: String!` | `GqlIdeaComment!` | `ideas:comment_edit` |
| `deleteIdeaComment` | `id: UUID!` | `Boolean!` | `ideas:comment_delete` or `ideas:moderate_comment` |
| `voteIdeaComment` | `id: UUID!, voteType: String!` | `GqlIdeaComment!` | `ideas:comment_vote` |
| `removeIdeaCommentVote` | `id: UUID!` | `GqlIdeaComment!` | `ideas:comment_vote` |
| `updateIdeaStatus` | `id: UUID!, status: String!` | `GqlIdea!` | `ideas:moderate_status` |
| `createIdeaCategory` | `input: CreateIdeaCategoryInput!` | `GqlIdeaCategory!` | Admin `ideas:edit` |
| `updateIdeaCategory` | `id: UUID!, input: UpdateIdeaCategoryInput!` | `GqlIdeaCategory!` | Admin `ideas:edit` |
| `deleteIdeaCategory` | `id: UUID!` | `Boolean!` | Admin `ideas:delete` |
| `createIdeaTag` | `name: String!` | `GqlIdeaTag!` | `ideas:create` |
| `deleteIdeaTag` | `id: UUID!` | `Boolean!` | Admin `ideas:delete` |

### Types

#### `GqlIdea`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Idea ID |
| `author` | `GqlIdeaAuthor` | Author info; `null` when `deleted` |
| `deleted` | `Boolean!` | The idea was deleted while other people's comments hang off it (tombstone): no author, empty `title`/`description`, no votes, tags or timeline. See [Ideas Hub → Deletion and tombstones](../features/ideas-hub.md#deletion-and-tombstones) |
| `category` | `GqlIdeaCategory!` | Category |
| `tags` | `[GqlIdeaTag!]!` | Assigned tags |
| `title` | `String!` | Idea title |
| `description` | `String!` | Idea description (plain text or HTML) |
| `status` | `String!` | Status slug (e.g. `open`, `in_progress`, `done`, `declined`) |
| `voteCountUp` | `Int!` | Number of upvotes |
| `voteCountDown` | `Int!` | Number of downvotes |
| `commentCount` | `Int!` | Number of live comments (tombstones not counted) |
| `myVote` | `String` | Authenticated caller's vote (`"up"`, `"down"`, or `null`) |
| `createdAt` | `String!` | ISO-8601 timestamp |
| `updatedAt` | `String!` | ISO-8601 timestamp |

#### `GqlIdeaConnection`

| Field | Type | Description |
|-------|------|-------------|
| `items` | `[GqlIdea!]!` | Page of ideas |
| `total` | `Int!` | Total matching the filter |

#### `GqlIdeaAuthor`

Also the element type of `ideaParticipants`.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | User ID |
| `displayName` | `String!` | Display name |
| `login` | `String` | Platform login. Only for Ideas staff (`ideas:moderate_read` on the user or admin role) and for the user themself; `null` for everyone else, including anonymous callers. Also `null` for a deleted user |
| `avatarUrl` | `String` | Avatar URL |

#### `GqlIdeaComment`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Comment ID |
| `ideaId` | `UUID!` | Parent idea ID |
| `author` | `GqlIdeaAuthor` | Comment author; `null` when `deleted` |
| `deleted` | `Boolean!` | The comment was deleted while replies hang off it (tombstone): no author, empty `body`, no votes |
| `parentId` | `UUID` | Parent comment ID for nested replies |
| `body` | `String!` | Sanitized HTML from rich text editor |
| `createdAt` | `String!` | ISO-8601 timestamp |
| `updatedAt` | `String!` | ISO-8601 timestamp |
| `voteCountUp` | `Int!` | Number of upvotes on the comment |
| `voteCountDown` | `Int!` | Number of downvotes on the comment |
| `myVote` | `String` | Authenticated caller's vote on the comment (`"up"`, `"down"`, or `null`) |
| `replies` | `[GqlIdeaComment!]!` | Nested replies (one level deep) |

Comment bodies contain sanitized HTML. @mentions appear as `<span data-mention-id="UUID" class="mention">@Name</span>`.

#### `GqlIdeaCategory`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Category ID |
| `name` | `String!` | Machine-readable slug |
| `label` | `String!` | Display label |
| `color` | `String` | Hex color for UI display |
| `sortOrder` | `Int!` | Sort position |
| `createdAt` | `String!` | ISO-8601 timestamp |

#### `GqlIdeaTag`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Tag ID |
| `name` | `String!` | Tag name |
| `createdBy` | `UUID` | Creating user |
| `createdAt` | `String!` | ISO-8601 timestamp |

#### `GqlIdeaTimelineEntry`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Entry ID |
| `actor` | `GqlIdeaAuthor` | Who performed the action |
| `action` | `String!` | `status_changed`, `title_changed`, `description_changed` or `category_changed` |
| `oldValue` | `String` | Previous value (see below) |
| `newValue` | `String` | New value (see below) |
| `createdAt` | `String!` | ISO-8601 timestamp |

What a caller sees in `oldValue` / `newValue` depends on the action. For `status_changed` (status key) and `category_changed` (category label), everyone sees both values. For `title_changed` and `description_changed` (the previous and new text), only the idea's author and Ideas staff (`ideas:moderate_read`) see the values. Anonymous callers and other signed-in users get `null` for both values; `action` is still returned. REST `GET /v1/ideas/:id` (`timeline`) applies the same rule.

#### `GqlIdeaVoter`

| Field | Type | Description |
|-------|------|-------------|
| `userId` | `UUID!` | Voting user |
| `voteType` | `String!` | `"up"` or `"down"` |
| `displayName` | `String!` | Display name |
| `avatarUrl` | `String` | Avatar URL |

#### `IdeaFilterInput`

| Field | Type | Description |
|-------|------|-------------|
| `status` | `String` | Filter by status slug |
| `categoryId` | `UUID` | Filter by category |
| `tagIds` | `[UUID!]` | Filter by one or more tags |
| `authorId` | `UUID` | Filter by author |
| `search` | `String` | Full-text search on title and description |

#### `IdeaSortInput` (enum)

| Value | Description |
|-------|-------------|
| `NEWEST` | Most recently created first |
| `MOST_VOTED` | Highest net vote count first |
| `MOST_COMMENTED` | Most comments first |
| `RECENTLY_UPDATED` | Most recently updated first |

> **Protocol parity:** All queries and mutations above have matching REST endpoints under `/v1/ideas` - see [REST API](./rest-api.md#ideas-hub).

## Developer Applications

User-scoped queries and mutations for the developer application flow. No account context is required.

### Queries

#### `myDeveloperApplication: DeveloperApplication`

Returns the authenticated user's latest developer application. Returns `null` if no application exists.

### Mutations

#### `submitDeveloperApplication(input: SubmitDeveloperApplicationInput!): DeveloperApplication!`

Submit a developer application. Validates the slug format and availability, checks that the user does not already have a developer profile or a pending application.

**Errors:**
- `"application_type must be 'solo' or 'team'"` - invalid type
- `"Slug must be between 3 and 50 characters"` / `"Slug must start with a lowercase letter"` / `"Slug must contain only lowercase letters, digits, and hyphens"` - slug format
- `"You already have a developer profile"` - user is already a developer
- `"You already have a pending application"` - previous application still pending
- `"Slug is already taken"` - slug in use

### Types

#### `DeveloperApplication`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Application ID |
| `userId` | `UUID!` | Applicant's user ID |
| `applicationType` | `String!` | `"solo"` or `"team"` |
| `displayName` | `String!` | Developer/team display name |
| `slug` | `String!` | URL slug |
| `description` | `String!` | Description |
| `motivation` | `String!` | Why the user wants developer access |
| `whatToBuild` | `String!` | Planned extensions |
| `githubUrl` | `String` | GitHub profile URL |
| `websiteUrl` | `String` | Website URL |
| `experience` | `String` | Development experience |
| `avatarKey` | `String` | Upload key for avatar |
| `status` | `String!` | `"pending"`, `"approved"`, or `"rejected"` |
| `reviewNotes` | `String` | Reviewer notes |
| `reviewedBy` | `UUID` | Reviewer's user ID |
| `reviewedAt` | `DateTime` | Review timestamp |
| `createdAt` | `DateTime!` | Submission timestamp |
| `updatedAt` | `DateTime!` | Last update timestamp |

#### `SubmitDeveloperApplicationInput`

| Field | Type | Required |
|-------|------|----------|
| `applicationType` | `String!` | Yes |
| `displayName` | `String!` | Yes |
| `slug` | `String!` | Yes |
| `description` | `String!` | Yes |
| `motivation` | `String!` | Yes |
| `whatToBuild` | `String!` | Yes |
| `githubUrl` | `String` | No |
| `websiteUrl` | `String` | No |
| `experience` | `String` | No |

> **Protocol parity:** Both operations have matching REST endpoints - see [REST API](./rest-api.md#developer-applications).

## Developer Verification (self-service)

KYC verification an **approved developer** submits about themselves (individual or company) to unlock paid-extension publishing - the developer-facing counterpart to the admin review operations below. First-party principal required (ZAF-469): a popout/overlay/widget/extension token is rejected with a `FORBIDDEN` error. The caller must be an approved developer (have a `developer_profiles` row).

> Deliberately **not** gated on `feature:extension_development`: that feature is *granted by* verification approval, so gating submission on it would be circular.

### Queries

#### `developerVerificationStatus: VerificationDetailGql`

Returns the authenticated developer's own verification record, or `null` if none has been submitted (or the caller is not yet an approved developer).

### Mutations

#### `submitDeveloperVerification(input: SubmitVerificationInput!): VerificationDetailGql!`

Submit (or resubmit) the developer's own KYC verification. **Idempotent upsert** - one record per developer; a resubmit re-enters `pending` and clears any prior review verdict. An already-`verified` record is terminal via self-service and cannot be resubmitted. The `developer_type` is inferred from whether `companyName` is provided. Emits the `developer:verification_submitted` audit event (user scope; no KYC/PII in metadata).

**Errors:**
- `"You must be an approved developer to submit verification"` - caller has no developer profile
- `"Your developer verification is already approved"` - the record is already `verified`
- `"Legal name is required"` / `"Address line 1 is required"` / `"Postal code is required"` / `"City is required"` / `"Country is required"` / `"Country must be a 2-letter ISO code"` / `"Tax number must be at most 50 characters"` / `"VAT ID must be at most 50 characters"` - validation

A submit without any of `taxNumber`, `vatId`, `smallBusinessDeclared` keeps the stored tax details.

#### `updateDeveloperTaxDetails(input: TaxDetailsInput!): VerificationDetailGql!`

Set the tax details (`taxNumber`, `vatId`, `smallBusinessDeclared`) a payout's credit note is derived from, in any verification status. They are self-declared: an update does not reset the review and never changes an issued note. Which details a payout needs is listed under [`PUT /v1/developer/verification/tax-details`](./rest-api.md#put-v1developerverificationtax-details). Emits `developer:tax_details_updated` (user scope). Errors: the validation texts above, `"You must be an approved developer to submit verification"`, `"Submit your developer verification before entering tax details"`.

### Types

#### `SubmitVerificationInput`

| Field | Type | Required |
|-------|------|----------|
| `legalName` | `String!` | Yes |
| `companyName` | `String` | No |
| `addressLine1` | `String!` | Yes |
| `addressLine2` | `String` | No |
| `postalCode` | `String!` | Yes |
| `city` | `String!` | Yes |
| `country` | `String!` | Yes (2-letter ISO) |
| `taxId` | `String` | No |
| `tradeRegisterId` | `String` | No |
| `documentKey` | `String` | No |
| `taxNumber` | `String` | No (Steuernummer) |
| `vatId` | `String` | No (USt-IdNr. / foreign VAT ID) |
| `smallBusinessDeclared` | `Boolean` | No (§ 19 UStG) |

`TaxDetailsInput` has the three tax fields only.

#### `VerificationDetailGql`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Verification ID |
| `developerId` | `UUID!` | Developer profile ID |
| `legalName` | `String!` | Legal name |
| `companyName` | `String` | Company name (company type) |
| `addressLine1` | `String!` | Address line 1 |
| `addressLine2` | `String` | Address line 2 |
| `postalCode` | `String!` | Postal code |
| `city` | `String!` | City |
| `country` | `String!` | ISO-3166-1 alpha-2 country code |
| `taxId` | `String` | Tax ID (legacy free text) |
| `taxNumber` | `String` | Steuernummer |
| `vatId` | `String` | USt-IdNr. / foreign VAT ID |
| `smallBusinessDeclared` | `Boolean` | § 19 UStG small business; `null` = not answered |
| `taxDetailsUpdatedAt` | `String` | When the tax details were last entered (RFC 3339) |
| `tradeRegisterId` | `String` | Trade register ID |
| `documentKey` | `String` | Upload key for a supporting document |
| `status` | `String!` | `"pending"`, `"verified"`, or `"rejected"` |
| `reviewNotes` | `String` | Reviewer notes (e.g. rejection reason) |
| `reviewedBy` | `UUID` | Reviewer's user ID |
| `reviewedAt` | `String` | Review timestamp (RFC 3339) |
| `createdAt` | `String!` | First submission timestamp (RFC 3339) |
| `updatedAt` | `String!` | Last update timestamp (RFC 3339) |

> **Protocol parity:** All three operations have matching REST endpoints under `/v1/developer/verification` - see [REST API](./rest-api.md#developer-verification-self-service).

## Developer Credit Notes

Self-billed credit notes (Gutschrift) of developer payouts (ZAF-2807). Field set, guards and error texts match the [REST endpoints](./rest-api.md#developer-credit-notes). Binary downloads are not a GraphQL fit: each note carries `downloadUrl`, the authenticated REST URL of its PDF (`null` while the PDF is being generated).

### Queries

#### `developerCreditNotes(limit: Int = 20, offset: Int = 0): [DeveloperCreditNote!]!`

The caller's own credit notes and cancellations, newest first. Requires `extension-dev:payouts` and `feature:extension_development`; first-party user.

#### `developerCreditNote(id: UUID!): DeveloperCreditNote!`

One of the caller's own notes; another developer's note fails with `"Credit note not found"`. Same guard.

#### `adminCreditNotes(developerId: UUID, limit: Int = 20, offset: Int = 0): [AdminCreditNote!]!` / `adminCreditNote(id: UUID!): AdminCreditNote!`

Operators; include notes whose profile was deleted. Requires `billing:read` (admin-scope).

#### `adminDeveloperPayouts(status: String, limit: Int = 20, offset: Int = 0): [AdminDeveloperPayout!]!`

Developer payouts for operators, newest first, including payouts of deleted profiles; `status` filters on `pending`, `processing`, `completed` or `failed` (anything else fails with `"Status must be one of pending, processing, completed, failed"`). Requires `billing:read` (admin-scope).

### Mutations

#### `cancelCreditNote(id: UUID!, input: CancelCreditNoteInput!): CancelCreditNoteResult!`

Record a developer objection (`reason: "developer_objection"`, `objectionReceivedAt` required) or a correction (`reason: "correction"`), optionally with `reissue: true` for a corrected note for the same payout and period. Requires `billing:edit` (admin-scope). Emits `system:developer_credit_note_cancelled`. Errors as on REST, including `CREDIT_NOTE_AMOUNT_MISMATCH`.

#### `completeDeveloperPayout(id: UUID!): SettleDeveloperPayoutResult!` / `failDeveloperPayout(id: UUID!): SettleDeveloperPayoutResult!`

Mark a `pending` or `processing` developer payout paid, or failed (the balance is credited back and the credit note cancelled). Requires `billing:edit` (admin-scope). Emits `system:developer_payout_completed` / `system:developer_payout_failed`. Errors as on REST: `Payout not found`, `PAYOUT_NOT_IN_FLIGHT`, and for `failDeveloperPayout` `PAYOUT_BEING_SENT` while the payout cycle may be sending it. See [Developer Payouts](../features/developer-payouts.md).

### Types

`DeveloperCreditNote`: `id`, `kind`, `number`, `issuedAt`, `payoutId`, `cancelsId`, `cancelledAt`, `cancellationReason`, `periodStart`, `periodEnd`, `currency`, `netAmount`, `vatRateBp`, `vatAmount`, `grossAmount`, `vatTreatment`, `pdfStatus`, `downloadUrl`, `deliveredAt` (meaning as on REST). `AdminCreditNote`: `note: DeveloperCreditNote!`, `developerId`, `supplierLegalName`, `supplierCountry`, `objectionReceivedAt`, `recordedBy`. `CancelCreditNoteResult`: `cancellation: AdminCreditNote!`, `reissued: AdminCreditNote`. `AdminDeveloperPayout`: `id`, `developerId`, `amount`, `currency`, `method`, `status`, `stripeTransferId`, `paypalBatchId`, `payoutReference`, `createdAt`, `completedAt`, `executionStartedAt`, `needsOperator` (meaning as on REST). `SettleDeveloperPayoutResult`: `payout: AdminDeveloperPayout!`, `refunded`, `cancellationNumber`.

## Admin Developer Applications

Admin-scope queries and mutations for reviewing developer applications. All require `developer-verifications:*` admin permissions.

### Queries

#### `adminDeveloperApplications(status: String): [AdminApplicationListItem!]!`

List developer applications with optional status filter. Requires `developer-verifications:read`.

#### `adminDeveloperApplication(id: UUID!): AdminApplicationDetail`

Get full details of a specific application. Requires `developer-verifications:read`.

### Mutations

#### `approveDeveloperApplication(input: ApproveApplicationInput!): ApplicationActionResult!`

Approve an application. Creates the developer profile, seeds default team roles (for team applications), and sends notifications. Requires `developer-verifications:edit`.

#### `rejectDeveloperApplication(input: RejectApplicationInput!): ApplicationActionResult!`

Reject an application. Sends rejection notifications. Requires `developer-verifications:edit`. The `notes` field is required to provide a rejection reason.

### Types

#### `AdminApplicationListItem`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Application ID |
| `userId` | `UUID!` | Applicant's user ID |
| `applicationType` | `String!` | `"solo"` or `"team"` |
| `displayName` | `String!` | Display name |
| `slug` | `String!` | URL slug |
| `status` | `String!` | Application status |
| `createdAt` | `String!` | Submission timestamp |
| `userDisplayName` | `String` | Applicant's display name |
| `userAvatarUrl` | `String` | Applicant's avatar URL |

#### `AdminApplicationDetail`

Same fields as `DeveloperApplication` with string-formatted timestamps.

#### `ApplicationActionResult`

Returned by `approveDeveloperApplication` and `rejectDeveloperApplication`.

| Field | Type | Description |
|-------|------|-------------|
| `success` | `Boolean!` | Whether the action succeeded |
| `newStatus` | `String!` | The new application status |

#### `ApproveApplicationInput` / `RejectApplicationInput`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Application ID |
| `notes` | `String` on approve, `String!` on reject | Reviewer notes |

> **Protocol parity:** All queries and mutations have matching REST endpoints under `/v1/admin/developer-applications` - see [REST API](./rest-api.md#admin-developer-applications).

## Developer Teams

Queries and mutations for developer team management. Team operations use team-scoped RBAC permissions (see [Team RBAC](../developer-guide/rbac-permissions.md#team-rbac-developer-teams)). Every operation except `developerTeamInviteByCode` requires a first-party user. `createDeveloperTeam` and `acceptDeveloperTeamInvite` additionally require the `feature:extension_development` plan feature, checked after the first-party gate with the same error as REST: `Feature 'feature:extension_development' is not available`.

### Queries

| Query | Arguments | Returns | Permission |
|-------|-----------|---------|------------|
| `developerTeams` | - | `[DeveloperTeam!]!` | Auth (developer) |
| `developerTeam` | `teamId: UUID!` | `DeveloperTeam` | Team member |
| `developerTeamMembers` | `teamId: UUID!` | `[DeveloperTeamMember!]!` | `team-members:read` |
| `developerTeamInvites` | `teamId: UUID!` | `[DeveloperTeamInvite!]!` | `team-members:read` |
| `developerTeamInviteByCode` | `code: String!` | `DeveloperTeamInviteDetail` | Public |
| `developerTeamRoles` | `teamId: UUID!` | `[DeveloperTeamRole!]!` | `team-members:read` |
| `developerTeamRole` | `teamId: UUID!, roleId: UUID!` | `DeveloperTeamRoleDetail!` | `team-members:read` |
| `availableTeamPermissions` | - | `[TeamPermission!]!` | Auth (first-party user) |

### Mutations

| Mutation | Arguments | Returns | Permission |
|----------|-----------|---------|------------|
| `createDeveloperTeam` | `name: String!` | `DeveloperTeam!` | Auth (developer) + `feature:extension_development` |
| `updateDeveloperTeam` | `teamId: UUID!, name: String!` | `Boolean!` | `team-settings:edit` |
| `deleteDeveloperTeam` | `teamId: UUID!` | `Boolean!` | Team owner only |
| `updateDeveloperTeamMemberRole` | `teamId: UUID!, memberId: UUID!, roleId: UUID!` | `Boolean!` | `team-members:edit` |
| `removeDeveloperTeamMember` | `teamId: UUID!, memberId: UUID!` | `Boolean!` | `team-members:remove` |
| `createDeveloperTeamInvite` | `teamId: UUID!, input: CreateTeamInviteInput!` | `DeveloperTeamInvite!` | `team-members:invite` |
| `deleteDeveloperTeamInvite` | `inviteId: UUID!, teamId: UUID!` | `Boolean!` | `team-members:invite` |
| `acceptDeveloperTeamInvite` | `code: String!` | `AcceptTeamInviteResult!` | Auth + `feature:extension_development` |
| `createDeveloperTeamRole` | `teamId: UUID!, input: CreateTeamRoleInput!` | `DeveloperTeamRoleDetail!` | `team-settings:edit` |
| `updateDeveloperTeamRole` | `teamId: UUID!, roleId: UUID!, input: UpdateTeamRoleInput!` | `DeveloperTeamRoleDetail!` | `team-settings:edit` |
| `deleteDeveloperTeamRole` | `teamId: UUID!, roleId: UUID!` | `Boolean!` | `team-settings:edit` |

The team-invite email opens `/invite/dev/{code}` on the configured web app origin. That page accepts by code; the bell accepts by the invite row ID without exposing the code. Both accept paths use the same checks and return `INVITE_NOT_FOUND`, `INVITE_EXPIRED`, `INVITE_FULL`, `ALREADY_MEMBER`, or `INVITE_NO_LONGER_VALID` in `extensions.code` when applicable. The bell's decline action deletes an unused single-use invite, leaves a shared or used invite in place, and succeeds if the invite is already gone.

### Types

#### `DeveloperTeam`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Team ID |
| `name` | `String!` | Team name |
| `slug` | `String!` | URL slug |
| `ownerId` | `UUID!` | Owning user |
| `createdAt` | `String!` | Creation timestamp |
| `updatedAt` | `String!` | Update timestamp |

#### `DeveloperTeamMember`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Membership ID |
| `teamId` | `UUID!` | Team ID |
| `userId` | `UUID!` | Member's user ID |
| `roleId` | `UUID!` | Assigned role ID |
| `roleName` | `String!` | Role display name |
| `roleSlug` | `String!` | Role slug |
| `roleColor` | `String` | Role colour |
| `displayName` | `String!` | Display name |
| `email` | `String!` | Email address |
| `avatarUrl` | `String` | Avatar URL |
| `createdAt` | `String!` | When they joined |

#### `DeveloperTeamInvite`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Invite ID |
| `teamId` | `UUID!` | Team ID |
| `invitedBy` | `UUID!` | Inviting user |
| `invitedByName` | `String` | Inviting user's display name |
| `email` | `String` | Target email, when the invite is addressed |
| `inviteCode` | `String!` | Invite code |
| `roleId` | `UUID!` | Role assigned on accept |
| `roleName` | `String!` | Role name |
| `roleSlug` | `String!` | Role slug |
| `maxUses` | `Int!` | Maximum uses |
| `useCount` | `Int!` | Current use count |
| `expiresAt` | `String` | Expiration timestamp |
| `acceptedAt` | `String` | When it was accepted |
| `acceptedBy` | `UUID` | Accepting user |
| `createdAt` | `String!` | Creation timestamp |

#### `DeveloperTeamInviteDetail`

Returned by `developerTeamInviteByCode` - the invite as seen by the recipient, without team-internal fields.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Invite ID |
| `teamId` | `UUID!` | Team ID |
| `teamName` | `String!` | Team name |
| `teamSlug` | `String!` | Team slug |
| `invitedByName` | `String` | Inviting user's display name |
| `inviteCode` | `String!` | Invite code |
| `roleId` | `UUID!` | Role assigned on accept |
| `roleName` | `String!` | Role name |
| `roleSlug` | `String!` | Role slug |
| `maxUses` | `Int!` | Maximum uses |
| `useCount` | `Int!` | Current use count |
| `expiresAt` | `String` | Expiration timestamp |
| `isExpired` | `Boolean!` | Whether the invite has expired |
| `isFull` | `Boolean!` | Whether `useCount` has reached `maxUses` |

#### `DeveloperTeamRole`

List shape - carries counts rather than the permission strings.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Role ID |
| `teamId` | `UUID!` | Owning team ID |
| `name` | `String!` | Role name |
| `slug` | `String!` | Role slug |
| `description` | `String` | Role description |
| `isDefault` | `Boolean!` | Default role |
| `isSystem` | `Boolean!` | System role (cannot be deleted) |
| `color` | `String` | Role colour |
| `sortOrder` | `Int!` | Sort order |
| `permissionCount` | `Int!` | Number of permissions granted |
| `memberCount` | `Int!` | Number of members holding it |
| `createdAt` | `String!` | Creation timestamp |
| `updatedAt` | `String!` | Update timestamp |

#### `DeveloperTeamRoleDetail`

Detail shape - same as `DeveloperTeamRole` but with `permissions: [String!]!` in place of `permissionCount`. Retains `memberCount` (`Int!`, number of members holding the role).

#### `TeamPermission`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Permission string (e.g. `team-extensions:create`) |
| `category` | `String!` | Grouping used by the role editor |

> **Protocol parity:** All queries and mutations have matching REST endpoints under `/v1/developer/teams` - see [REST API](./rest-api.md#developer-teams).

## Developer Payout Settings

Self-scoped read of the **authenticated developer's** saved payout configuration. This is a private, first-party resolver - do not confuse it with the public `developerProfile(slug)` store profile documented below (that returns the public `DeveloperPublicProfile`, which carries **no** payout fields).

### Queries

#### `myDeveloperProfile: DeveloperProfile`

Returns the authenticated developer's own profile. The caller needs a logged-in user session or their own API key. Errors with `Developer application required…` if the caller has not applied as a developer. REST twin: `GET /v1/developer/profile`.

**Permission:** `extension-dev:read` · **Feature:** `feature:extension_development`

#### `developerPayoutSettings: DeveloperProfile`

Returns the authenticated developer's saved payout settings - `payoutMethod`, `stripeConnectId`, `paypalEmail`, and SEPA `bankIban` / `bankBic` / `bankName`, plus `revenueBalance` / `totalEarned` - for prefilling the payouts form. Companion read to the `updateDeveloperPayoutSettings` mutation, which returns the same `DeveloperProfile` type. Errors with `Developer profile not found` if the caller has not applied as a developer. `updateDeveloperPayoutSettings` bounds the plaintext with the same rule and error text as REST `POST /v1/developer/payouts`: IBAN at most 34 characters not counting spaces (50 with spaces), BIC at most 11, PayPal email and bank name at most 255 each. A longer value is refused with `IBAN must be at most 34 characters, not counting spaces`, `BIC must be at most 11 characters`, `PayPal email must be at most 255 characters` or `Bank name must be at most 255 characters` before anything is stored. The four fields are stored encrypted.

**Permission:** `extension-dev:payouts` · **Feature:** `feature:extension_development`

### Types

#### `DeveloperProfile`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Developer profile ID |
| `userId` | `UUID!` | Owning user ID |
| `stripeConnectId` | `String` | Stripe Connect account id (Phase 9) |
| `paypalEmail` | `String` | PayPal payout email |
| `bankIban` | `String` | SEPA IBAN |
| `bankBic` | `String` | SEPA BIC |
| `bankName` | `String` | Account holder name |
| `payoutMethod` | `String` | `"stripe"`, `"paypal"`, or `"bank"` |
| `revenueBalance` | `Int!` | Current balance, minor units |
| `totalEarned` | `Int!` | Lifetime earnings, minor units |
| `createdAt` | `DateTime!` | Profile creation date |
| `updatedAt` | `DateTime!` | Last update date |

> **Protocol parity:** matches REST `GET /v1/developer/payout-settings` - see [REST API](./rest-api.md#get-v1developerpayout-settings).

## Marketplace

Public, unauthenticated queries for the extension store: `marketplaceExtensions`, `marketplaceExtension(slug)`, `marketplaceExtensionReviews(slug)`, `marketplaceFeatured` and `marketplaceCategories`. A review (`MarketplaceReviewEntry`) has `id`, `rating`, `comment`, `createdAt` and `updatedAt`. It contains no reviewer identity, neither a user ID nor a name.

> **Protocol parity:** matches the REST endpoints under `/v1/marketplace` - see [REST API](./rest-api.md).

## Developer Store Profiles

Public queries for developer and team profile pages displayed in the extension store. No authentication required.

### Queries

#### `developerProfile(slug: String!): DeveloperPublicProfile`

Get a public developer profile by slug. Returns `null` if not found. Includes aggregate stats and a list of published extensions.

#### `developerTeamProfile(slug: String!): DeveloperTeamProfile`

Get a public team profile by slug. Returns `null` if not found. Includes aggregate stats, public member list, and published extensions.

#### `inlineDeveloperPanel(developerId: UUID, teamId: UUID): InlineDeveloperPanel`

Get a compact developer info panel for display on extension detail pages. Returns the developer/team name, slug, avatar, extension count, and whether the developer is a team.

### Types

#### `DeveloperPublicProfile`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Developer profile ID |
| `displayName` | `String!` | Display name |
| `slug` | `String!` | URL slug |
| `description` | `String` | Bio/description |
| `githubUrl` | `String` | GitHub URL |
| `websiteUrl` | `String` | Website URL |
| `avatarKey` | `String` | Avatar upload key |
| `createdAt` | `DateTime!` | Profile creation date |
| `stats` | `DeveloperStats!` | Aggregate statistics |
| `extensions` | `[ProfileExtension!]!` | Published extensions |

#### `DeveloperTeamProfile`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Team ID |
| `name` | `String!` | Team name |
| `slug` | `String!` | URL slug |
| `description` | `String` | Description |
| `githubUrl` | `String` | GitHub URL |
| `websiteUrl` | `String` | Website URL |
| `avatarKey` | `String` | Avatar upload key |
| `createdAt` | `DateTime!` | Creation date |
| `stats` | `DeveloperStats!` | Aggregate statistics |
| `members` | `[TeamMemberSummary!]!` | Public member list |
| `extensions` | `[ProfileExtension!]!` | Published extensions |

#### `DeveloperStats`

| Field | Type | Description |
|-------|------|-------------|
| `extensionCount` | `Int!` | Number of published extensions |
| `totalInstalls` | `Int!` | Total installs across all extensions |
| `avgRating` | `Float!` | Average rating across all extensions |

#### `ProfileExtension`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Extension ID |
| `shortId` | `String!` | Short identifier |
| `slug` | `String!` | URL slug |
| `name` | `String!` | Extension name |
| `description` | `String` | Short description |
| `category` | `String!` | Extension category |
| `iconKey` | `String` | Icon upload key |
| `pricingType` | `String!` | `"free"`, `"paid"`, etc. |
| `pricingAmount` | `Int` | Price in minor units |
| `pricingCurrency` | `String!` | ISO-4217 currency code |
| `installCount` | `Int!` | Number of installs |
| `ratingAvg` | `Float!` | Average rating |
| `ratingCount` | `Int!` | Number of ratings |
| `publishedAt` | `DateTime` | Publish date |

#### `TeamMemberSummary`

| Field | Type | Description |
|-------|------|-------------|
| `userId` | `UUID!` | Member's user ID |
| `displayName` | `String!` | Display name |
| `avatarUrl` | `String` | Avatar URL |
| `role` | `String!` | Role name |

#### `InlineDeveloperPanel`

| Field | Type | Description |
|-------|------|-------------|
| `developerId` | `UUID!` | Developer/team ID |
| `displayName` | `String!` | Display name |
| `slug` | `String` | URL slug |
| `description` | `String` | Short description |
| `avatarKey` | `String` | Avatar upload key |
| `extensionCount` | `Int!` | Number of extensions |
| `isTeam` | `Boolean!` | Whether this is a team profile |

> **Protocol parity:** `developerProfile` and `developerTeamProfile` have matching REST endpoints - see [REST API](./rest-api.md#developer-store-profiles).

### Extension Limits

#### `developerLimits: DeveloperLimits!`

Returns the resolved limits for the authenticated developer, including per-category breakdowns with resolution sources and all extension-specific overrides.

**Permission:** `extension-dev:read` · **Feature:** `feature:extension_development`

#### `developerLimitRequestEvents(requestId: UUID!): [LimitRequestEvent!]!`

Returns the timeline events for a limit request owned by the authenticated developer.

**Permission:** `extension-dev:read` · **Feature:** `feature:extension_development`

#### `extensionLimits(extensionId: UUID!): ExtensionLimits!`

Returns the resolved sound limits for an extension. Requires the caller to be the extension owner or a member of the owning developer team.

**Permission:** `extension-dev:read` · **Feature:** `feature:extensions`

#### `ExtensionLimits`

| Field | Type | Description |
|-------|------|-------------|
| `maxSounds` | `Int!` | Resolved max bundled sounds |
| `maxSoundsSource` | `String!` | Resolution source: `default`, `developer_override`, or `extension_override` |
| `maxSoundFileSize` | `Int!` | Resolved max size of a single bundled sound, in bytes |
| `maxSoundFileSizeSource` | `String!` | Resolution source for `maxSoundFileSize` |
| `maxSoundStorageBytes` | `Int!` | Resolved total sound storage budget, in bytes |
| `maxSoundStorageBytesSource` | `String!` | Resolution source for `maxSoundStorageBytes` |

### Admin - Developer Limits

#### `adminDeveloperLimits(developerId: UUID!): DeveloperLimitsGql!`

Fetch limit overrides for a developer. **Permission:** `developer-limits:read`

#### `adminSetDeveloperLimit(input: AdminSetDeveloperLimitInput!): AdminActionResultGql!`

Set or remove a developer limit override. Pass `null` for `limitValue` to remove the override. **Permission:** `developer-limits:edit`

#### `adminSetExtensionLimits(input: AdminSetExtensionLimitsInput!): AdminActionResultGql!`

Set or clear per-extension limit overrides (`maxSounds`, `maxSoundFileSize`, `maxSoundStorageBytes`). Pass `null` for any field to revert to developer/platform default. **Permission:** `developer-limits:edit`

#### `adminAllLimitRequests(status: String, scope: String, search: String): [LimitRequestGql!]!`

List all developer limit requests with optional status filter. **Permission:** `developer-limits:read`

#### `adminDeveloperLimitRequests(developerId: UUID!): [LimitRequestGql!]!`

List limit requests for a specific developer. **Permission:** `developer-limits:read`

#### `adminLimitRequestEvents(requestId: UUID!): [LimitRequestEventGql!]!`

Get timeline events for a limit request. **Permission:** `developer-limits:read`

#### `adminReviewLimitRequest(input: AdminReviewLimitRequestInput!): AdminActionResultGql!`

Approve or reject a limit request. Approving auto-applies the requested limits. Rejecting requires review notes. **Permission:** `developer-limits:edit`

### Admin - Undelivered Extension Purchases

#### `adminUndeliveredExtensionPurchases(first: Int, after: String): UndeliveredPurchasePage!`

Paid extension checkouts without delivery: still `completed`, never installed, older than one hour, newest first. Returns `{ items, nextCursor }`. Each item has `id`, `extensionId`, `extensionName`, `accountId`, `accountName` (the four are `null` once the extension or account is deleted), `stripeCheckoutSessionId`, `stripePaymentId`, `amount` (cents), `currency`, `undeliveredReason` (`detached`, `not_installable`, `install_failed`, `refund_failed`, or `null` when unknown) and `createdAt`. `first` is 1-100 (default 50); pass `nextCursor` as `after` for the next page. Invalid values fail with `first must be between 1 and 100` / `after is not a valid cursor`, as on the REST twin `GET /v1/admin/extension-purchases/undelivered`. **Permission:** `extension-purchases:read` (admin scope). See [Admin › Extension Purchases](../admin/extension-purchases.md).

## Bot Module Extension Kill Switch

#### `setBotModuleKillSwitch(accountId: UUID!, killed: Boolean!): Boolean!`

Set the extension kill switch for the caller's account: while `killed` is `true`, the bots match no extension bot-module trigger for the account, and every handler server function (`extensionExecuteHandler`) of the account's extensions of any category, widgets included, is refused with `EXTENSIONS_KILLED`. Declarative server functions (`extensionQuery`, `extensionMutate`) keep working. The state is stored (it survives a bot restart and is returned as `killed` by the internal trigger feed) and pushed live to the bots. Requires `bot-modules:edit`; `accountId` must be the caller's active account (`FORBIDDEN`, `Cannot control kill switch for another account` otherwise). Emits the audit event `account:extension_kill_switch_set`.

> **Protocol parity:** REST twin `POST /v1/bot-modules/kill` with the same permission, check, error and audit event -- see [REST API](./rest-api.md#post-v1bot-moduleskill).

## Extension Install Logs

#### `extensionInstallLogs(installId: UUID!, since: DateTime, level: String): ExtensionInstallLogsResponse!`

The newest handler-execution logs (up to 100, newest first) of one bot-module or automation-node install of the caller's active account. `since` keeps entries at or after a timestamp; `level` filters to `info`, `warn` or `error`.

**Permission:** follows the install's extension category — `bot-modules:read` for a bot module, `automations:read` for an automation node. The field itself only requires authentication. An install of another account, an unknown install, an install of any other category, and a caller without the category's permission all fail with the same error `Install not found`.

**Redaction:** `message` and `stackTrace` are scrubbed of UUIDs, @-mentions, tokens and IPv4 addresses. For a bot module, `args` holds the positional command arguments, scrubbed the same way. For an automation node, `args.nodeConfig` keeps its values with secret-looking keys masked as `"***"` at any depth, and `args.inputData` (the triggering event) is shape only: keys and nesting are kept, values become `"<string>"`, `"<number>"` or `"<bool>"`.

`ExtensionInstallLogEntry` fields: `time`, `handler`, `triggerType`, `platform`, `level`, `message`, `stackTrace`, `args` (JSON), `userName`, `userRole`, `executionMs`, `success`.

> **Protocol parity:** REST twin `GET /v1/extension-installs/{id}/logs` with the same guard, redaction and error -- see [REST API](./rest-api.md#get-v1extension-installsidlogs).

## Extension Server Functions

#### `extensionQuery(input: ExtensionQueryInput!): ExtensionFunctionResult!`

#### `extensionMutate(input: ExtensionMutateInput!): ExtensionFunctionResult!`

Run a declarative server function of an extension install by name. `functionName` is an export of the extension's `server/functions.ts`; the API looks it up in the functions manifest of the version the install runs (parsed once per version and process, the same cache as REST) and binds `params` (a JSON object, the `arg()` values) as typed SQL parameters. `extensionQuery` runs a `queryRows` definition, `extensionMutate` an `insertRow` / `patchRow` / `deleteRow` definition. `ExtensionFunctionResult` has `rows` (JSON, each the full row with `_id`, `_account_id`, `_created_at`, `_updated_at`) and `affectedCount`.

- **Editor-only:** a definition with `editorOnly: true` runs only for a dashboard session, personal API key or System key. Extension, overlay and widget tokens get `Editor-only function called outside editor`. The input has no field that could claim the editor surface.
- **Raw operations:** sessions, personal API keys and System keys may send `table` (+ `filters` / `limit`, or `functionType` / `args` / `rowId`) instead of a name; `params` is then ignored. Tokens get `Raw data operations need a signed-in session or an API key; call the server function by name`.
- **Errors:** `Not found: Unknown server function: {name}`; `Bad request: Server function '{name}' is a mutation, not a query` (and the reverse, and `... is a handler; call it through execute`); ``Bad request: missing argument `{name}` ``; the data errors and codes listed for REST.
- **Callers:** `User` / `ApiKey` of the install's account with `extension-data:read` (query) / `extension-data:edit` (mutate); System keys with `bots:internal`; an extension token for its own install, an overlay token for an install that an `ext:{slug}` layer of its overlay renders, a widget token for its widget's install.

`uploadExtensionVersion` takes the version's `functions.json` as `functionsManifest` (JSON) and checks it like the REST upload.

> **Protocol parity:** REST twins `POST /v1/extension-installs/{install_id}/query/{function_name}` and `/mutate/{function_name}` with the same callers, resolution, messages and codes -- both protocols call `services::extension_functions::prepare_call`. See [REST API](./rest-api.md#post-v1extension-installsinstall_idqueryfunction_name-and-mutatefunction_name).

#### `extensionExecuteHandler(input: ExtensionExecuteHandlerInput!): ExtensionHandlerResult!`

Run a handler server function (`query()` / `mutation()` / `action()` of the extension's `server/functions.ts`) on the Bot Module Worker's V8 executor. The input is `installId`, `functionName` and `args` (a JSON object, passed as the handler's `args`). The handler's category, its `editorOnly` flag and its code come from the functions manifest and `server.js` of the version the install runs, never from the request. `ExtensionHandlerResult.data` is the handler's return value (JSON).

- **Checks:** the callers of `extensionQuery` (an install whose code may not run - extension or version suspended, install disabled, account in its dissolution grace period - is `Not found: Extension install not found` and never reaches the worker); `extension-data:read` for a `query()` handler, `extension-data:edit` for `mutation()` / `action()` (sessions and API keys); `editorOnly` as above; the account's extension kill switch (`EXTENSIONS_KILLED`, `Extension handlers are switched off for this account`).
- **Limits:** 5 s and 256 MB per call, `ctx.fetch` refuses every host, per install and minute 100 `query()` (shared with `extensionQuery`), 50 `mutation()` and 20 `action()` calls (`RATE_LIMIT_EXCEEDED`, also when the worker's rate-limit Redis fails), at most 16 handlers per worker replica and 4 per account at a time (`RATE_LIMIT_EXCEEDED` at once when no slot is free).
- **Realtime:** the handler's `ctx.realtime.push` calls are validated and published exactly as on REST (32 per call, 16 KiB payload, topic charset, 300 per install and minute; a bad push throws inside the handler, and an invalid batch that still reaches the API is dropped while the call succeeds) and reach the WebSocket channel `extension_install:{install_id}`. There is no GraphQL subscription for them; the WebSocket channel is the delivery path.
- **Errors:** `Bad request: Server function '{name}' is not a handler; call it through query or mutate`; `Not found: Unknown server function: {name}`; `Not found: The installed version has no server bundle`; `Not found: Extension install not found`; `HANDLER_ERROR` (the first line of the message the handler threw, without its stack trace; `Handler execution failed` for a failure outside the handler's code, whose text never reaches the caller), `HANDLER_MEMORY_LIMIT`, `HANDLER_TIMEOUT`; `EXECUTOR_UNAVAILABLE` (`Server-function executor is unavailable; try again later`) when the worker is not configured, unreachable or failing.

> **Protocol parity:** REST twin `POST /v1/extension-installs/{install_id}/execute/{function_name}` with the same checks, messages and codes -- both protocols call `services::extension_functions::prepare_handler_call` and `services::server_function_executor`. See [REST API](./rest-api.md#post-v1extension-installsinstall_idexecutefunction_name).

## Automation Extension Nodes

Queries for managing extension-provided automation nodes.

### Queries

#### `installedAutomationNodes: [InstalledAutomationNode!]!`

List all installed automation node extensions for the current account. Returns metadata for each node including schemas, trigger mode, icon, and color. Requires `automations:read`.

#### `automationWebhookUrl(installId: UUID!, automationId: UUID!): AutomationWebhookUrl!`

Get the webhook URL and secret for an installed trigger node within a specific automation. Requires `automations:read`.

### Types

#### `InstalledAutomationNode`

| Field | Type | Description |
|-------|------|-------------|
| `installId` | `UUID!` | Install ID |
| `extensionId` | `UUID!` | Extension ID |
| `extensionName` | `String!` | Extension name |
| `extensionSlug` | `String!` | Extension slug |
| `nodeType` | `String!` | `"trigger"`, `"action"`, or `"logic"` |
| `inputSchema` | `JSON!` | JSON Schema for node input |
| `outputSchema` | `JSON!` | JSON Schema for node output |
| `triggerMode` | `String` | `"webhook"`, `"polling"`, or `"both"` (triggers only) |
| `pollIntervalSeconds` | `Int` | Poll interval for polling triggers |
| `icon` | `String` | Lucide icon name |
| `color` | `String` | Hex color for canvas rendering |

#### `AutomationWebhookUrl`

| Field | Type | Description |
|-------|------|-------------|
| `webhookUrl` | `String!` | Full webhook URL for the external service |
| `webhookSecret` | `String!` | 64-character hex secret for the `X-Webhook-Secret` header |

> **Protocol parity:** Both queries have matching REST endpoints -- see [REST API](./rest-api.md#automation-extension-nodes).

## Extension Storage

Per-install key/value storage behind `useExtensionStorage()`. Auth: the install's own extension token, or a member credential (user session, personal key, service key) of the owning account with the permission below. Overlay and widget tokens whose overlay or widget renders a runnable install may read it, never write it. Feature: `feature:extensions`. Errors (code and message) are identical to the REST twins.

### Queries

#### `extensionStorage(installId: UUID!): [ExtensionStorageEntry!]!`

All entries, ordered by key. Permission: `extension-store:read`, or an overlay/widget token that renders the install (`FORBIDDEN` `Extension install belongs to a different overlay` / `… widget` otherwise; a non-runnable install is `NOT_FOUND`). REST twin: `GET /v1/extension-installs/{install_id}/storage`.

### Mutations

#### `setExtensionStorage(input: SetExtensionStorageInput!): ExtensionStorageEntry!`

Set one key (`installId`, `key`, `value: JSON`) and broadcast `storage:update` on `ext-storage:{install_id}`. Permission: `extension-store:configure`. Overlay and widget tokens get `FORBIDDEN` `Overlay and widget tokens cannot write extension storage`. REST twin: `POST /v1/extension-installs/{install_id}/storage`.

Limits per install, checked on every write: key at most 256 bytes (UTF-8, not empty, no `:`; surrounding whitespace is trimmed), value at most 64 KiB of JSON, at most 1 000 keys and 1 MiB in total (keys + JSON values). Overwriting an existing key with a smaller value is always allowed. A rejected write stores nothing (`code: BAD_REQUEST`).

### Types

#### `ExtensionStorageEntry`

| Field | Type | Description |
|-------|------|-------------|
| `key` | `String!` | Storage key |
| `value` | `JSON!` | Stored JSON value |

## Extension Actions

#### `executeExtensionAction(input: ExecuteExtensionActionInput!): ExtensionActionResult!`

Run an action (`chat:send`, `events:emit`, `overlay:update_layer`, the OBS actions, …) on behalf of an extension install - the backend of `useLumioAction()`. Input: `installId`, `action`, `params` (JSON object; anything else → `params must be a JSON object`). Result: `success`, `data`, `error`; a failure inside the action returns `success: false` with `error` instead of a GraphQL error. Unknown actions → `Unknown action: …`, bad params → `Invalid params: …`. REST twin: [`POST /v1/extension-installs/{install_id}/actions/{action}`](./rest-api.md#extension-actions).

**Auth** (identical on both protocols, one shared resolver):

| Credential | May act on |
|------------|-----------|
| Extension token (`lm_ext_*`) | Only its own install; any other id → `Extension token install_id does not match the requested install` |
| User session / personal API key | A live install of the caller's account, with `extension-store:configure` (`Missing permission: extension-store:configure`; another account's install → `Extension install belongs to a different account`; unknown or uninstalled → `Extension install not found`) |
| Overlay token (`lm_overlay_*`) | Only a live install of the token's account that an extension layer (`ext:{slug}`) of **that** overlay renders; anything else → `Extension install belongs to a different overlay` |
| Widget token (`lm_widget_*`) | Only the widget's own install; anything else → `Extension install belongs to a different widget` |
| Shared overlay link (`lm_share_*`), popout token, anything else | Never → `Authentication required` |

Overlay and widget tokens never run a `chat:*` action (`chat:send`, `chat:delete`, `chat:ban`, … and any future `chat:` action): their links are permanent and leak through stream captures and shared screenshots, and a chat action runs as the account's bot. Such a call is refused before the install is looked up with `Permission denied: chat actions require a signed-in session, not an overlay or widget token`. Spotify, OBS and the other actions stay available to them. Chat actions need a user session, an API key or the extension token.

The extension identity is always read from the token or the install row, never from the request. The install's manifest must then declare the permission the action needs (`Permission denied: Extension does not declare the required permission: …`). Feature: `feature:extensions`. Actions run on behalf of the install and emit no audit event.

## Developer Extension Versions

`createExtensionVersion(extensionId: UUID!, input: CreateVersionInput!)` creates a draft version. `uploadExtensionVersion(input: UploadExtensionVersionInput!)` records a draft bundle version; the REST multipart upload is the CLI path. Both validate `lumio.config.json`, require the manifest extension ID to match the target extension, and require the input `version` to equal the manifest version. Both take an optional `dataSchema` (the `defineSchema` result) with the same validation as REST: `422 INVALID_DATA_SCHEMA`, or `DATA_SCHEMA_NOT_ADDITIVE` with the violation list in the `details` error extension. An invalid manifest returns a validation error; a mismatched version returns `Version '<input>' does not match the manifest version '<manifest>'`.

`UploadExtensionVersionInput` contains `extensionId`, `version`, `bundleHash`, `manifest`, and optional `isBreaking`, `releaseNotes`, and `changelogEntry`. It has no storage-key fields. The server derives the bundle and source keys from the extension ID and validated version.

`submitExtensionVersion(versionId: UUID!)` revalidates the stored manifest before a draft enters review. Invalid data leaves the version in draft. On a team-owned extension, create and upload require `team-versions:create`; submit requires `team-extensions:publish`. A member lacking the team grant receives `FORBIDDEN` with `Missing team permission: <permission>`. Ownership checks run first, so a caller outside the owning team receives a not-found error.

Create and update accept developer visibility values `private`, `unlisted`, `public`, and `paid`; `system` is reserved. Developer slugs beginning with `system-` are rejected. `installExtension` requires a published extension; a private extension additionally requires an account access grant or tester invitation. Ineligible install targets return `Extension not found`; installing an extension the account already has returns `Extension is already installed`. After `uninstallExtension` the install disappears from every query and per-install resolver at once. `deleteDataImmediately: true` deletes the account's extension data at once instead of after 30 days; like the retention path it removes only this account's rows from the shared `ext_{extension_id}` schema and drops the schema only with the extension's last install. Both protocols emit `account:extension_uninstalled`. installing it again within the 30-day data-retention window restores it with its saved configuration (REST parity: `POST`/`DELETE /v1/extension-installs`). `reviewExtension` accepts only store-visible targets (published or deprecated, excluding private).

> **Protocol parity:** The REST developer version endpoints and install route apply the same manifest, team-role, visibility, and install checks. See [REST API](./rest-api.md#developer-extension-endpoints).

## Extension Version Files

### Queries

#### `extensionVersionFiles(extensionId: UUID!, version: String!): [ExtensionVersionFile!]!`

List all files in an extension version's bundle. Published versions are publicly accessible; draft and testing versions are restricted to the extension's own developer/team members (or a System key carrying `bots:internal`; a System key without it gets `Missing permission: bots:internal`) - an authenticated user from another account cannot enumerate them. The REST twin `GET /v1/extensions/{id}/versions/{version}/files` enforces the same ownership check.

```graphql
query {
  extensionVersionFiles(extensionId: "uuid", version: "1.2.0") {
    id
    versionId
    filePath
    contentType
    sizeBytes
    contentHash
    createdAt
  }
}
```

### Types

#### `ExtensionVersionFile`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | File record ID |
| `versionId` | `UUID!` | Parent version ID |
| `filePath` | `String!` | Path within the bundle (e.g. `layer.js`, `assets/logo.png`) |
| `contentType` | `String!` | MIME type (e.g. `application/javascript`, `text/css`) |
| `sizeBytes` | `Int!` | File size in bytes |
| `contentHash` | `String` | SHA-256 content hash |
| `createdAt` | `DateTime!` | Upload timestamp |

> **Protocol parity:** `GET /v1/extensions/{id}/versions/{version}/files` in REST -- see [REST API](./rest-api.md#extension-bundle-serving).

## Platform Metadata

### Queries

#### `platformMetadata: [PlatformMetadata!]!`

Returns static platform info (name, slug, icon, features, OAuth scopes). Public query -- no authentication required.

```graphql
query {
  platformMetadata {
    name
    slug
    icon
    features
    oauthScopes
  }
}
```

### Types

#### `PlatformMetadata`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `String!` | Platform display name |
| `slug` | `String!` | Platform slug (e.g. `twitch`, `youtube`) |
| `icon` | `String!` | Platform icon identifier |
| `hasLogin` | `Boolean!` | Platform can be used to sign in |
| `hasChannel` | `Boolean!` | Platform supports a channel connection |
| `hasBot` | `Boolean!` | Platform supports a custom bot identity |
| `hasIntegration` | `Boolean!` | Platform exposes a non-channel integration |

## Sounds

All sound operations require the `feature:sounds` feature flag to be enabled for the account.

### Queries

#### `sounds(offset: Int! = 0, limit: Int! = 20, search: String): SoundsResult!`

List sounds in the account's library with optional pagination and name search.

**Permission:** `sounds:read`

```graphql
query {
  sounds(limit: 20, offset: 0, search: "tada") {
    items {
      id
      name
      fileName
      contentType
      sizeBytes
      durationSecs
      createdAt
    }
    total
  }
}
```

#### `sound(id: UUID!): SoundGql`

Fetch a single sound by ID.

**Permission:** `sounds:read`

### Mutations

#### `updateSound(id: UUID!, input: UpdateSoundInput!): SoundGql`

Update the metadata of an existing sound.

**Permission:** `sounds:edit`

```graphql
mutation {
  updateSound(id: "uuid", input: { name: "Fanfare" }) {
    id
    name
    updatedAt
  }
}
```

#### `deleteSound(id: UUID!): Boolean!`

Delete a sound from the library. Returns `true` on success.

**Permission:** `sounds:delete`

#### `playSound(id: UUID!, volume: Float! = 1.0, target: SoundTargetInput): Boolean!`

Trigger playback of a sound in browser sources. `volume` is 0.0–1.0 (default 1.0). `target` is an optional overlay key; omit to broadcast to all browser sources.

**Permission:** `sounds:play`

#### `stopSound(id: UUID!, target: SoundTargetInput): Boolean!`

Stop playback of a sound in browser sources. `target` is an optional overlay key; omit to broadcast to all browser sources.

**Permission:** `sounds:play`

### Types

#### `SoundGql`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Sound ID |
| `accountId` | `UUID!` | Owning account |
| `name` | `String!` | Display name |
| `filename` | `String!` | Original file name |
| `contentType` | `String!` | MIME type (e.g. `audio/mpeg`) |
| `sizeBytes` | `Int!` | File size in bytes |
| `durationMs` | `Int` | Duration in milliseconds (null until processed) |
| `waveform` | `JSON` | Precomputed waveform peaks (null until processed) |
| `createdAt` | `String!` | Upload timestamp |
| `sourceExtensionName` | `String` | Extension that bundled this sound, when applicable |

#### `SoundsResult`

| Field | Type | Description |
|-------|------|-------------|
| `sounds` | `[SoundGql!]!` | Sound list for the current page |
| `totalCount` | `Int!` | Total count matching the query |
| `userSoundCount` | `Int!` | Sounds uploaded by the account (excludes extension-bundled) |
| `maxSounds` | `Int!` | Plan limit on sound count |
| `maxSoundFileSize` | `Int!` | Plan limit on a single upload, in bytes |
| `maxSoundStorageBytes` | `Int!` | Plan limit on total storage, in bytes |
| `usedStorageBytes` | `Int!` | Storage currently used, in bytes |

#### `UpdateSoundInput`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `String` | New display name |
| `durationMs` | `Int` | Duration in milliseconds |
| `waveform` | `JSON` | Waveform peaks |

#### `SoundTargetInput`

Passed to `playSound` / `stopSound` to address a single browser source instead of every listener.

| Field | Type | Description |
|-------|------|-------------|
| `type` | `String!` | Target kind (e.g. `"overlay"`, `"widget"`) |
| `id` | `UUID!` | Target ID |

> **Protocol parity:** All operations have matching REST endpoints - see [REST API](./rest-api.md#sounds).

## Widgets

Account-scoped queries and mutations for widget instances, access management and duplication.

### Queries

#### `widgetInstances: [WidgetInstanceGql!]!`

List the widget instances of the active account.

**Permission:** `widgets:read`

A widget on which the caller has the role `none` is left out; no entry, `viewer` or `editor` is listed. `widgets:access-read` sees every widget. Same rule as REST `GET /v1/widgets` and the `overlays` query.

#### `widgetAccess(widgetId: UUID!): [WidgetAccessEntry!]!`

List access entries for a widget. Returns all users with explicit access grants.

**Permission:** `widgets:access-read`

#### `widgetAccessCandidates(widgetId: UUID!): [WidgetAccessCandidate!]!`

List account members eligible for the widget access dialog. Excludes users who already have an access entry.

**Permission:** `widgets:access-read`

### Mutations

#### `setWidgetAccess(widgetId: UUID!, userId: UUID!, role: String!): WidgetAccessEntry!`

Set a user's access role on a widget. `role` accepts `"viewer"`, `"editor"`, or `"none"`.

**Permission:** `widgets:access-grant`

#### `removeWidgetAccess(widgetId: UUID!, userId: UUID!): WidgetDeleteResult!`

Remove a user's access entry from a widget.

**Permission:** `widgets:access-revoke`

#### `duplicateWidgetInstance(id: UUID!): CreateWidgetResult!`

Duplicate a widget instance. Creates a copy of the widget with its configuration and returns the new widget with an access token.

**Permission:** `widgets:create`, plus **Editor** access on the source widget; `widgets:access-grant` bypasses the per-widget check, `widgets:access-read` does not. A source the caller cannot edit returns `Widget not found`, the same as a missing one. The plan limit is checked inside the insert. A source bound to an install that is no longer live returns `Extension install not found`. Errors match REST `POST /v1/widgets/{id}/duplicate`.

#### `createWidgetInstance(input: CreateWidgetInput!): CreateWidgetResult!`

Create a widget instance with a one-time access token.

**Permission:** `widgets:create`

The stored `extensionId` comes from the install, never from the input. `installId` must be a live install of the active account; otherwise `Extension install not found`. An `extensionId` or `widgetType` naming a different extension returns `Widget extension does not match the install`; an `extensionId` or `ext:` `widgetType` without `installId` returns `An extension widget requires an install_id`. Errors match REST `POST /v1/widgets`.

### Types

#### `WidgetExtensionRef`

`WidgetInstanceGql.extension` - set for an extension widget, `null` otherwise. Describes the extension and its newest published version; the dashboard widget editor and the designer opened from it read it. REST returns the same object as `extension` on every widget response.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Extension ID |
| `slug` | `String!` | Extension slug |
| `name` | `String!` | Display name |
| `visibility` | `String!` | Store visibility |
| `iconKey` | `String` | Icon storage key |
| `developerName` | `String` | Developer display name (`Lumio` for system extensions) |
| `version` | `String` | Newest published version |
| `targets` | `JSON` | `targets` of that version's manifest |
| `configSchema` | `JSON` | `config_schema` of that version's manifest |
| `designerSchema` | `JSON` | `designer_schema` of that version's manifest |
| `permissions` | `[String!]!` | `permissions` of that version's manifest (`events:read`, `chat:read`, ...). The host forwards live events and chat only for declared permissions; `[]` when it declares none. See [WebSocket → Extension hosts](./websocket.md#extension-hosts-read-events-and-chat) |

#### `WidgetAccessEntry`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Access-entry ID |
| `widgetId` | `UUID!` | Widget instance the grant applies to |
| `userId` | `UUID!` | User ID |
| `userName` | `String!` | User display name |
| `userAvatar` | `String` | User avatar URL |
| `role` | `String!` | Access role (`"viewer"`, `"editor"`) |
| `grantedBy` | `UUID` | User who granted access; `null` once that profile is deleted |
| `createdAt` | `String!` | When access was granted |

#### `WidgetAccessCandidate`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | User ID |
| `displayName` | `String!` | User display name |
| `avatarUrl` | `String` | User avatar URL |

> **Protocol parity:** All queries and mutations have matching REST endpoints - see [REST API](./rest-api.md#widgets).

## Setting Presets

Named snapshots of chat/events/music display settings, keyed to the pair `(user, account)` (ZAF-622 §52c; see [Setting Presets](../features/setting-presets.md)). All fields require the `feature:setting_presets` feature flag. Create/edit/delete are scoped to *(the authenticated user, their active account)* with no `resource:action` permission and fail-closed on membership (a preset in an account you have left reads as missing); the **one** RBAC gate is `presets:share` on the share/un-share mutations.

**Popout access:** the queries accept a **popout token** (the OBS-source popout can list/load presets). The mutations require a **first-party user session** - a popout/overlay/widget/extension token is rejected with `FORBIDDEN` (a popout token authenticates as the member it is bound to, not as the person holding it; ZAF-450/469). The quota is one number over all kinds, resolved **per account** from that account's own plan (plus any override; `0 = unlimited`) - a full account never blocks a different one. The effective limit is also readable without creating a preset - as `maxSettingPresets` on the `accountLimits` query and its REST twin `GET /v1/billing/account-limits` (both gated on `plan:read`) - so a UI can render "N of M used".

**Account sharing (ZAF-622 §19):** a user can share one of their own presets with the members of their active account. For a **first-party** caller, `settingPresets` then also returns presets shared into the active account by a still-member owner - each marked `shared: true` with `ownerDisplayName`. Over a **popout token the list stays restricted to your own presets**. Sharing is a flag on the existing row (no copy, no quota cost); loading writes nothing server-side.

### Queries

#### `settingPresets(kind: SettingPresetKind): [SettingPresetGql!]!`

List the current user's presets, optionally filtered by `kind`, plus (for a first-party caller) presets shared into the active account by a still-member owner. Own rows sort first (default-first, then most-recently-changed) with `shared: false`; foreign shared rows follow with `shared: true` + `ownerDisplayName`. A popout token sees own presets only.

#### `settingPreset(id: UUID!): SettingPresetGql`

Get a single preset by ID (scoped to the current user + active account); `null` if missing, foreign, in another account, or in an account you have left.

#### `settingPresetQuota: SettingPresetQuotaGql!`

Your own preset quota in the active account: `used` (own presets across all kinds - foreign shared rows never count) and `limit` (the account's resolved cap, `0` = unlimited). Per-account and popout-token readable like the list, deliberately **not** gated on `plan:read`, so every member sees their limit. Both numbers come from the functions the create path gates on, so this read and the create rejection can never disagree. REST twin `GET /v1/setting-presets/quota`.

### Mutations

#### `createSettingPreset(input: CreateSettingPresetInput!): SettingPresetGql!`

Create a preset. First-party session only. Fails with a limit message when the user is at their preset quota.

#### `updateSettingPreset(id: UUID!, input: UpdateSettingPresetInput!): SettingPresetGql!`

Rename and/or overwrite a preset (moves `updatedAt`). First-party session only.

#### `setDefaultSettingPreset(id: UUID!): SettingPresetGql!`

Mark the preset as its kind's default (unsets the previous default of that kind). First-party session only.

#### `deleteSettingPreset(id: UUID!): Boolean!`

Hard-delete a preset. First-party session only.

#### `shareSettingPreset(id: UUID!): SettingPresetGql!`

Share one of your own presets with the members of your active account. First-party session + `presets:share`. The target is always the active account; a second share re-points the same row (no copy, no quota cost). Fails `FORBIDDEN` with `Missing permission: presets:share` without the permission, `Setting preset not found` if the preset is missing or not owned by the caller. Emits `account:setting_preset_shared`.

#### `unshareSettingPreset(id: UUID!): SettingPresetGql!`

Un-share one of your own presets (make it private again). First-party session + `presets:share`. Idempotent - un-sharing an already-private preset succeeds and emits no event; otherwise emits `account:setting_preset_unshared`.

### Operator (AdminApp) queries & mutations

Platform operators view and delete a user's presets from the AdminApp (ZAF-1282). An operator manages presets by owning user and sees **all** of that user's presets across every account; deleting one removes that single `(user, account)` row (a preset lives in exactly one account). These use the same admin RBAC as the rest of the admin surface.

#### `adminUserSettingPresets(userId: UUID!): [AdminSettingPreset!]!`

List a user's presets for the operator view. Requires `users:read`. The `payload` is **not** exposed (it can hold viewer names the user typed). REST twin `GET /v1/admin/users/{id}/setting-presets`.

#### `adminDeleteUserSettingPreset(id: UUID!): Boolean!`

Delete one of a user's presets. Requires `users:edit`. Returns `false` if no such preset exists. Emits `system:user_setting_preset_deleted`. REST twin `DELETE /v1/admin/setting-presets/{id}`.

#### `AdminSettingPreset`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Preset ID |
| `userId` | `UUID!` | Owning user |
| `kind` | `String!` | `chat` \| `events` \| `music` |
| `name` | `String!` | Display name |
| `isDefault` | `Boolean!` | Whether this is the kind's default |
| `createdAt` | `DateTime!` | Creation timestamp |
| `updatedAt` | `DateTime!` | Last-changed timestamp |

### Types

#### `SettingPresetKind`

Enum: `chat`, `events`, `music`.

#### `SettingPresetGql`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID!` | Preset ID |
| `userId` | `UUID!` | Owning user |
| `kind` | `String!` | `chat` \| `events` \| `music` |
| `name` | `String!` | Display name |
| `payload` | `JSON!` | The settings snapshot (ZAF-622 export format) |
| `isDefault` | `Boolean!` | Whether this is the kind's default |
| `sharedAccountId` | `UUID` | The account this preset is shared with, or `null` when private |
| `shared` | `Boolean!` | `true` when this is a foreign preset shared into your active account (own rows are `false`) |
| `ownerDisplayName` | `String` | The owner's display name - only for foreign shared rows |
| `createdAt` | `DateTime!` | Creation timestamp |
| `updatedAt` | `DateTime!` | Last-changed timestamp |

#### `CreateSettingPresetInput`

| Field | Type | Description |
|-------|------|-------------|
| `kind` | `SettingPresetKind!` | The preset kind |
| `name` | `String!` | Display name (non-empty, ≤ 255) |
| `payload` | `JSON!` | The settings snapshot |
| `isDefault` | `Boolean` | Mark as this kind's default |

#### `UpdateSettingPresetInput`

| Field | Type | Description |
|-------|------|-------------|
| `name` | `String` | New name (rename) |
| `payload` | `JSON` | New snapshot (overwrite) |

> **Protocol parity:** All queries and mutations have matching REST endpoints - see [REST API](./rest-api.md#setting-presets).

## Popout Tokens

Create, update, and revoke the long-lived popout/API tokens (`lm_pop_*`) used by overlays and embedded browser sources. See [Tokens](../features/tokens.md) for the full model, permissions, and REST twins.

### Mutations

#### `createPopoutToken(input: CreatePopoutTokenInput!): CreatePopoutTokenResult!`

Requires `tokens:create` (and the `feature:tokens` flag). Returns the full token string (shown only once) plus the token metadata. Binds to the **creator** (the acting first-party user) when `userId` is omitted.

> **First-party session required (ZAF-1017 / ZAF-469):** minting a popout token is itself a first-party action - the omitted-`userId` (NULL) binding keys off the *creator*. A popout token is always bound to an explicit user; there is no fallback to the account owner, and an unbound token never resolves (ZAF-1922). A popout/overlay/widget/extension token calling `createPopoutToken` is rejected with `FORBIDDEN`. Passing an explicit `userId` for another account member is allowed only for a member of the account whose role does not exceed the caller's own permissions (ZAF-1740 A1) - the account owner counts as holding every account permission. The same binding rule applies when `updatePopoutToken` reassigns `userId`. Same gate, rule and messages as REST `POST /v1/tokens` / `PATCH /v1/tokens/{id}`.

**`CreatePopoutTokenInput`**

| Field | Type | Description |
|-------|------|-------------|
| `label` | `String` | Human-readable label. |
| `permissions` | `[String!]!` | Permission strings the token grants (must be a subset of the creator's rights). |
| `userId` | `UUID` | User to bind the token to (defaults to the authenticated user). |
| `expiresAt` | `String` | Optional lifetime (RFC3339). `null`/absent = never expires (the default). Must **not** be in the past - a back-dated value is rejected with code `VALIDATION_ERROR` and message `Validation error: expires_at cannot be in the past`, **identical to REST `POST /v1/tokens`**. Optional and additive. |

#### `updatePopoutToken(input: UpdatePopoutTokenInput!): PopoutToken!`

Requires `tokens:edit`. `label` and `expiresAt` distinguish absent (don't change) from an explicit `null` (clear) and a value (set) - the same meaning as `"label": null` / `"expires_at": null` on REST `PATCH /v1/tokens/{id}` - plus a `revoke` boolean. `userId` distinguishes absent (no change) from an explicit `null`, which unassigns by binding the token to the **editor** - the editor must be a first-party user (a token-authenticated editor gets `FORBIDDEN` `This endpoint requires a logged-in user session`), and the resulting binding passes the same binding check as an explicit `userId` (ZAF-1922). REST twin: `PATCH /v1/tokens/{id}` with `"user_id": null`. Unlike create, the update path **allows** a back-dated `expiresAt` - that is a supported soft-revoke.

> **Protocol parity:** matching REST endpoints under `/v1/tokens` - see [REST API](./rest-api.md#endpoints-overview). GraphQL and REST share the same fields, permissions, validation, and error messages.

## Popout Sessions

Exchange a raw popout token (`lm_pop_*`) for a short-lived **popout session** so the raw token stays out of the page URL. See [Authentication → Popout Tokens & Popout Sessions](./authentication.md#popout-tokens--popout-sessions) for the full model.

### Queries

#### `popoutSession: PopoutSessionIdentity!`

Read the `(accountId, userId)` pair the current popout session represents, plus the represented user's display preferences (`locale`, `timezone`, `dateFormat`, `timeFormat`) and seasonal-look preferences (`season*`). Popout-token readable — gated with `AuthGuard`, **not** the first-party gate (a popout carries no logged-in user session). The pair is read straight from the auth context, never a client parameter, so the scope cannot be forged, and the response is only the caller's **own** session ids — never a list, never another account. Anonymous is rejected with `Authentication required`.

The popout-session cookie is httpOnly, so the popout page cannot read this pair itself; this query is how it learns which account and user it acts as. `userId` is always the user the token is bound to — every popout token is bound to an explicit user, there is no owner fallback (ZAF-1922) — the same binding every popout read uses. No permission guard and no audit event (a read of the caller's own session).

> **Protocol parity:** matching REST endpoint `GET /v1/auth/popout/session` — see [REST API](./rest-api.md#auth).

### Mutations

#### `exchangePopoutToken(token: String!): PopoutSession!`

Validates the popout token (prefix + `revoked_at` / `expires_at`), mints a 15-minute session JWT carrying the token's permission subset, and sets it as an httpOnly cookie (`lumio-popout-token`, `Path=/`, `SameSite=Lax`). No permission guard - possession of a valid popout token IS the authorization. A revoked, expired, unknown, or non-popout token is rejected with `Invalid or expired popout token`.

The minted session resolves to the **same** popout auth context as the raw token (identical account, permission subset, OBS credential gate) - never a full user session.

#### `issuePopoutWsToken: String!`

Mint a **WebSocket-scoped** token for the current **popout session** - the popout counterpart of `issueWsToken`. `issueWsToken` is session-only (ZAF-469 / ZAF-1742) and returns `FORBIDDEN` for a popout, so a popout cannot mint there; this path mints a WS token that carries the popout's **own** permission subset (never the account owner's). No permission guard - possession of a valid popout session IS the authorization; a non-popout caller is rejected with `UNAUTHENTICATED` (anonymous) or `FORBIDDEN` (any non-popout credential).

The token carries a WebSocket-only use tag and **no `session_id`**, so the API accepts it **only** on the `/v1/ws` upgrade path - a leaked `?token=` WS URL cannot drive a REST/GraphQL mutation. It is short-lived (`auth.ws_token_expiration`, ~15 min); the popout re-mints on reconnect.

> **Protocol parity:** matching REST endpoint `POST /v1/auth/popout/ws-token` - see [REST API](./rest-api.md#auth).

#### `popoutDismissSeasonBanner(instance: String!): PopoutSeasonLook!`

Dismiss the season banner for one season instance (`<seasonId>:<year>`, e.g. `halloween:2026`) on behalf of the current **popout session**. One of exactly two one-way profile writes a popout may make: it appends `instance` to the represented user's `seasonBannerDismissed` and changes nothing else. Idempotent (a present instance is a no-op); the same dedupe and 50-entry cap as `updateMe` apply (a full list drops its oldest entry).

**Guard:** popout-only - anonymous → `UNAUTHORIZED` (`Authentication required`), every other credential (user session, API key, overlay, shared-overlay, widget, extension) → `FORBIDDEN` (`This endpoint requires a popout session`). A logged-in user uses `updateMe`. **Validation:** the season id must be in the server-side `SEASON_IDS` list (`halloween`, `nicholas`, `christmas`, `new-year`, `easter` - every season of the web season registry plus the planned ones; a season outside it extends both) and the year within ±1 of the current one; otherwise `VALIDATION_ERROR` with the same text as the REST twin. No audit event, no WebSocket push.

> **Protocol parity:** matching REST endpoint `POST /v1/auth/popout/season-banner/dismiss` - see [REST API](./rest-api.md#auth).

#### `popoutSwitchOffSeasonLook(instance: String!): PopoutSeasonLook!`

Switch the seasonal look **off** on behalf of the current **popout session**: sets the represented user's global `seasonLookEnabled = false` (all seasons - the same switch as the Settings toggle) and, in the same write, dismisses the banner for `instance`, so switching the look on again later does not bring this season's banner back. **Off only** - no popout mutation can switch the look on or change `seasonStrength`, `seasonMotion` or `seasonCreatures`; that stays in dashboard Settings (`updateMe`). Same guard, validation and errors as `popoutDismissSeasonBanner`; idempotent. No audit event, no WebSocket push.

> **Protocol parity:** matching REST endpoint `POST /v1/auth/popout/season-look/off` - see [REST API](./rest-api.md#auth).

### Types

#### `PopoutSeasonLook`

The represented user's seasonal-look state after a popout write (`popoutDismissSeasonBanner` / `popoutSwitchOffSeasonLook`).

| Field | Type | Description |
|-------|------|-------------|
| `seasonLookEnabled` | `Boolean!` | Global seasonal-look switch (all seasons). |
| `seasonBannerDismissed` | `[String!]!` | Dismissed season banners as `<seasonId>:<year>`, oldest first (≤ 50). |

> **Protocol parity:** REST twin `PopoutSeasonLookResponse` (snake_case fields) - see [REST API](./rest-api.md#auth).

#### `PopoutSession`

| Field | Type | Description |
|-------|------|-------------|
| `token` | `String!` | The popout-session JWT (`lm_...`). Store as an httpOnly cookie. |
| `expiresAt` | `DateTime!` | Absolute expiry (`now + 15 min`). |
| `accountId` | `UUID!` | Account the session is scoped to. |

> **Protocol parity:** matching REST endpoint `POST /v1/auth/popout/exchange` - see [REST API](./rest-api.md#auth).

#### `PopoutSessionIdentity`

The `(accountId, userId)` pair the current popout session represents, plus the represented user's display preferences (`popoutSession` query).

| Field | Type | Description |
|-------|------|-------------|
| `accountId` | `UUID!` | The Lumio account (`accounts.id`, `me.activeAccountId`) the session is scoped to — the "channel account", not a single platform connection. |
| `userId` | `UUID!` | The user whose settings the session represents: the user the popout token is bound to. |
| `locale` | `String!` | UI language preference of `userId`: `auto` · `en` · `de`. |
| `timezone` | `String!` | Timezone preference of `userId`: `auto` or an IANA name. |
| `dateFormat` | `String!` | Date-format preset of `userId`: `auto` · `dmy_dot` · `dmy_slash` · `mdy_slash` · `ymd_dash`. |
| `timeFormat` | `String!` | Time-format preset of `userId`: `auto` · `h12` · `h24`. |
| `seasonLookEnabled` | `Boolean!` | Seasonal look on/off of `userId`. |
| `seasonStrength` | `String!` | `full` · `subtle`. |
| `seasonMotion` | `String!` | `auto` · `off`. |
| `seasonCreatures` | `JSON!` | `{ "<creature>": Boolean }` overrides; absent key = registry default. |
| `seasonBannerDismissed` | `[String!]!` | Dismissed season banners as `<seasonId>:<year>`, oldest first. |
| `motionPreference` | `String!` | "Animations in Lumio" of `userId`: `system` · `reduced` · `off`. |

The preference fields let a popout - which cannot reach the first-party-gated `me` - render language, timezone, date/time format, the seasonal look and the motion preference. They are written via `updateMe`; a popout session's only two writes are the one-way `popoutDismissSeasonBanner` / `popoutSwitchOffSeasonLook` mutations. None of them is a secret.

> **Protocol parity:** matching REST endpoint `GET /v1/auth/popout/session` - see [REST API](./rest-api.md#auth).

## Account Bots

The active account's bot list supports Twitch, Kick and YouTube. Reads use `chat-bots:read`; writes use `chat-bots:edit`. These account-scoped `PermissionGuard` checks match the [REST endpoints](./rest-api.md#account-bots). Automatic recognition from bot badges, Lumio's curated list and the account's own bot connections is read only.

| Operation | Result |
|-----------|--------|
| `accountBots` | `[AccountBot!]!`, newest first. Each entry has `platform`, `platformUserId`, `login`, `displayName`, `source`, `addedBy`, `addedByName`, `addedAt`. |
| `autoDetectedBots` | `[AutoDetectedBot!]!` with `platform`, `source` (`badge`, `known`, `own_connection`), `identity`, `name`. |
| `addAccountBot(input: AddAccountBotInput!)` | `{ bot, created }`; supply `platform` and exactly one of `platformUserId` or `name`. A name or `@handle` must resolve on its platform before saving. An existing entry returns `created: false`. A real add starts background recalculation of retained sessions. |
| `removeAccountBot(platform: String!, platformUserId: String!)` | `Boolean!`; `false` when the entry did not exist. Removal does not restore already recalculated history figures. |

A real list change emits `account:bot_list_updated`. The REST twin uses snake_case fields.

## Stream History

All account operations require `feature:stream_history`. The GraphQL endpoint is `POST /v1/gql`; structured operations have REST twins under `/v1/history`. The filtered-list file download is intentionally REST-only.

### Queries

| Query | Permission | Result |
|-------|------------|--------|
| `channelHistory(page, perPage, from, to, sessionType, platform, platforms, search, category, sortBy, sortDir, currency)` | `history:read` | Paged sessions (25 by default, max 100). `viewerSparkline`, `milestones` and `platformStats` are filled when selected under `sessions`; `estimatedRevenue` is filled only when selected and allowed. |
| `channelHistoryOverview(from, to, sessionType, platform, platforms, category, search, timeZone, currency, range)` | `history:read` | Totals, platforms, month totals, 371-day activity buckets, optional KPI range and newest session. `timeZone` is an IANA zone (UTC default); invalid names give `BAD_REQUEST`. `days` ignores `from`/`to` but applies other filters. Revenue fields require `history:revenue-read`. |
| `channelHistoryMilestones(from, to, platforms)` | `history:read` | Up to 1,000 persisted milestones, oldest first; `from` inclusive and `to` exclusive. `platforms` keeps only those platforms' follower marks; the cross-platform records stay. Invalid reversed bounds or an unknown platform give `BAD_REQUEST`. |
| `channelHistoryFilterOptions` | `history:read` | Distinct platforms and categories present in this account. |
| `channelHistoryReport(id, currency)` | `history:read` | Session, streams, chart markers, `adBreaks`, `adStats`, and top lists (`topEmotes` up to 20, `topChatters`/`topGifs` up to 10). Each stream carries `tags: [String!]!`, `categoryChanges: [HistoryCategoryChange!]!` (`at`, `category`, `categoryId`) and `titleChanges: [HistoryTitleChange!]!` (`at`, `title`); the first entry is the state at stream start, YouTube returns empty lists, and the timeline is frozen at finalize. A Twitch stream with a Shared Chat also has `sharedViewersPeak` / `sharedViewersAvg` (per-bucket total of own + partners), `sharedChatSources` (JSON, snake_case keys) and `sharedChatTimeline` / `sharedChatInsights` (JSON). The timeline is event-exact and frozen at finalize; older streams fall back to minute samples. Partner insights hold term and count, without viewer identities. `session.estimatedRevenue` is `null` without revenue-read permission. `session.displayMoney` (`currency`, `donationsCents`, `superchatsCents`, `superstickersCents`, `rateDate`) converts donations, Super Chats and Super Stickers into `currency` under `history:read`; an amount without a rate is `null`. |
| `channelHistoryRevenueSettings` | `history:revenue-read` | Saved assumptions or defaults, `youtubeMemberLevels`, read-only USD `fixedValues`; `updatedAt` and `updatedBy` are `null` until saved. |
| `channelHistoryYoutubeRevenueStatus` | `history:revenue-read` | Account-level YouTube Analytics state without amounts: `connected`, `status`, `yppCheckedAt`, `revenueAuthVerifiedAt`. Requires `feature:stream_history`; REST twin: `GET /v1/history/youtube-revenue/status`. |
| `channelHistoryYoutubeMemberLevelSuggestions` | `history:revenue-read` | Up to 50 level names seen in retained YouTube membership events, most frequent first: `name`, `events`, `lastSeenAt`, `entered`. Requires `feature:stream_history`. |
| `channelHistoryStats(sessionId, platform)` | `history:read` | Time-series samples, optionally for one platform. Each sample may carry `liveCounters`; older samples return `null`. A Twitch sample during a Shared Chat carries `sharedViewers` (own + partners in that bucket, else `null`) and `sharedChatViewers: [HistorySharedChatViewers!]!` (`platformChannelId`, `viewerCount`; `[]` outside a Shared Chat, a missing partner was not in it, `viewerCount: null` = not live). |
| `automodLog(sessionId, outcome, after, first)` | `history:read` **and** `chat:automod-read` | `AutomodLogPage` or `null`: the messages Twitch AutoMod held during the session, oldest first. `null` means unavailable (no Twitch broadcast in the session, or the session started before the chat retention window). `textRetentionDays` is the account's effective chat window: the entry, text included, is deleted that many days after the hold. `entries` carry `messageId`, `sender { userId login displayName avatarUrl color badges }` (look at hold time, `null` = unknown), `text` and `flaggedSpans` (code points, `end` inclusive), `emotes` (JSON, the `ChatMessage.emotes` shape: Twitch emotes and cheermotes; `null` when none; an unknown cheer stays plain text), `textState` (`stored`, or `not_stored` above the 4 KiB size cap), `reasonKind` + `reason { category level terms { termId text } }`, `outcome` (`open`, `approved`, `denied`, `expired`), `resolvedVia` (`lumio`/`twitch`), `moderatorLogin`, `moderatorName`, `heldAt`, `resolvedAt`. A hold nobody decided reads `expired` after the queue TTL, with no moderator and no `resolvedAt`. `counts { total open approved denied expired }` cover the whole session regardless of `outcome`. `first` is 1–100 (default 50); pass `nextCursor` as `after`. Popout tokens are refused. Never part of the report, share links or exports. Requires `feature:stream_history`; REST twin: `GET /v1/history/reports/{id}/automod`. |
| `historySharedLinks(sessionId)` | `history:share` | Links, options, active state and expiry; never the full token. |
| `historyKeywords` | `history:read` | `HistoryKeywordList!` with `keywords`, `lastSessionId`, `lastSessionStartedAt` and `maxKeywords` (50). Each entry includes `lastStreamCount`, which is `null` when unknown. |
| `testHistoryKeywordPattern(pattern, match, caseInsensitive, sample)` | `history:read` | `{ valid, error, matches { start end text } }` without saving. A sample has at most 500 characters; offsets use UTF-16. At most 30 calls per minute per caller. |

For an unfinalized session started within the last 48 hours,
`HistorySessionSummary.live: HistoryLiveOverlay` describes running values on
`channelHistory.sessions`, `channelHistoryReport.session`, public shares and
`channelHistoryOverview.latestSession.session`. It has `computedAt`, nullable
`sampledAt`, `samples`, `chat`, `topChatters` and nullable
`youtubeSubscribers`. The state fields use `HistoryLiveValueState`: `LIVE`
means the figure is running, `UNAVAILABLE` means its numeric zero or empty
list must not be treated as a known value, and `AFTER_STREAM` marks YouTube
subscriber gain. `youtubeSubscribers` is `null` without YouTube. The whole
`live` field is `null` on finalized sessions and open sessions beyond the
48-hour overlay window. This session field is separate from
`latestSession.live`, the dashboard's sampled support and viewer snapshot.

The list filters are freely combinable. `from`/`to` bound `startedAt`; `sessionType` is `single` or `multi`; `search` matches session or stream titles case-insensitively; category matches either level. `sortBy` accepts `started_at`, `duration_secs`, `peak_viewers`, `avg_viewers`, `total_messages`, `unique_chatters`, `new_followers`, `new_paid_subs`, or `estimated_revenue`; `sortDir` is `asc` or `desc`. Nullable stats sort last; ties sort newest first. `estimated_revenue` orders by the revenue a row shows (the converted total in `currency`, else the raw estimate), computed over the whole filtered set before paging. Without `history:revenue-read` it is accepted but keeps the default order, so the order never reveals revenue. An invalid filter or reversed time range is rejected on both protocols.

With `range: "today" | "7d" | "30d"`, `channelHistoryOverview` fills `range { key from to previousFrom previousTo }`, `current` and `previous` (each `sessions totalDurationSecs avgViewers newFollowers messages newPaidSubs giftedSubs`), and daily `kpiSeries` with the same metrics plus `date`. The time bounds use local midnights in `timeZone`; `to` is the start of the next day. The existing totals and estimated revenue cover that range, while `days` remains 371 days. `range` together with `from` or `to` is rejected. `latestSession` ignores all overview filters and contains `session`, `viewerSeries { platform points { time viewers } }` (up to 60 points per platform), `live`, and `milestones`; it is computed only when selected and is `null` if there is no session.

**Platform filter (`platforms: [String!]`).** `channelHistory`, `channelHistoryOverview` and `channelHistoryMilestones` accept a list of `twitch`, `youtube` and `kick`. A missing or empty list means no filter. The list keeps every session with a broadcast on at least one selected platform. The overview also keeps only those sessions, but counts only the **share** of the selected platforms in its totals, `months`, `days`, `current`, `previous` and `kpiSeries`:

- A session whose every platform is selected keeps its own values, so selecting all platforms gives the unfiltered result.
- **Stream time** is the time at least one selected platform was live.
- **Ø viewers** is each selected platform's stream average weighted by that platform's live time, divided by the stream time. Platforms that ran at the same time add up. The KPI average then weights each session by this stream time.
- **Peak viewers** is the sum of the selected platforms' stream peaks.
- **Followers, messages, Subs + Members and gifted Subs** come from the selected platforms' `platformBreakdown` entries. YouTube followers are the rounded subscriber delta.
- A session or calendar day counts only when a selected platform streamed in it.
- `platforms` in the result lists only the selected platforms.
- `estimatedRevenue` and `months.revenue` cover the whole sessions that include a selected platform, not their share.

With `platforms`, `latestSession` is the newest session with a selected platform. `latestSession.viewerTotal: [HistoryViewerPoint!]!` is the combined viewer curve (≤ 60 `{ time viewers }` points on the `viewerSeries` bucket times): per bucket the highest per-minute sum across platforms, not the sum of the per-platform maxima. The session's `viewerSeries`, `viewerTotal`, `live` (viewers, peak, messages, followers, Subs and the per-platform list) and follower marks cover only the selected platforms; tips stay session-wide. The session summary stays whole. `viewerSparkline` on the list sums only the selected platforms. Combining `platforms` with `platform` and passing an unknown platform both give `BAD_REQUEST` with the same message as REST (`` `platforms` cannot be combined with `platform` ``, `` `platforms` must only contain: kick, twitch, youtube ``).

`HistorySessionSummary.sharedChat: HistorySessionSharedChat` is the Twitch Shared Chat marker of a list row; `null` means the session never ran Shared Chat. It has `hostBroadcasterId` (the host of the newest or running Shared Chat, `null` when unknown), `active` (a Shared Chat of the live session is running now), `channelCount` and `channels: [HistorySessionSharedChatChannel!]!` (`platformChannelId`, `login`, `displayName`, `avatarUrl`, `isHost`, `isOwnChannel`; host first, then the own channel, then join order). Sessions stored before the Shared Chat timeline list only the partner channels and have no host. `channelHistory` computes it only when selected, with at most two queries per page; it is `null` elsewhere. REST twin: `shared_chat` (`include=shared_chat`), same `history:read` guard.

`channelHistory` and `channelHistoryOverview` accept `sharedChat: String`
with `WITH` or `WITHOUT` (case-insensitive). It filters live and finalized
sessions, overview tiles, trend, heatmap and export. An invalid value has the
same bad-request message as REST `?shared_chat=`. Filter options expose
`hasSharedChat`; no extra permission applies beyond the history read guard.

`HistorySessionSummary.platformStats: [HistoryPlatformStats!]!` gives each platform's part of a session, in platform order: `platform`, `durationSecs` (the time it was live), `peakViewers`, `avgViewers`, `newFollowers`, `messages`, `paidSubs` and `giftedSubs`, with the same definitions as the filter for one platform. A single-platform session carries its own values. It is computed on `channelHistory` only when selected, always on `channelHistoryOverview.latestSession.session`, and is empty elsewhere. REST twin: `platform_stats` (`include=platform_stats`).

`latestSession.live` contains `sampledAt`, `currency`, `viewerCount`, `peakViewers`, `messagesTotal`, `chatPerMin`, `newFollowers`, `paidSubs`, `giftedSubs`, `bits`, `kicks`, `superchats`, `superstickers`, `tips`, and per-platform figures. Each money kind has `count`, `byCurrency` (JSON currency-to-cents map), `unknownCents`, and `convertedCents` in the requested display currency; conversion is `null` if any part lacks a currency or rate. Tips are session-wide. `HistoryStatSample.liveCounters` keeps gifted Subs, Bits, KICKs, Super Chats, Super Stickers and tips separately, with money kinds as `count`, `byCurrency` and `unknownCents`. `chatPerMin` uses the two latest samples; live figures begin at the first sample.

`latestSession.sharedChatSeries: HistorySharedChatSeries` has `total` (the
per-bucket highest concurrent sum of own Twitch and partner viewers) and
`channels` (one partner curve each, `platformChannelId`, name, avatar and
`points`). Its buckets and times match `viewerSeries`; a partner without a
known count has a gap. It is `null` without Shared Chat, when Twitch is
excluded, or after the raw samples age out. REST:
`latest_session.shared_chat_series`.

`latestSession.live.sharedChat: HistoryLiveSharedChat` supplies
`hostBroadcasterId`, ordered `participants`, `partnerViewers`,
`totalViewers`, `partnerMessages`, `sessionChatPerMin` and `source` (`state`
or `sample`). `sessionChatPerMin` is the own plus partner message rate over
the two latest Twitch samples; it is `null` until a second sample exists and
never falls back to the own `chatPerMin`. REST uses the corresponding
snake_case fields under `latest_session.live.shared_chat`.

`HistoryMilestone` has `id`, `sessionId`, `kind`, `platform`, `value`, `previous` and `achievedAt` (session start). `kind` is `viewer_record`, `sub_record`, `biggest_raid` or `follower_mark`; `platform` is set for follower marks. `channelHistoryReport.session.milestones` is always populated, while a list computes the field only when selected. Records require an earlier, lower value. The REST twins use snake_case fields and `include=milestones` for the list.

Every session (list, report and public share) carries `botMessages: Int`: the chat messages left out of `totalMessages`, `uniqueChatters`, the per-platform counts, the top lists and the emote/GIF counts because a bot wrote them (bot badge, known bot, or the account's own bot account; see [Stream History → Bot messages](../features/stream-history.md#bot-messages)). `null` means unknown: the live chat calculation is unavailable, or the session was finalized before bot filtering and its chat log is gone. A live session with a completed chat calculation has a running count. REST twin: `bot_messages`.

`viewerSparkline` contains at most 32 total-viewer points, or `null` when there are no samples. It uses raw samples when present and a 5-minute rollup for older sessions. The revenue object contains `currency`, `totalCents`, `lines`, `unpriced`, `actuals`, `grandTotal`, and `averages`. Each line has a converted `HistoryMoney` when a rate exists. `HistoryMoney` has `amountCents`, `currency`, `sourceAmountCents`, `sourceCurrency`, `rate`, `rateDate`, and `convertible`. `grandTotal` separates estimated and actual cents and lists `notConvertible` amounts. Values without an ECB rate within seven days stay in their source currency and are excluded from converted totals. The optional `currency` defaults to the user's effective display currency.

`channelHistoryReport` also carries `links: [HistoryLink!]`, `commands: [HistoryCommand!]` and `keywords: [HistoryKeywordEntry!]` (see [Stream History → Links and commands](../features/stream-history.md#links-and-commands)), each at most 50 entries by count and `null` when unknown (no frozen list and no complete chat log) or not shared. `HistoryLink` has `url` (normalized), `display` (as first posted), `domain`, `count`, `firstSeenAt`, `lastSeenAt`, `posters: [HistoryInsightPoster!]!` (top 5: `platform`, `userId`, `login`, `displayName`, `count`, `isBot`, `erased`), `otherPosters`, `occurrences: [HistoryLinkOccurrence!]!` (first 100, oldest first: `at`, `platform`, `userId`, `login`, `displayName`, `isBot`, `erased`) and `occurrencesTruncated`. `erased: true` marks an erased chatter: `userId` is `null`, `login` and `displayName` are empty — render "Deleted user". The `topChatters` JSON carries the same `erased` key on erased entries. Bot posters are included and flagged. `HistoryCommand` has `name` (prefix + lower-cased name, e.g. `!discord`), `prefix`, `count`, `uniqueUsers`, `firstSeenAt`, `lastSeenAt`, `posters`, `otherPosters`, `topArgs: [HistoryCommandArgs!]!` (top 5 `args` + `count`, `""` = no arguments), `occurrences: [HistoryCommandOccurrence!]!` (as for links, plus `args`), `occurrencesTruncated` and `known` (an enabled Lumio bot command). Bot authors are left out of commands, so `isBot` is always `false` there. REST twin: `links` / `commands` in snake_case. `HistoryKeywordEntry` has `keywordId`, `keyword`, `match`, `caseInsensitive`, `count`, `botCount`, `uniqueUsers`, `firstSeenAt`, `lastSeenAt`, top `posters`, `otherPosters`, up to 100 `occurrences` and `occurrencesTruncated`. Every tracked keyword gets a row, even with count zero. Bot posts count and are flagged; a matching leading command token counts as a keyword rather than a command. REST returns `keywords` with snake_case fields.

`channelHistoryReport` also has `announcements: [HistoryAnnouncement!]` and `pins: [HistoryPin!]`, oldest first (at most 500 and 200). `announcementsCaptured` and `pinsCaptured` distinguish sessions that began before capture from an empty list; `announcementsTruncated` and `pinsTruncated` signal the caps. `null` means unknown or a section not shared. An announcement includes its colour, author, optional Shared Chat source and deleted state; a pin includes sender, pinned-by person, planned duration, changes, actual duration, approximate-time flag and `endReason` (`expired`, `unpinned`, `replaced`, `message_deleted`, `stream_end`, `ran_past_stream_end`, `unknown`, `active`). People carry avatar, name and bot status. Neither list freezes message text: `text` and `emotes` resolve from retained chat data (pins can use the retained pin event), while `textStored: false` calls for **Text no longer stored**. The lists are masked for erased or objecting people. Announcements count as ordinary messages in chat totals and keyword insights. REST uses snake_case twins.

`adBreaks` contains `startedAt`, `durationSecs`, `automatic`, `viewersStart`, and `viewersAfter`. `adStats` contains break counts, total/average/min/max seconds, minutes per hour, the three-minute threshold, estimated impressions, and average viewer change. These are report metrics under `history:read`.

`HistoryRevenueSettings` exposes `currency`, `twitchShareBps`, `kickShareBps`, `twitchAdCpmCents`, `twitchAdShareBps`, `twitchAdFreeViewerBps`, `kickAdCpmCents`, `kickAdShareBps`, `kickAdFreeViewerBps`, `youtubeAdCpmCents`, `youtubeMidrollsPerHour`, `youtubeAdShareBps`, `youtubeAdFreeViewerBps`, `youtubeShareBps` (Super Chats), `youtubeSuperstickerShareBps`, `youtubeMembershipShareBps`, `youtubeMemberLevels { name priceCents }`, `fixedValues { item amountCents currency share source sourceUrl note }`, `updatedAt` and `updatedBy`. Fixed values are USD cents for Twitch tiers, Prime and Bits and Kick subs and KICKs; there are no editable Twitch or Kick unit-price fields. The input has the same editable fields without `fixedValues` or update stamps. The three YouTube creator shares default to 7,000 basis points when omitted; `youtubeMemberLevels` omitted keeps the stored list, while an empty list clears it. Kick and YouTube ad fields keep their stored value when omitted; explicit `null` clears `kickAdCpmCents`, `youtubeAdCpmCents` or `youtubeMidrollsPerHour`. `twitchAdCpmCents: null` also leaves Twitch ads without an amount. Level names are trimmed, unique ignoring case, non-empty and at most 100 characters; at most six levels are accepted. The REST twin uses snake_case names and identical validation.

`channelHistoryYoutubeRevenueStatus.status` is `not_connected`, `not_granted`, `not_in_ypp`, `api_disabled`, `unchecked`, or `ok`; the query never returns amounts. On an owned report, `session.estimatedRevenue.youtubeAnalytics` contains `status` (`not_granted`, `not_in_ypp`, `api_disabled`, `pending`, `provisional`, or `final`) and nullable `fetchedAt`. It is `null` without a YouTube stream, on shared reports, and on the overview. `pending` keeps the Lumio estimate; `provisional` and `final` replace YouTube ads, memberships, Super Chats and Super Stickers with `youtube_analytics_ads`, `youtube_premium`, and `youtube_transactions`. The latter is derived from YouTube's reported total; their `note` is `youtube_analytics` or `derived_from_analytics`. These fields and values need `history:revenue-read` and `feature:stream_history`. Public share links and exports use only the Lumio estimate, including the total.

### Mutations

| Mutation | Permission | Result |
|----------|------------|--------|
| `updateChannelHistoryRevenueSettings(input: HistoryRevenueSettingsInput!)` | `history:revenue-edit` | Writes the account's editable currency, shares, ad assumptions and YouTube membership levels. The fixed USD prices are read-only. Currency must be EUR or an ECB currency; shares are 0–10000 basis points; monetary inputs are 0–1,000,000 cents; mid-rolls are 0–60 per hour. Requires `feature:stream_history`. |
| `exportHistoryReport(sessionId, format, currency, locale, timeZone)` | `history:export` | Returns `{ downloadUrl, filename, contentType, format }` for a finalized report. Formats: `csv`, `txt`, `json`, `pdf`; bytes come from REST. |
| `createHistorySharedLink(sessionId, durationSecs, password, allowExport, options)` | `history:share` | Creates a link (up to 20 active per report); returns plaintext token and URL once. `options` accepts `sections` (`chat`, `top_chatters`, `ads`, `revenue`, `links`, `commands`, `keywords`, `announcements`, `pins`; these five are off unless listed), `includeRevenue`, and `currency`. Revenue inclusion also requires `history:revenue-read`. |
| `addHistoryKeyword(input: HistoryKeywordInput!)` | `history:keywords-edit` | `{ keyword, created, changed }`; a duplicate term and mode is a no-op. |
| `updateHistoryKeyword(id: UUID!, input: HistoryKeywordInput!)` | `history:keywords-edit` | `{ keyword, created, changed }`; `changed: false` for an unchanged entry. |
| `removeHistoryKeyword(id: UUID!)` | `history:keywords-edit` | `Boolean!`; `false` when the entry did not exist. |
| `extendHistorySharedLink(linkId, durationSecs)` | `history:share` | Extends expiry. A link that shares revenue also needs `history:revenue-read` (`FORBIDDEN`, same message as REST). |
| `revokeHistorySharedLink(linkId)` | `history:share` | Revokes the link. |
| `deleteChannelHistory(id)` | `history:delete` | Deletes a finalized session. A session that is not finalized yet (live, in its grace window or waiting for the finalizer) is refused with `CONFLICT` `This stream session is still live; it can be deleted once it is finalized` (same code and text as REST). |

A keyword input has `keyword`, `match` (`word`, `contains`, `regex`) and optional `caseInsensitive` (true by default). The account may track 50 entries; text modes allow 100 characters, regex 200 characters with a 1 MiB compile limit and no empty-text match. Real changes emit `account:history_keywords_updated` and recount finalized sessions with complete chat logs in the background.

A new share link defaults to chat and ads, without top chatters or revenue. A link created without `options` shows the legacy view (chat and top chatters; no ads, revenue, links, commands, keywords, announcements or pins — ad data needs the creator to turn on `ads`). `HistorySharedLink.options` describes the effective view and `legacyOptions` identifies that case. Durations are 1h, 6h, 24h, 7d, or 30d. A live report cannot be exported (`409` on REST); invalid formats and unknown sessions use the same validation as REST.

## Public Stats

Per-channel publicness for the public Stats app, gated behind the
`feature:public_stats_page` flag. Publicness is **opt-out / public-by-default**:
a channel with no settings row is public. Mirrors the REST
`/v1/public-stats/channels` endpoints exactly (same fields, guards, validation
and errors).

### Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `channelPublicSettings` | `public-stats:read` | The account's connected channels with their publicness settings (`platform`, `platformChannelId`, `channelName`, `isPublic`, `showTopChatters`, `optedOutVia`, `updatedAt`). Channels default to `isPublic: true` (opt-out) but `showTopChatters: false` (leaderboard opt-in, Art. 25(2)) until changed. |

### Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `setChannelPublicSettings(input: { platform, isPublic, showTopChatters })` | `public-stats:edit` | Toggle a channel's publicness (opt-out / opt-in) and chatter-leaderboard suppression. The channel is resolved to the caller's own connected channel for `platform` (the channel id is never taken from the client). No connection → error; an unresolved channel identity → error. Emits a `public_stats:channel_opted_{out,in}` audit event. |

### Public read model (unauthenticated)

The read surface the public Stats app consumes. **No authentication, no
permission** - reachable anonymously - and **no per-user data**, so responses are
cache-friendly. Gated globally by the `system:public_stats` kill-switch flag
(disabled → "not available"). Mirrors the REST
`/v1/public-stats/{channels,streams}` endpoints exactly. Serves **only** the §5
public-safe field set; there is no field for donations, subscriber/gifter
identities, revenue splits, or the raw `platformMetrics` / `platformBreakdown`
JSONB. First-party and crawled rows use the same types, distinguished only by the
`source` badge.

| Query | Permission | Description |
|-------|-----------|-------------|
| `publicChannelStats(platform, channel)` | none - public | A channel's public aggregate by platform + URL handle (`channel` = `channelLogin`): `platformChannelId`, `channelDisplayName`, `source`, `streamCount`, `totalDurationSecs`, `peakViewers`, `avgViewers`, `totalMessages`, `lastStreamedAt`, `broadcasterType` (Twitch channel type: `"partner"` / `"affiliate"`, else `null` - no badge; ZAF-841), and `recentStreams` (public stream summaries). Returns `null` when the channel has no addressable streams or has **opted out** (`isPublic = false`). Unsupported platform → error. |
| `publicStreamStats(platform, broadcastId)` | none - public | One stream by its public key `(platform, broadcastId)`: the stream summary, `emoteCount`, `topEmotes`, `gifCount` **and** `topGifs` (ZAF-968 - `topGifs` is `[{id, url, provider, alt, count}]`, the GIF twin of `topEmotes`; on the public-stats crawler path `provider`/`alt` are `null`, and both are erased after the 90-day GIF-content retention), de-identified `newPaidSubs` / `giftedSubs` **counts**, `newFollowers`, the `viewerCurve` timeseries, and `topChatters` **only** when the channel opted the leaderboard in (`showTopChatters = true`) - otherwise `null`. Erased and objecting chatters (`chatter_suppressions`) are blanked in `topChatters` on read (`erased: true`, count kept), also on streams frozen before the objection; if that lookup fails, `topChatters` is `null`. Returns `null` when the stream is unknown or its channel opted out. |

Every public stream summary (the `publicStreamStats` summary and the
`publicChannelStats.recentStreams` items) carries `sharedChatSources` (ZAF-819): a
list of source-channel message counts. It also carries
`sharedChatSessions: [PublicSharedChatSession!]!`: the public host and
participation timeline for first-party streams. Crawled streams without
EventSub session events return an empty list. The timeline contains no viewer
counts or identities of individual viewers. REST twins are
`shared_chat_sources` and `shared_chat_sessions`.

`sharedChatSources` is a
list of `{ platformChannelId, messageCount, displayName, avatarUrl }` naming which
**source channels** contributed Twitch **Shared Chat** messages to that broadcast.
`displayName` + `avatarUrl` (ZAF-868) are the source channel's public identity,
resolved from the crawler channel-profile store so the participant list can render
source avatars/names; both are `null` when the anonymous crawler never captured
that channel's identity (fail-open - the client falls back to the id). Shared-chat
messages are attributed to their source channel instead of being counted toward the
host, so `messageCount` / `uniqueChatters` reflect only the host channel's own chat;
the list is empty for a normal (non-shared) broadcast. Attribution is by **channel**
(public broadcaster identity), never by viewer - aggregates only.
| `publicChannelProfileHistory(platform, channel, limit, offset)` | none - public | A channel's **About-box change timeline** (ZAF-836) - bio / social-link / team changes over time, most-recent first, paginated (`limit` default 50, max 200; `offset` default 0). Each entry: `changeType` (`bio` / `link` / `team`), `oldValue` / `newValue` (opaque JSON - a string for `bio`, an array for `link` / `team`; `null` old = initial capture, `null` `bio` new = deletion), and `changedAt`. Returns `null` when the channel has no addressable streams or has **opted out**; an empty list when it has no recorded changes. Public data (founder ruling ZAF-791): no §5 minimisation, no retention cap. |
| `publicStreamMetadataHistory(platform, broadcastId, limit, offset)` | none - public | A broadcast's **stream-metadata change timeline** (ZAF-890) - title / category / tags changes over time, most-recent first, paginated (`limit` default 50, max 200; `offset` default 0). Each entry: `changeType` (`title` / `category` / `tags`), `oldValue` / `newValue` (opaque JSON - a string for `title` / `category`, an array of tag strings for `tags`; `null` old = initial capture, `null` new = emptied field / all tags removed), and `changedAt`. Returns `null` when the stream is unknown or its channel has **opted out**; an empty list when the broadcast has no recorded changes. Public data (founder ruling ZAF-791/ZAF-794): no §5 minimisation, no retention cap. |
| `publicChannelTrends(platform, channel, range)` | none - public | A channel's **"Stats"-tab trends** (ZAF-891) over the selected `range` (`DAYS_30` / `DAYS_90` / `DAYS_180` / `DAYS_365`): `followerSeries` (dated follower-total growth) and `avgViewerSeries` (dated average-viewers-over-time). Each is an oldest-first list of `{ date (`YYYY-MM-DD`, UTC), … }` day points - `followerSeries` items carry `followerCount`, `avgViewerSeries` items carry `avgViewers` (the exact sample-weighted daily mean). Follower points come from dated crawler snapshots (last value per day); avg-viewer points from the `channel_history_stats_1h` aggregate scoped to the channel's sessions. Returns `null` when the channel has no addressable streams or has **opted out**; either series is an empty list when the channel has no history in the window (frontend renders "not enough history"). Aggregate counts only - no viewer identities. |
| `publicChannelPanelHistory(platform, channel)` | none - public | A channel's **ad-panel lifecycle + image-change history** (ZAF-892) for the "Placements" tab - the ad-marked panels grouped by panel, most-recently-active first. Each entry: `panelId`, latest content (`title` / `description` / `imageUrl` / `linkUrl`), full span (`firstSeenAt` / `lastSeenAt`), lifecycle (`status` = `"active"` / `"removed"`, `removedAt`), and `images: [{ imageUrl, firstSeenAt, lastSeenAt }]` - the distinct image versions over time, oldest-first (the slideshow). Returns `null` when the channel has no addressable streams or has **opted out**; an empty list when it has no ad-marked panels. Artwork hotlinked from the Twitch CDN (never re-hosted). The flat `publicChannelStats.panels` also carries the `status` / `removedAt` lifecycle fields. |

### Sitemap and share-card queries

These three queries are anonymous. Their only gate is the account-less
`system:public_stats` kill switch, checked on every call. When it is off, they
return `0`, `[]`, and `null` respectively, without an authorization error.
The REST twins use the same service. There is no WebSocket channel because a
sitemap and a share card have no live-update consumer.

| Query | Result |
|-------|--------|
| `publicSitemapChannelPageCount: Int!` | Number of zero-based channel sitemap pages, `ceil(candidate channels / 45000)`. The count does not subtract opt-outs, so the final page can be short or empty. |
| `publicSitemapChannels(page: Int!): [PublicSitemapChannel!]!` | Up to 45,000 channel pages, ordered by platform and stable channel ID. Each entry has `platform`, `channelLogin`, and `lastmod` (UTC `YYYY-MM-DD`, from the most recent stream start). A page beyond the count returns `[]`; a negative page errors with `page must not be negative`. |
| `publicChannelCard(platform: String!, platformChannelId: String!): PublicChannelCard` | Share-card data by stable platform channel ID, independent of the URL handle. An unknown or opted-out channel returns `null`, the same as a disabled surface. An unsupported platform errors with `Unsupported platform: <p>`; an ID outside 1–64 ASCII letters, digits, `_` or `-` errors with `Invalid platform channel id`. |

The sitemap lists **channel pages only** for server-allowlisted platforms
(`public_stats.sitemap_platforms`, default `twitch,kick`) with a non-null login and a
stream started within the last 12 months. Opt-outs are removed at read time.
Clients cannot widen the allowlist. The card also checks visibility on every
hit; unknown and opted-out channels cannot be distinguished by its answer.

`PublicChannelCard` has exactly these 13 fields: `platform`,
`platformChannelId`, `channelLogin`, `channelDisplayName`, `isLive`,
`currentViewers`, `followerCount`, `streamCount`, `avgViewers`, `peakViewers`,
`watchSeconds` (viewer-seconds), `lastCategory`, and `lastStreamedAt` (UTC
timestamp). The current `channelLogin` is the channel page's canonical handle.
Unavailable figures remain `null`, never zero. The card contains no chatter
identities, bio, links, team, or change history.

### Cross-channel browse (Form B)

Public, **unauthenticated** browse/ranking **across all channels** - the metric
nav, a Games directory, and channel search - gated only by the account-less
`system:public_stats` kill-switch. Opted-out channels are excluded. GraphQL +
REST only (no WebSocket: a browse/search directory has no live-push consumer).

| Query | Permission | Description |
|-------|-----------|-------------|
| `publicChannelBrowse(platform, category, metric, live, search, page, limit): PublicChannelBrowsePage!` | none - public | Ranked channel list. `metric` (enum, default `WATCHTIME`): `WATCHTIME` (Σ avg-viewers·duration), `VIEWERS` (avg), `PEAK`, `FOLLOWER_GAIN` (Σ new-followers), `MESSAGES`, `RECENT`. Optional filters: `platform`, `category` (Games), `live` (`true`/`false`), `search` (case-insensitive substring on handle + display name). `page` 1-based; `limit` clamped `1..=100` (default 50). Each item: identity, `source` badge, `lastCategory`, `isLive`, `streamCount`, `watchSeconds`, `avgViewers`, `peakViewers`, `totalMessages`, `followerGain`, `lastStartedAt`, `broadcasterType` (Twitch channel type: `"partner"` / `"affiliate"`, else `null`; ZAF-841). Empty-string filters are treated as absent. Page fields: `page`, `limit`, `total`, `totalPages`, `totalCapped` - pages stop at row 10 000 (`page` is clamped), `total` counts at most 10 000, and `totalCapped` is `true` when more channels match (render "10 000+"). |
| `publicGames(platform, search, page, limit): PublicGamesPage!` | none - public | Games directory: distinct categories with `channelCount`, `streamCount`, `liveStreamCount`, `peakViewers`, `watchSeconds`, `lastStartedAt`. Optional `platform` filter and `search` (case-insensitive substring on category). Page-based pagination with the same 10 000-row depth cap and `totalCapped` flag as `publicChannelBrowse`. |

### Cross-channel placements (`/partners`)

Public, **unauthenticated** browse of the **active, broadcaster-marked advertising
panels** of every public channel, grouped by **advertiser** - the panel link's
host (lower-cased, leading `www.` stripped). Same gate as the other public Stats
reads (`system:public_stats` kill-switch), opted-out channels excluded, artwork
and avatar fields carry the Twitch CDN URLs (the Stats page shows them through its
[image proxy](../developer-guide/image-proxy.md)), no viewer data. GraphQL
+ REST only - the only `public-stats` WebSocket channel is the per-broadcast live
read; placements change per crawl, so there is no live-push consumer.

| Query | Permission | Description |
|-------|-----------|-------------|
| `publicPlacementsBrowse(platform, domain, sort, after, limit, placementsLimit): PublicPlacementsPage!` | none - public | Advertisers with their active placements. `platform` defaults to `twitch` (the only supported value - anything else is a validation error `Unsupported platform: …`). `domain` restricts to one advertiser (normalized like the link host). `sort` (enum, default `CHANNEL_COUNT`): `CHANNEL_COUNT` (most channels first) or `LAST_SEEN` (most recently seen first); ties by `domain`. **Keyset pagination**: pass the previous page's `nextCursor` as `after`; a malformed cursor or one from the other `sort` is rejected (`Invalid cursor`). `limit` clamped `1..=100` (default 25), `placementsLimit` `1..=50` (default 10). Page: `advertisers`, `nextCursor` (`null` on the last page), `hasMore`. Advertiser: `domain`, `channelCount`, `placementCount`, `firstSeenAt`, `lastSeenAt`, `placements` (most recently seen first, at most `placementsLimit`). Placement: `platform`, `platformChannelId`, `channelLogin`, `channelDisplayName`, `avatarUrl`, `panelId`, `title`, `imageUrl`, `linkUrl`, `firstSeenAt` (earliest across the panel's versions), `lastSeenAt`. Only the latest version of a panel counts, removed panels and panels without an `http(s)` link are skipped, and only channels with an addressable Stats page are included. |

## Emote Directory

Public, **unauthenticated** browse of the cross-platform emote catalog
(`chat_emotes`) for the public Stats app. Read-only and edge-cacheable, gated
**only** by the account-less `system:public_stats` operator kill-switch - no auth
and no RBAC permission. Mirrors the REST `GET /v1/public-stats/emotes` endpoint
exactly (same fields, filters, pagination and errors). There is **no** WebSocket
channel: a static browse / search surface has no live-push consumer (a deliberate
single-protocol omission).

### Queries

| Query | Auth | Description |
|-------|------|-------------|
| `publicEmotes(platform, provider, channelId, animated, search, page, limit): PublicEmotePage!` | none (public) | Paginated browse of the emote catalog. All filters optional: `platform` (`twitch`/`youtube`/`kick`), `provider` (the platforms plus `7tv`/`bttv`/`ffz`), `channelId`, `animated`, and `search` (case-insensitive substring on `name`). `page` is 1-based; `limit` is clamped to `1..=100` (default 50). Empty-string filters are treated as absent. When the kill-switch is off the query errors with `Feature 'system:public_stats' is not available`. |

### Types

- `PublicEmote { id, platform, provider, channelId, name, url, animated, ownerId, source, firstSeenAt, lastSeenAt }` - a public-safe projection of a `chat_emotes` row. `channelId` is `null` for a global (platform-wide) set; `source` is `api_fetch` | `observed`; `firstSeenAt` / `lastSeenAt` are RFC-3339. The internal `providerEmoteId` is **not** exposed.
- `PublicEmotePage { emotes, page, limit, total, totalPages }` - a page of `PublicEmote` with page-based metadata (identical to the REST `pagination` object).

Caching: the browse is public reference data. The REST mirror sets edge-cache
headers; the GraphQL surface (a `POST`, not edge-cacheable) is cached at the SSR
layer of the public Stats app.

## Audit Log

Three scoped readers over the `audit_events` table, one per `scope` column value
(`user` | `account` | `system`). The scope is set by the writer and never
inferred at read time, so each reader returns only its own audience's rows.

### Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `myAuditLog(filter)` | none - self-only | The caller's own `scope=user` rows. No RBAC permission, but requires a **first-party principal** - a logged-in session or the user's own API key; a popout/overlay/widget/extension token cannot read it. Current writers record successful logins, failed login attempts tied to a known user, and OAuth grant consent. |
| `accountAuditLog(filter)` | `audit-log:read` | The active account's `scope=account` events. Current emitters write role/permission, member-role, channel-connection, and account-scoped GDPR erasure rows. Requires the **account-scope** `audit-log:read` permission and returns only the caller's account's rows. |
| `adminAuditLog(filter)` | `audit-log:read` (admin) | The operator audit view. Guarded by the **admin-scope** `audit-log:read`, a distinct permission from the account one of the same name. Accepts an optional `scope` filter to narrow the superuser view to `user`, `account`, or `system`; without it, admins can read rows from every scope. |

### Types

- `AuditEvent { id, accountId, userId, eventType, scope, ipAddress, userAgent, country, city, metadata, createdAt, resolvedNames }` - `metadata` is a JSON string; `scope` is `user` | `account` | `system`.
- `AuditLogPage { items, total, page, limit }` - a page of `AuditEvent`.
- `AuditLogFilter { page, limit, eventType, dateFrom, dateTo }` - `dateFrom` / `dateTo` are RFC-3339; an unparseable value is ignored.
- `ResolvedName { id, kind, displayName }` - a read-time resolution of one entity UUID the event references to its display name (`kind` is `user` | `account` | `role`). `resolvedNames` is computed once per page for the actor plus an allowlist of metadata ids (`target_user_id`, `member_id`, `from_account_id`, `to_account_id`, `target_account_id`, `role_id`); **misses are omitted** (a deleted/unknown entity keeps only its raw UUID). The raw UUIDs are never removed - `resolvedNames` is additive. Identical field on the admin `AdminAuditEvent` and the REST `AuditEventResponse` (ZAF-1233).

Scope isolation is enforced by the reader: `myAuditLog` never returns `account`
or `system` rows, and `accountAuditLog` never returns another account's rows.
**Overlap rule:** an account-context action that has an actor lives **only** in
the account log (the actor is shown), never additionally in the user log;
personal-security events live **only** in the user log.

## Account Sessions

First-party session management for the logged-in user - the GraphQL twin of the
REST endpoints under `GET`/`DELETE /v1/users/me/sessions`. All three require a
**first-party principal** (a logged-in session or the user's own API key; a
popout/overlay/widget/extension token is rejected), guarded by `AuthGuard` +
`require_first_party_user` rather than an account-scope permission - session rows
are keyed on the acting user, not the active account (ZAF-516).

### Queries

| Query | Description |
|-------|-------------|
| `sessions` | The caller's active (non-expired) sessions. |

### Mutations

| Mutation | Description |
|----------|-------------|
| `deleteSession(id)` | Revoke one of the caller's own sessions. Emits `user:session_revoked`. |
| `deleteAllOtherSessions` | Revoke every session except the current one. Emits `user:session_revoked` with `revoked_all: true`. |

### Types

- `Session { id, userId, activeAccountId, activeAccountName, ipAddress, userAgent, expiresAt, createdAt, isCurrent }` - `activeAccountName` is the display name of the account the session currently has selected (`activeAccountId`), resolved by a `LEFT JOIN accounts` (ZAF-1418); it is `null` whenever no account is selected (API-key / fresh sessions, or after the account is dissolved), and the LEFT JOIN keeps such rows in the list. Parity with the REST `SessionResponse.active_account_name` (both protocols carry the same `active_account_id` + `active_account_name`). `isCurrent` is `true` for the one row the request is authenticated with (resolved from the session id on the principal); it lets the client render the "Current session" badge and hide the revoke button on the caller's own session. Parity with the REST `SessionResponse.is_current` (ZAF-1412) - a non-session principal leaves every row `false`. `ipAddress` / `userAgent` are first-party disclosure, readable only by the session's owner.

## Real-time Updates

Lumio does not expose a GraphQL `Subscription` type. For real-time updates (events, chat, overlay changes), use the channel-based WebSocket at `/v1/ws` - see [WebSocket](./websocket.md).

### Passkey and 2FA inputs

Passkey sign-in and assertion challenge queries return `challengeId` and browser `options`. Send the browser's `PublicKeyCredentialJSON` answer as `response` with that `challengeId`. `startPasskeyRegistration` returns browser `options` and, for the first method, `recoveryCodes`; `finishPasskeyRegistration` takes the browser `response` without a separate challenge ID. `verifyMfaChallenge`, `stepUpMfa`, `removeMfaFactor`, `disableMfa` and `regenerateRecoveryCodes` accept `passkeyChallengeId` plus `passkeyResponse` from `stepUpPasskeyOptions` (or `passkeyMfaOptions` for the pending sign-in). A second factor can also be an app `code` or `recoveryCode`. `mfaStatus.factors` reports `id`, `kind` (`totp` or `passkey`), `label`, `createdAt`, `lastUsedAt`; passkeys additionally report `provider`, `backupEligible` and `backupState`. Errors include `INVALID_MFA_FACTOR_LABEL`, `RECOVERY_CODES_NOT_STORED`, `PASSKEY_NOT_SET_UP`, `PASSKEY_INVALID`, `PASSKEY_CHALLENGE_EXPIRED`, `PASSKEY_ALREADY_REGISTERED` and `MFA_FACTOR_LIMIT`. See [REST security routes](/api-reference/rest-api#profile-security-and-data-routes) for the equivalent paths and field casing.

---

## API Reference / WebSocket

Source: https://docs.lumio.vision/api-reference/websocket

# WebSocket

Real-time communication via WebSocket using a channel-based pub/sub protocol.

## Connection

| Environment | URL |
|-------------|-----|
| Production         | `wss://api.lumio.vision/v1/ws` |
| Production Preview | `wss://lumio.api.prod.zaflun.dev/v1/ws` |
| Staging            | `wss://lumio.api.staging.zaflun.dev/v1/ws` |

The endpoint is an HTTP `GET /v1/ws` request that is upgraded to a WebSocket connection. All fields in both directions use `snake_case` JSON.

## Protocol

Lumio uses a custom JSON-message channel-subscription protocol. Clients subscribe to named channels (e.g. `events:{account_id}`, `overlay:{key}`) and receive messages pushed by the server whenever workers publish to the matching Redis pub/sub channel.

Lumio does **not** use `graphql-ws` and does **not** expose GraphQL subscriptions (`EmptySubscription`). All real-time updates flow through this WebSocket.

## Authentication

Auth is resolved by the same middleware that guards REST and GraphQL. Two transport mechanisms are supported, and **what they accept differs**:

| Token type | `Authorization: Bearer …` header | `?token=…` query param | Rate limit |
|------------|----------------------------------|------------------------|------------|
| JWT (`lm_eyJ…`)            | ✓ | ✓ | 600/min |
| User API Key (`lm_usr_…`)  | ✓ | ✗ | 1200/min |
| System Key (`lm_sys_…`)    | ✓ | ✗ | unlimited |
| Popout Token (`lm_pop_…`)  | ✗ | ✓ | 600/min |
| Overlay Token (`lm_overlay_…`) | ✓ | ✓ | 600/min |
| Shared Overlay Token (`lm_share_…`) | ✓ | ✓ | 600/min |
| Extension Token (`lm_ext_…`) | ✓ | ✓ | 600/min |
| Widget Token (`lm_widget_…`) | ✓ | ✓ | 600/min |
| Anonymous                  | (no token sent) | (no token sent) | 120/min |

API keys and System keys go **only** through the header. Query strings end up in server access logs, browser history, and `Referer` headers - long-lived credentials must not be passed there. JWTs are short-lived (~15 min), Popout tokens are revocable, and Overlay tokens are revocable/rotatable, so they're acceptable as query-param transport for browser `WebSocket` clients (which can't set custom headers natively).

Rate-limit tiers are fixed per auth context, not derived from the account's plan.

### Presented-but-invalid credentials

The distinction the middleware draws is **"credential presented and rejected"** vs. **"no credential"** - not "anonymous allowed, yes or no":

- **No token** (neither header nor `?token=`) → the connection is `Anonymous`. Public, overlay and widget channel paths are unaffected.
- **A token is presented but fails validation** - an expired or bad-signature JWT, a `refresh`/legacy JWT on the request path, or a JWT whose backing session was revoked (logout) - the **WebSocket upgrade is rejected with HTTP `401`** *before* the `101` switch, and no session is started. The 401 body is the standard error envelope `` `{ "error": "TOKEN_EXPIRED" | "UNAUTHORIZED", "message": "…" }` `` - `TOKEN_EXPIRED` when the JWT is expired, `UNAUTHORIZED` for an invalid signature, a wrong token type, or a revoked session.

Previously a presented-but-invalid token was silently downgraded to `Anonymous`: the upgrade returned `101`, then the first `chat:*` / account-scoped subscribe failed with `UNAUTHORIZED` while the socket stayed open - indistinguishable from a healthy connection. Clients should treat the `401` as "re-mint the token and reconnect" (Lumio's own clients do; see [Client reconnection](#client-reconnection)).

> **Scope:**
> On **REST and GraphQL** routes a presented-but-invalid credential still resolves to `Anonymous` (unchanged), so public routes with a stale cookie or header keep working; only the `/v1/ws` upgrade fails closed today. Either way the rejection is logged once, distinguishably from a genuinely anonymous request (`auth_type: rejected`, no token material): at `debug` for an expired JWT, which the client renews on `TOKEN_EXPIRED`, and at `warn` for an invalid signature, a wrong token type or a revoked session.

Browser apps that want to use an API key for the WebSocket connection must proxy through their own SSR layer (Next.js Route Handler → API with the header attached) - the browser's `WebSocket` API can't send headers directly.

Dashboard/popout pages must **not** place the raw session cookie JWT in the `?token=` URL (that value is also the API/session credential and would be exposed to JS, browser history and proxy logs, defeating the cookie's `httpOnly` protection). Instead the SSR page mints a **WebSocket-scoped** JWT and passes that as the query-param token. A first-party dashboard page calls the `issueWsToken` GraphQL mutation (REST twin `POST /v1/auth/ws-token`); a **popout** page calls `issuePopoutWsToken` (REST twin `POST /v1/auth/popout/ws-token`) - a separate mint because `issueWsToken` is first-party gated (ZAF-469) and rejects a popout, and because the popout token must carry the popout's **own** permission subset, never the account owner's. Either token carries **no `session_id`** and a WebSocket-only use tag, so the API accepts it **only** on the `/v1/ws` upgrade path - a leak of the WS URL cannot be replayed against a REST/GraphQL mutation or a session-management endpoint. It is short-lived (`auth.ws_token_expiration`, ~15 min); the client re-mints on reconnect. Raw JWTs passed via `?token=` on any **non-WebSocket** route are ignored.

A JWT-authenticated session's access is bounded by the token's expiry for the **whole** connection, not just at the handshake: the server checks the token `exp` on every heartbeat tick (5s) and disconnects an already-open session with `TOKEN_EXPIRED` once it passes (the same in-memory expiry enforcement applied to shared overlay tokens). This covers both a logged-in user's JWT and a popout session JWT (the `issuePopoutWsToken` token or the exchanged popout session). The client re-mints a fresh WS token and reconnects (see [Client reconnection](#client-reconnection)), so an open socket cannot outlive its token.

Overlay tokens (`lm_overlay_*`) are per-overlay access tokens designed for browser sources. Each token is bound 1:1 to a specific overlay and can only subscribe to the `overlay:{key}` channel matching that overlay. They carry no RBAC permissions and cannot access REST or GraphQL endpoints. There are a few exceptions for extension content: an overlay or widget token also reaches its own account's `events:` / `chat:` stream when it renders an extension that declares `events:read` / `chat:read` (see [Extension hosts](#extension-hosts-read-events-and-chat)). It also reaches the storage and realtime channels of the installs it renders.

Shared overlay tokens (`lm_share_*`) are temporary, time-limited tokens for sharing overlay access with collaborators. Like overlay tokens, they are bound to a specific overlay and can only subscribe to the matching `overlay:{key}` channel. The server checks expiry every heartbeat tick (5s) and disconnects with `TOKEN_EXPIRED` when the token's duration elapses. Revocation is caught by the 30-second [credential re-validation](#credential-re-validation).

### Channels being dissolved

While a channel is scheduled for dissolution, the `/v1/ws` upgrade is refused with HTTP `403` and `{ "error": "CHANNEL_DISSOLVING", … }` for **any** credential of that channel, a member's session JWT included. Sockets that are already open are closed with the error code `CHANNEL_DISSOLVING` on the next 30-second [credential re-validation](#credential-re-validation). Every feature flag also resolves off for the account, so the feature-flag gate refuses its channels. After the owner cancels the dissolution, clients connect again normally. See [REST API → Channels being dissolved](./rest-api.md#channels-being-dissolved).

### RBAC gate (subscribe-time)

Channel access is enforced at subscribe time. `crates/lo-websocket/src/gate.rs::channel_gate_for` maps each channel type to one of these gate kinds:

| Gate | Meaning |
|------|---------|
| `Public` | Anyone, including anonymous callers |
| `PublicWhenFeature(flag)` | Anyone while the named system flag is on; rejected with `FEATURE_DISABLED` when off |
| `Authenticated` | Any non-anonymous identity |
| `Permission(perm)` | Caller can access the account ID in the channel name **and** holds `perm` on it |
| `PermissionOrExtensionHost(perm)` | Same as `Permission(perm)`, **or** an `lm_overlay_*` / `lm_widget_*` token of that account whose overlay or widget renders a runnable install whose manifest declares `perm` (see [Extension hosts](#extension-hosts-read-events-and-chat)) |
| `AccountScoped` | Caller can access the account ID in the channel name; no specific permission |
| `UserPermission(perm)` | Caller holds `perm` in their **user-scoped** permissions; the channel ID is not an account UUID |
| `OverlayToken` / `WidgetToken` | Requires that bound token type, with a matching `overlay_id` / `widget_id` |
| `ExtensionOwner` | Caller is a developer who owns the extension in the channel ID |
| `Unknown` | Unrecognised channel type - always rejected |

The complete channel map:

| Channel | Gate |
|---------|------|
| `overlay:{key}` | `OverlayToken` - an `lm_overlay_*` or `lm_share_*` token bound to this specific overlay |
| `widget:{widget_instance_id}` | `WidgetToken` - an `lm_widget_*` token bound to this widget instance |
| `events:{account_id}` | `PermissionOrExtensionHost("events:read")` |
| `spotify:{account_id}` | `Permission("spotify:read")` |
| `chat:{account_id}` | `PermissionOrExtensionHost("chat:read")` |
| `automod:{account_id}` | `Permission("chat:automod-read")` |
| `automations:{account_id}` | `Permission("automations:read")` |
| `history:{account_id}` | `Permission("history:read")` |
| `chatters:{account_id}` | `Permission("chat:read")` |
| `ext-storage:{install_id}` | `ExtensionStorage` - the readers of the install's storage: its own extension token, a member session, user API key or service key of the owning account with `extension-store:read`, or an overlay / widget token whose overlay or widget renders the (runnable) install; shared overlay, popout and System keys are refused |
| `ext-install-logs:{install_id}` | `InstallLogs` - the install's owning account plus its category's read permission: `bot-modules:read` (bot module) or `automations:read` (automation node) |
| `extension_install:{install_id}` | `ExtensionInstall` - the callers of a `query` server function on the install: its own extension token, an overlay token whose overlay renders it, a widget token whose widget renders it, or a member session or user API key of the owning account with `extension-data:read`; a System key is refused (the `feature:extensions` check needs an account of its own) |
| `sounds:{account_id}` | `AccountScoped` - Widget/Overlay tokens carry no account RBAC but must still stay inside their own account; a System key needs `bots:internal` |
| `presence:{resource_channel}` | `PresenceScoped` - signed-in members of the account that owns the wrapped resource; a widget token only for its own widget |
| `ext-logs:{extension_id}` | `ExtensionOwner` |
| `ideas:list`, `ideas:{idea_id}` | `PublicWhenFeature("system:ideas_hub_public")` |
| `public-stats:{platform}:{broadcast_id}` | `PublicWhenFeature("system:public_stats")` |
| `login-assignments:{id}` | `Public` |

`presence:*` channels track who is connected to an editor session. Subscribe to `presence:widget:{id}` to receive `presence:join`, `presence:leave`, and bootstrap events with the current connections list - which include each editor's display name, avatar, `user_id` and `account_id`. Because that bootstrap leaks member identities, presence is bound to **both** the owning account and the caller's identity class. The server parses the wrapped resource (e.g. `widget:{id}`), resolves it to its owning account, and accepts only:

- a signed-in member (JWT session) of that account;
- a widget token (`lm_widget_*`) whose widget is the wrapped resource - `presence:widget:{id}` for its own widget id, and no other widget of the same account;
- a System key carrying `bots:internal` (a System key without it is rejected like any other credential).

Every other credential is rejected with `UNAUTHORIZED`, even inside the owning account: popout, overlay, shared overlay, extension, user API key, service key and developer key tokens, and anonymous callers. The subscribe also fails closed if the resource type is unknown, the id is malformed, or the resource cannot be resolved to an account.

"Can access the account" means the account in the caller's own auth context, or a System key. On `Permission` channels a System key also needs the channel's permission; on `sounds:*` and `presence:*`, which carry no channel permission, it needs `bots:internal` - never the key type alone. No other identity has a cross-tenant reach: a platform operator holding `admin:access` is gated exactly like any other member of their active account. `admin:access` is only the admin-dashboard entry gate, so it never opens another tenant's `events`, `chat`, `presence`, or other account-scoped channel.

Subscribing without the matching permission yields an `error` message with `code: "UNAUTHORIZED"` and the channel is **not** registered.

#### Extension hosts read events and chat

An OBS browser source renders extensions with an overlay token (`lm_overlay_*`, overlay page) or a widget token (`lm_widget_*`, widget page). Those tokens carry no account RBAC, so the extension's own manifest is the grant. An extension declares `events:read` and/or `chat:read` in `permissions` of its `lumio.config.json`. Such a token may subscribe `events:{account_id}` / `chat:{account_id}` when all of these hold:

- the channel's account is the token's own account;
- its overlay has an `ext:{slug}` layer for the extension, or its widget renders the install (`widget_instances.install_id`);
- the install is runnable: live, enabled, extension and run version not suspended, account not in its dissolution grace period;
- the manifest of the version the host renders (`extension_versions.manifest` of the install's `version_id`, the version the bootstrap sends) declares that same permission. `events:read` never opens `chat:` and vice versa.

The check runs once per subscribe. Anything else is rejected with `UNAUTHORIZED`: another account's channel, an install without the declaration, a disabled or uninstalled install, an overlay without the extension's layer. Shared overlay links (`lm_share_*`), popout tokens without the grant and System keys follow the plain `Permission` rule. The feature gates still apply (`feature:events`, `feature:multichat` on the channel's account). Frames are unchanged: `events:` carries `{"type":"event","data":StreamEvent}` and `chat:` carries `{"type":"chat:message","data":…}`. The host forwards each event only to extensions that declared the matching permission: chat types (`chat:message`, `twitch:chat`, `youtube:chat`, `kick:chat`, `twitch:ban`, `twitch:unban`) need `chat:read`, every other event type needs `events:read`. The hosts learn the declared permissions from `extension_permissions` in the overlay and widget bootstraps, and the dashboard widget editor learns them from `WidgetInstance.extension.permissions`.

### Feature-flag gate (subscribe-time)

After the RBAC gate passes, the WebSocket layer also checks the feature-flag layer (same source as REST/GraphQL - `account_features` overrides on top of plan defaults). Channels mapped in `crates/lo-websocket/src/gate.rs::channel_feature_for` reject the subscribe with `code: "FEATURE_DISABLED"` when the flag is off for the account:

| Channel prefix | Required feature flag |
|----------------|----------------------|
| `overlay:{key}` | `feature:overlays` |
| `chat:{account_id}` | `feature:multichat` |
| `automod:{account_id}` | `feature:multichat` |
| `automations:{account_id}` | `feature:automation` |
| `events:{account_id}` | `feature:events` |
| `spotify:{account_id}` | `feature:music` |
| `sounds:{account_id}` | `feature:sounds` |
| `history:{account_id}` | `feature:stream_history` |
| `chatters:{account_id}` | `feature:chat-viewer-list` |
| `widget:{widget_instance_id}` | `feature:widgets` |
| `ext-storage:{install_id}` | `feature:extensions` (checked on the subscriber's account) |
| `ext-logs:{extension_id}` | `feature:extension_development` |
| `ext-install-logs:{install_id}` | `feature:bot_module_extensions` (checked on the subscriber's active account) |
| `extension_install:{install_id}` | `feature:extensions` (checked on the subscriber's account) |
| `ideas:*` | `system:ideas_hub` |
| `public-stats:*` | `system:public_stats` |
| _all others_ (`presence`, `login-assignments`) | _no feature gate_ |

For `overlay:{key}` the channel suffix is the opaque overlay key, **not** an account UUID, so the entitlement is checked against the account carried by the `lm_overlay_*` / `lm_share_*` token - not by parsing the channel id. This mirrors the `feature:overlays` `FeatureGuard` on every GraphQL overlay path, so an account that loses the feature (e.g. a downgrade) stops streaming over an already-issued overlay token. `widget:{widget_instance_id}` works the same way. Its suffix is the widget id, so `feature:widgets` is checked against the account that owns the widget, which the `lm_widget_*` token carries, never against the widget id.

Plan-bypass via the WebSocket protocol is therefore impossible for gated channels - disabling `feature:automation` for a Free account stops both the REST endpoints **and** the live `automations:*` stream. Add new mappings to `channel_feature_for` when introducing paid-tier streams.

## Client Messages

All client messages are JSON with a `type` discriminator.

| `type` | Fields | Purpose |
|--------|--------|---------|
| `subscribe` | `channel: string` | Subscribe to a channel. Server responds with `subscribed` or `error`. **Idempotent:** subscribing again to a channel this session already holds re-acks with `subscribed` but does **not** open a second stream - a channel is delivered exactly once per session regardless of repeat subscribes. |
| `unsubscribe` | `channel: string` | Unsubscribe. Server responds with `unsubscribed` and delivery for that channel stops immediately. |
| `ping` | -- | Heartbeat. Server replies with `pong`. |

The socket is **read-only for clients**. No frame lets a client publish into a channel. Every channel's publisher is server-side code, such as the event pipeline, chat ingest, workers, and REST/GraphQL mutations. Any other `type`, including a `broadcast` frame, is answered with `code: "INVALID_FORMAT"` and has no effect.

Example:

```json
{"type":"subscribe","channel":"events:550e8400-e29b-41d4-a716-446655440000"}
```

Messages larger than 64 KiB are rejected with `MESSAGE_TOO_LARGE`.

### Subscribe rate limit

Each session has a token bucket for `subscribe` and `unsubscribe` frames. Both frame kinds draw from the same bucket, on every channel type. A fresh session may send **120** of them back-to-back (`subscribe_burst`), then **5 per second** (`subscribe_refill_per_second`). The burst is never below the session channel cap (`max_channels_per_session`, default 100): a lower configured value is raised to the cap at startup, so a client can always subscribe a full channel set at connect. A frame sent with the bucket empty gets an `error` with `code: "RATE_LIMITED"` and is dropped: the subscription is not changed, and no authorization or bootstrap work runs for it. The message names the channel and how many milliseconds until the next frame is accepted. The session stays open, and channels already subscribed keep delivering. Repeat the dropped frame after that delay. `ping` frames do not count against the bucket.

The limit exists because every subscribe runs the channel's authorization lookups and its bootstrap read. For `public-stats:*` that bootstrap is a database read, available to anonymous callers. A normal client subscribes to a few channels after `welcome` and stays far below the burst. A reconnect opens a new session with a full bucket. The `/ws` upgrade itself is covered by the HTTP rate limiter, so one caller cannot reset its bucket faster than it is allowed to open connections.

## Server Messages

All server messages are JSON with a `type` discriminator.

Messages generated by the session loop itself use the `ServerMessage` shapes:

| `type` | Fields | Meaning |
|--------|--------|---------|
| `welcome` | `session_id: string`, `server_version: string` | Sent once immediately after the socket opens. |
| `subscribed` | `channel: string` | Subscription accepted. |
| `unsubscribed` | `channel: string` | Unsubscription accepted. |
| `pong` | -- | Reply to `ping`. |
| `error` | `message: string`, `code: string` | Error. See codes below. |
| `event` | `channel: string`, `event_type: string`, `data: object` | Event payload for a subscribed channel. |

Relayed traffic reuses `event` for most families but keeps three legacy per-family discriminators:

| `type` | Fields | Meaning |
|--------|--------|---------|
| `spotify:now-playing` | `data: object` | Spotify playback-state update relayed from `spotify:{account_id}`. |
| `chat:message` | `data: object` | Chat event relayed from `chat:{account_id}` (new messages, deletions, moderation logs, etc.). |
| `automation` | `data: object` | Automation-engine update relayed from `automations:{account_id}`. |

### Relay envelope

When a worker publishes to a Redis pub/sub channel, the API's event-relay worker forwards the payload to every subscribed WebSocket session, wrapped in an envelope. The envelope depends on the Redis channel prefix. Only the prefixes listed below are relayed - a publish on any other Redis channel never reaches a WebSocket client.

| Redis channel | WebSocket envelope | Published to sessions subscribed on |
|---------------|--------------------|-------------------------------------|
| `lumio:events:{account_id}` | `{"type":"event","data":…}` (`data` is the full event row; `raw` is forwarded unchanged, incl. the Twitch Shared Chat `is_shared_chat` / `source_channel` / `shared_chat_notice_type` partner-event fields - see [Events](../features/events.md#twitch-shared-chat-partner-events)) | `events:{account_id}` |
| `lumio:spotify:{account_id}` | `{"type":"spotify:now-playing","data":…}` | `spotify:{account_id}` |
| `lumio:chat:{account_id}` | `{"type":"chat:message","data":…}` (including `data.type: "chat:pins"` and `data.type: "shared_chat_session"`) | `chat:{account_id}` |
| `lumio:automod:*` | `event` with `event_type` and `data` | `automod:{account_id}` |
| `lumio:automations:{account_id}` | `{"type":"automation","data":…}` | `automations:{account_id}` |
| `lumio:overlay:{key}` | `{"type":"event","channel":…,"event_type":…,"data":…}` - `event_type` from the payload, default `overlay:update` | `overlay:{key}` |
| `lumio:widget:{widget_instance_id}` | `{"type":"event","channel":…,"event_type":…,"data":…}` - `event_type` from the payload's `type`, default `widget:update` | `widget:{widget_instance_id}` |
| `lumio:ext-storage:{install_id}` | `{"type":"event","channel":…,"event_type":"storage:update","data":…}` | `ext-storage:{install_id}` |
| `lumio:extension_install:{install_id}` | `{"type":"event","channel":…,"event_type":"extension:realtime","data":{"topic":…,"payload":…}}` | `extension_install:{install_id}` |
| `lumio:sounds:{account_id}` | `{"type":"event","channel":…,"event_type":"sound:play"\|"sound:stop","data":…}` | `sounds:{account_id}` |
| `lumio:history:{account_id}` | `{"type":"event","channel":…,"event_type":"history:session_started"\|"history:session_sampled"\|"history:session_updated"\|…,"data":…}` | `history:{account_id}` |
| `lumio:chatters:{account_id}` | `{"type":"event","channel":…,"event_type":"chatters:delta","data":…}` | `chatters:{account_id}` |

The relay is one-way (Redis to WebSocket). For the four legacy families (`events`, `spotify`, `chat`, `automations`) `data` is the exact JSON the publisher sent, including publisher-specific fields such as `type`, `event_type`, and `payload`. For the other families the relay lifts `event_type` out of the payload and forwards the payload's `data` member.

A `chat:message` envelope whose `data.type` is `shared_chat_session` contains
the **full** REST-shaped session state, not a delta: `status`, `revision`,
`session_id`, host and own broadcaster IDs, times, `participants` and
`total_viewers`. It uses the existing `chat:{account_id}` subscription,
including for delegated popout tokens with `chat:read`; there is no new
channel or Redis pub/sub key. Clients drop an older revision and keep the
last state on `unknown`. Every persisted transition also sends
`history:session_updated` on the existing history channel, with `session_id`,
`reason: "shared_chat"` and `revision`, so open reports can reload at once.

Channel-status transitions do not have their own WebSocket channel: the channel-status relay republishes them onto `lumio:events:{account_id}` as `channel:online` / `channel:offline`, so they arrive on `events:{account_id}`.

After each successful history sampler tick, `history:{account_id}` receives `history:session_sampled` with `data: { "session_id": "<uuid>", "platforms": ["twitch", "kick"], "sampled_at": "<RFC3339 minute>" }`. The channel requires `history:read` and `feature:stream_history`. The event tells the dashboard to refetch `channelHistoryOverview`; it does not contain the sampled counters. The dashboard reuses its existing socket for this subscription.

#### Relay liveness

One relay task holds one Redis pub/sub subscription and feeds **every** channel in the table above, for every account. Its health is therefore all-or-nothing: if that subscription dies, every WebSocket client goes silent at once while their sockets stay open and their pings keep getting answered.

A pub/sub subscriber never writes after subscribing, so a peer that disappears without a clean TCP close leaves a socket that looks perfectly healthy and simply never delivers again. `lo_cache::RedisSubscriber` therefore probes its own connection: after 30 s of silence it sends a Redis `PING`, and if that goes unanswered for 5 s the subscription is declared dead so the relay's reconnect loop takes over. TCP keepalive and `TCP_USER_TIMEOUT` are enabled on the same socket as a kernel-level backstop (`redis` leaves both off by default). Every `RedisSubscriber` user inherits this - the API relays and workers as well as all five chat bots.

Watch `ws_relay_connected`, `ws_relay_reconnects_total` and `ws_relay_messages_total` (see [Metrics](../developer-guide/metrics.md)).

Example relayed follower event on `events:{account_id}`:

```json
{"type":"event","data":{"type":"twitch:follower","payload":{"username":"viewer123"}}}
```

#### Chat sub-types

Inside the `chat:message` envelope, the `data.type` field disambiguates the underlying chat event:

| `data.type` | Direction | Payload shape |
|-------------|-----------|---------------|
| _absent / regular `ChatMessage` fields_ | Worker ➔ clients | Full chat-message row (id, username, message, emotes, badges, reply fields, …). An announcement has `message_type: "announcement"` and `announcement_color` (`primary`, `blue`, `green`, `orange`, `purple`); an ordinary message has no announcement colour. A reply carries the parent author as both `reply_parent_username` (display name) and `reply_parent_login` (login/handle twin; `null` where unavailable). For a Twitch **Shared Chat** message originating in a different channel's room, also carries `is_shared_chat: true` and `source_channel: {platform_channel_id, login, display_name, avatar_url}`; both are absent/`null` for normal and host-origin messages. |
| `chat:pins` | Pin worker ➔ clients | `{type: "chat:pins", twitch, kick}` replaces the full current pin state for both platforms. Each pin has `sent_at` (the original message time or `null`) beside `starts_at`, `ends_at` and `updated_at`. Subscribe to the existing `chat:{account_id}` channel; there is no separate pins subscription. |
| `chat:delete` | Worker ➔ clients | `{type, platform_message_id, deleted_by}` - a single message was moderation-deleted, either issued through Lumio **or** detected natively (Twitch EventSub `channel.chat.message_delete`, YouTube moderator-delete / author-retract, InnerTube, Kick `MessageDeletedEvent` from the unofficial chat socket - `deleted_by` is `"moderator"` or `"Kick AutoMod"`). The row is only ever **soft-deleted** - never hard-deleted - and the removal is recorded in the affected user's moderation log; clients grey out that row. |
| `chat:clear_user` | Worker ➔ clients | `{type, platform, platform_user_id, deleted_by, action, duration_secs}` - fired after a successful ban/timeout (issued through Lumio or detected via Twitch EventSub `channel.ban` / Kick webhook `moderation.banned`); clients grey out **every** message from `(platform, platform_user_id)` and append a localised "Banned/Hidden/Timed-out by X" suffix. `action` is `"ban"` or `"timeout"`; `duration_secs` is `null` for permanent bans. |
| `chat:moderation_log` | Worker ➔ clients | `{type, data: {action, platform, target_user_id, target_username, target_display_name, moderator_name, moderator_login, reason, duration_secs, ends_at, target_message_id, created_at}}` - moderation-log entry for the user card and moderation feed widgets. It is published for every stored entry: native actions (Twitch EventSub ban/unban, Kick webhook `moderation.banned`, Kick delete/unban from the unofficial chat socket) **and** actions issued through Lumio (REST/GraphQL `moderate`, all platforms), all built from the same fields as the stored row. `duration_secs` / `ends_at` are set for a timeout and `null` for a ban, delete or unban. `target_username` / `moderator_login` carry the login half, `target_display_name` / `moderator_name` the display half; either half may be `null` when a platform exposes only one name (e.g. YouTube) or a system placeholder acted. |
| `chat:user_treatment_update` | Worker ➔ clients | `{type, platform, platform_user_id, user_treatment}` - per-user treatment changed (`user_treatment` ∈ `active_monitoring`, `restricted`, `none`); REST, GraphQL, and Twitch EventSub all publish this identical flat shape |

Subscribe to `chat:{account_id}` once and dispatch on `data.type` - the chat-shell, multichat hook, and OBS browser-source clients all use the same demultiplexer.

The `events:{account_id}` relay also carries the five pin events
(`twitch:pin_added`, `twitch:pin_updated`, `twitch:pin_removed`,
`kick:pin_added`, `kick:pin_removed`) and the four Twitch role events
(`twitch:mod_added`, `twitch:mod_removed`, `twitch:vip_added`,
`twitch:vip_removed`) as ordinary `event` frames. Pin `raw` includes the
sender and moderator person shapes described in [Events](/features/events#pin-and-twitch-role-events);
`raw.sent_at` on a pin-added event is the original message time or `null`.

### Error codes

| `code` | Meaning |
|--------|---------|
| `UNAUTHORIZED` | Caller lacks access to the requested channel (missing account access or `resource:action` permission). |
| `FEATURE_DISABLED` | Caller is authorized but the channel's feature flag is disabled for the account (e.g. `feature:automation` off). |
| `TOKEN_REVOKED` | The credential the session was opened with is no longer valid: it was revoked, rotated, deleted or has expired, or (popout tokens, personal API keys) the member it is bound to left the account. See [Credential re-validation](#credential-re-validation). Reconnect with a fresh credential - for a browser source, a fresh URL from the dashboard. |
| `AUTH_UNAVAILABLE` | The server could not re-validate the session's credential twice in a row (database timeout or error), so it closed the session instead of keeping it open unchecked. Transient - reconnect with backoff. |
| `TOKEN_EXPIRED` | The session's token has expired mid-connection - a shared overlay token whose duration elapsed, or a JWT session whose token `exp` passed. Re-mint the token and reconnect (Lumio's clients do this automatically); for a shared link, create a new one to regain access. |
| `CHANNEL_DISSOLVING` | The channel the session belongs to is scheduled for dissolution and suspended. Sent on the 30-second [credential re-validation](#credential-re-validation) tick, then the socket is closed. Reconnecting is refused until the owner cancels the dissolution. |
| `SUBSCRIBE_FAILED` | Server-side failure while registering the subscription. |
| `CHANNEL_DROPPED` | The client fell too far behind on one channel and the server dropped it from that channel (its outbound buffer stayed full). The session stays connected and other channels are unaffected; resubscribe to resume. Surfaced instead of the channel silently disappearing. |
| `INVALID_FORMAT` | Message was not valid JSON or did not match any known client-message shape. |
| `MESSAGE_TOO_LARGE` | Text frame exceeded the 64 KiB limit. |
| `RATE_LIMITED` | A `subscribe` or `unsubscribe` frame arrived with the session's [subscribe rate limit](#subscribe-rate-limit) used up. The frame was dropped; the session stays open. Retry the frame after the delay named in the message. |

## Heartbeats and timeouts

The server disconnects any session that has been silent for 30 seconds (`client_timeout`, 6× the 5-second heartbeat interval - a margin wide enough that throttled background tabs are not dropped). **The server does not send WebSocket `Ping` frames**, so the client is responsible for keeping the connection alive: send a `{"type":"ping"}` every few seconds, or maintain any other inbound traffic. A hidden browser tab has its `setInterval` clamped to at most once per minute, so the wide `client_timeout` margin is what keeps backgrounded overlay and Multichat tabs connected - do not shrink it toward the heartbeat interval. Standard WebSocket `Ping` control frames sent *by the client* are auto-answered with `Pong`. (The 5-second heartbeat tick is an internal timer used for credential re-validation and JWT / shared-token expiry enforcement, not a ping to the client.)

The same `client_timeout` also bounds every outbound send: if a client stops draining its socket (a sleeping phone, a half-open TCP connection), the server closes and reaps the session within that window instead of buffering its broadcasts without limit. A per-session outbound queue caps at 256 messages; a session that stays behind past that point is disconnected rather than allowed to grow unbounded.

### Credential re-validation

Every session opened with a revocable credential has that credential re-validated against the database every 30 seconds (throttled inside the 5-second heartbeat tick), not only at the handshake. This covers every token kind:

| Credential | Invalid on the next re-check when |
|------------|-----------------------------------|
| Popout token `lm_pop_*`, and popout session JWTs minted from one | the origin token is revoked, expired or deleted, or the member it is assigned to left the account |
| Personal API key `lm_usr_*` | the key is rotated, expired or deleted, or its owner left the account |
| Service key `lm_svc_*` | the key is rotated, expired or deleted |
| Developer key `lm_dev_*` | the key is revoked, rotated, expired or deleted |
| Overlay token `lm_overlay_*` | the token is rotated, revoked, expired or deleted |
| Shared overlay token `lm_share_*` | the link is revoked or has expired |
| Extension token `lm_ext_*` | the token has expired or was deleted |
| Widget token `lm_widget_*` | the token is rotated, revoked, expired or deleted |
| JWT carrying a `session_id` | the session was logged out or has expired |

The check reads the stored token hash, so a **rotated** secret stops working on an open socket even though the token row (and its id) survives the rotation. Nothing about validity is cached: a revocation is visible on the very next re-check.

When the credential is no longer valid, the server sends an `error` with `code: "TOKEN_REVOKED"` and closes the WebSocket. Browser sources automatically attempt to reconnect, at which point they need a fresh URL from the dashboard.

The re-check **fails closed**. Each check has a 500 ms budget; a timeout or database error keeps the session's last result (it was valid, or the session would already be closed) for **one** check only. A second consecutive failure closes the session with `code: "AUTH_UNAVAILABLE"`; clients reconnect with backoff, and the reconnect handshake validates the credential afresh. A single successful check resets the count, so an isolated database blip never disconnects anyone.

A JWT without a `session_id` (the WS token minted by `issueWsToken` / `issuePopoutWsToken`) has nothing to look up; its lifetime is bounded by its `exp` instead (see [JWT session expiry](#jwt-session-expiry)). Anonymous sessions and system keys are not re-validated.

### JWT session expiry

For sessions authenticated with a JWT (a logged-in `User`, including the WebSocket-scoped token minted by `issueWsToken`, and a popout session JWT, including the token minted by `issuePopoutWsToken`), the server enforces the token's `exp` for the entire connection. On each heartbeat tick it compares the token expiry (carried in from the validated claims - no per-tick database round-trip) against the current time and, once it has passed, sends an `error` with `code: "TOKEN_EXPIRED"` and closes the WebSocket. This bounds an already-open socket to its token's lifetime: the handshake rejection alone (see [Authentication](#authentication)) only stops an *expired* token from *starting* a session, whereas this closes a session whose token expires *while connected*. Lumio's clients re-mint a fresh WS token and reconnect automatically.

### Client reconnection

Lumio's own browser clients (dashboard chat/events/history feeds, popout windows, overlay browser sources) share one resilient reconnection strategy:

- **Fresh credential per connect.** The dashboard mints its WS token (`issueWsToken`) from a short-lived route on **every** connect attempt (never a value frozen at page load), and popout windows mint their own WS-scoped token (`issuePopoutWsToken`) the same way. A tab left open past the token TTL therefore re-mints and recovers on its next reconnect without a page reload.
- **`welcome`-gated subscribe.** The client subscribes only after the `welcome` frame and reports itself "connected" only once the server acknowledges a subscription with `subscribed`. A rejected subscribe surfaces the `error` `code` in the UI rather than a false "connected" state.
- **Bounded auth recovery.** An `error` with `UNAUTHORIZED` / `FORBIDDEN` / `TOKEN_EXPIRED` / `TOKEN_REVOKED` triggers exactly one fresh-token reconnect; a second consecutive auth error stops the loop (no reconnect storm). `FEATURE_DISABLED` stops immediately; `CHANNEL_DROPPED` reconnects to re-subscribe; `AUTH_UNAVAILABLE` is transient and reconnects with the normal backoff.
- **Jittered backoff.** Reconnect delay is exponential (1s → 30s cap) with equal jitter so a fleet of tabs does not stampede the API in lockstep after a restart, and the backoff counter resets only after a connection has held stably - a socket that drops right after upgrading keeps escalating instead of hammering at the 1s floor.
- **Subscribe only to channels the credential can read.** Because auth recovery is triggered by an `UNAUTHORIZED` `error` frame, a client that runs several channels over one socket must not subscribe to a channel its own credential cannot read - the per-channel rejection would enter the reconnect path and churn the *whole* socket, dropping the channels that were working. So a surface asks only for what its token's permission subset allows, resolved before it opens the socket. Concretely, a **delegated/shared chat pop-out** (a popout session from a shared `lm_pop_*` link) always subscribes to `chat:{account_id}`, and additionally subscribes to `events:{account_id}` **only when its token was granted `events:read` and the account holds `feature:events`** - the same conditions the [subscribe-time RBAC gate](#rbac-gate-subscribe-time) enforces server-side. The common delegated subset (`chat:read`, no `events:read`) therefore never attempts the `events:` subscribe, so it shows live chat but no inline stream-event lines; a pop-out whose creator explicitly delegated `events:read` gets both. See [Multichat → Inline stream events](../features/chat.md#where-inline-events-appear-and-where-they-dont).

### Chatters channel

`chatters:{account_id}` carries the live [chatter list](../features/chatter-list.md). Same guard as GraphQL `chatters` and REST `GET /v1/chat/chatters`: `chat:read` + `feature:chat-viewer-list`; popout tokens (ws-token) with `chat:read` are accepted. Clients never publish. Its `supported_platforms` contains Twitch and, when the account has a usable Kick channel connection, Kick.

- **Subscribe** → one `bootstrap` event whose `data` is the full `ChattersSnapshot` (`supported_platforms`, `platforms`, `chatters` — the REST shape without the `data`/`links` wrapper). Holding the channel open keeps the server polling the platform. Every subscription also renews the account's 7-day *wanted* marker, so the server keeps polling while that platform's stream is live even with no subscriber (see [Chatter List → Polling](../features/chatter-list.md#polling-open-panel-or-live-stream)). An account that never subscribes causes no platform calls.
- **Then deltas only**, `event_type: "chatters:delta"`:

| `data.op` | Payload | Client action |
|---|---|---|
| `join` | `{op, platform, entries: [Chatter]}` | Add each entry. A `join` for a key the client already holds is applied as an `update` (dedupe, e.g. after a reconnect) |
| `update` | `{op, platform, entries: [Chatter]}` | Replace the entry with the same (`platform`, `user_id`). This includes **leaving the chat** (`present: false`, frozen `last_seen_at`) and **coming back** (`present: true`, new `first_seen_at`) |
| `leave` | `{op, platform, entries: [Chatter]}` | **Drop the row** with the same (`platform`, `user_id`); unknown keys are ignored. Sent when the recently-left retention is over, and for every entry when the stream goes offline |
| `status` | `{op, platform, entries: [], status: ChatterPlatformStatus}` | Replace that platform's status (`available`, `reason`, `total`, `truncated`, `updated_at`) |

`status.reason` can be `missing_scope`, `not_connected`, `disabled`, or `source_unavailable`. The last value means that the platform’s list source failed (for example, Kick’s undocumented endpoint): `available` is `false`, `total` is `null`, `truncated` is `false`, and recent writers remain in the list. After two failed polls, snapshot-only entries receive `update` with `present: false`. Other platforms continue independently.

Entries are keyed by (`platform`, `user_id`), never by name. One frame carries at most 500 entries. A new `bootstrap` (re-subscribe) replaces the whole list.

**Presence lifecycle of one key** (ZAF-1767):

1. `join` (`present: true`, `first_seen_at` set) — the person appears.
2. `update`s while they stay: role, avatar, color, name. `first_seen_at` does not move; a present row's moving `last_seen_at` is **not** re-sent per poll.
3. `update` with `present: false` — they left. `last_seen_at` is now final. Show them as recently left; never count them.
4. Either `update` with `present: true` and a **new** `first_seen_at` (they came back within 30 min), or `leave` once `last_seen_at` is older than the retention (30 min) — remove the row.

When the stream goes offline the server sends `leave` for every entry, so the next stream starts empty. A client that missed frames re-subscribes and gets a fresh `bootstrap`.

### Observability

The WebSocket server exposes two live gauges on the public health surface (`GET /v1/health`, `data.websocket`): `sessions` (active WebSocket sessions) and `channels` (active broadcast channels). Both are aggregate counters with no per-user or per-channel detail. They are maintained on every connect/disconnect and subscribe/unsubscribe and read lock-free, so scraping the health endpoint never contends with the broadcast hot path. Watching `sessions` trend flat rather than climbing is the production signal that the connection-reaping path is healthy.

### AutoMod events

`automod:{account_id}` carries `automod:held`, `automod:resolved` and `automod:moderation_log` as `event` envelopes. It is separate from `chat:{account_id}`: a held message never reaches ordinary chat, overlays or widgets. The channel requires `chat:automod-read` and `feature:multichat`; a popout token with that permission can subscribe. The client also fetches `heldChatMessages` / `GET /v1/chat/automod/held` to restore open holds after reconnect.

The `automod:held` payload has the same fields as a `heldChatMessages` entry: `emotes` (Twitch emotes and cheermotes in the chat-message `emotes` shape, derived from the fragments when the message leaves the server; absent or `null` when there are none or the fragments were dropped for size) and the sender's `avatar_url`, `color` and `badges` (a snapshot of Lumio's chatter record at hold time; absent for a chatter Lumio has not seen). Resolved holds stay readable after a reload as `automod` items of the merged chat history ([`mergedChatHistory`](../features/chat.md#server-merged-history-read-mergedchathistory)).

## Example Channels

- `events:{account_id}` -- Stream events (follows, subs, cheers, raids, redemptions, tips, channel online/offline, bot-command updates, `spotify:track`). Requires `feature:events`. Readers are members with `events:read` and [extension hosts](#extension-hosts-read-events-and-chat) whose extension declares `events:read`.
- `spotify:{account_id}` -- Spotify "now playing" state changes for the Spotify overlay widget.
- `chat:{account_id}` -- Live chat messages, deletions, moderation logs, user-treatment updates. Requires `feature:multichat`. Readers are members with `chat:read` and [extension hosts](#extension-hosts-read-events-and-chat) whose extension declares `chat:read`.
- `automod:{account_id}` -- Twitch AutoMod holds and decisions; requires `feature:multichat` and `chat:automod-read`.
- `automations:{account_id}` -- Automation-engine lifecycle updates (triggers, execution progress).
- `history:{account_id}` -- Stream-history session lifecycle (started / updated / ended) and sampler ticks (`history:session_sampled`). Requires `feature:stream_history` and `history:read`.
- `chatters:{account_id}` -- Live chatter list: snapshot as `bootstrap`, then `chatters:delta` (`join` / `leave` / `update` / `status`). Requires `feature:chat-viewer-list` and `chat:read`. See [Chatters channel](#chatters-channel).
- `sounds:{account_id}` -- Sound playback commands (`sound:play`, `sound:stop`) consumed by browser sources to trigger in-overlay audio. Requires `feature:sounds` and access to the account in the channel name.
- `overlay:{key}` -- Per-overlay updates for browser-source popouts. Requires an `lm_overlay_*` or `lm_share_*` token bound to the specific overlay identified by `key`. On subscribe the server pushes a `bootstrap` event with `account_id` and the overlay's `layers` (`id`, `overlay_id`, `type`, `name`, `config`, `visible`, `sort_order`, `created_at`, `updated_at`), plus `obs`, `spotify` and `chat` state when the overlay has such layers. An extension layer (`type: "ext:{slug}"`) also carries `extension_id`, `extension_install_id`, `extension_slug` `extension_version` and `extension_permissions` (the `permissions` array of that version's manifest, `[]` when it declares none) when the overlay's account has a live, enabled install of that extension and the extension is not suspended; the bundle is served at `/extension-bundles/{extension_id}/{extension_version}/layer.js`. Without such an install these keys are absent and the overlay mounts nothing for the layer. A `layers:updated` event (sent when the overlay is saved in the editor) carries `layers` in the same shape, so a live overlay keeps its extension layers mounted. The overlay bootstrap exists only on WebSocket; GraphQL `overlayLayers` is the dashboard editor read and returns the raw rows.
- `widget:{widget_instance_id}` -- Per-widget config/state updates for browser sources. Requires an `lm_widget_*` token bound to that instance and `feature:widgets`. On subscribe the server pushes a `bootstrap` event with `account_id`, `widget_type`, `name`, `config`, `width`, `height`, `extension_id` and `install_id`. An extension widget also gets `version` and `extension_permissions`: `version` is the bundle version, served at `/extension-bundles/{extension_id}/{version}/layer.js`. `extension_permissions` is the `permissions` array of that version's manifest. Both are sent only while the install is live and enabled and the extension is not suspended. Otherwise `version` is `null` and `extension_permissions` is `[]`.
- `ext-storage:{install_id}` -- Live key/value updates for an extension installation's storage: every write through GraphQL `setExtensionStorage` / REST `POST /v1/extension-installs/{install_id}/storage` arrives as a `storage:update` event with `data: { "key", "value", "install_id" }`. The id is an install id; the server resolves it to the install and admits exactly the callers that may read that storage on GraphQL `extensionStorage` / REST `GET /v1/extension-installs/{install_id}/storage` - the install's own extension token, a member session, user API key or service key of the owning account holding `extension-store:read`, or an overlay token whose overlay renders the install in an extension layer (`ext:{slug}`) or a widget token whose widget renders it, as long as the install is runnable. Overlay or widget tokens that do not render the install, shared overlay, popout, developer and System keys, anonymous callers, a member of another account, an unknown install, an install waiting for its data deletion and a malformed id are rejected with `UNAUTHORIZED`. Also requires `feature:extensions` on the caller's account. Updates are not stored; read the current values through `extensionStorage`. The web extension host subscribes to this channel for every install it renders and hands each update to the extension as `storage.update`, so `useExtensionStorage()` re-renders on every surface.
- `ext-logs:{extension_id}` -- Build and runtime log stream for an extension, restricted to its owning developer. Requires `feature:extension_development`.
- `ext-install-logs:{install_id}` -- Runtime logs of one bot-module or automation-node install. The server resolves the install to its owning account and extension category; the caller needs access to that account and the category's read permission: `bot-modules:read` for a bot module, `automations:read` for an automation node. This is the same rule as GraphQL `extensionInstallLogs` and REST `GET /v1/extension-installs/{id}/logs`. An unknown or uninstalled install, an install of any other category, and a malformed id are rejected with `UNAUTHORIZED`. Also requires `feature:bot_module_extensions` on the caller's account.
- `extension_install:{install_id}` -- Realtime messages of one extension install: every `ctx.realtime.push(topic, payload)` of its server-function and bot-module handlers arrives as an `extension:realtime` event with `data: { "topic", "payload" }`. The extension host in the dashboard, overlay and widget pages subscribes with its own credential and hands each message to the extension (`server.realtime`, SDK `useRealtime`). Admitted are exactly the callers of a `query` server function on the install - the install's extension token, an overlay token whose overlay has a layer of the extension, a widget token whose widget renders the install, and a member session or user API key of the owning account holding `extension-data:read`. System keys (even with `bots:internal`, since the `feature:extensions` check runs on the subscriber's own account), popout, shared overlay, service key, developer key and anonymous credentials, an unknown or uninstalled install, an install whose code may not run (extension or version suspended, install disabled, account in its dissolution grace period) and a malformed id are rejected with `UNAUTHORIZED`. Also requires `feature:extensions` on the caller's account. Messages are not stored; a client that is not subscribed when a push happens never receives it. There is no GraphQL subscription twin: the API has no GraphQL subscription transport, and browsers never call GraphQL directly.
- `presence:widget:{id}` -- Editor presence (`presence:join`, `presence:leave`, bootstrap list). Open to signed-in members of the account that owns the widget, to that widget's own widget token, and to a System key carrying `bots:internal`; every other credential is rejected. Resource types without an account resolver fail closed.
- `ideas:list` / `ideas:{idea_id}` -- Ideas Hub list and per-idea updates. Public while `system:ideas_hub_public` and `system:ideas_hub` are on.
- `public-stats:{platform}:{broadcast_id}` -- Public Stats live read for one stream. On subscribe the server pushes a `bootstrap` event with the field-gated, opt-out-respecting stream snapshot (the same DTO as the GraphQL `publicStreamStats` / REST `GET /v1/public-stats/streams/...`). **Unauthenticated** and carries no per-user data; gated globally on `system:public_stats`. An **opted-out** channel (or an unknown stream) yields **no bootstrap**. Clients never publish - server-side only. The cross-channel **browse/search** surface (`GET /v1/public-stats/{browse,games}` + GraphQL `publicChannelBrowse` / `publicGames`) has **no** WebSocket channel - a browse/search directory has no live-push consumer (a justified single-protocol omission, like the emote directory).
- `login-assignments:{id}` -- Login-assignment updates. Public.

---

## API Reference / Authentication

Source: https://docs.lumio.vision/api-reference/authentication

# Authentication

Email/password and platform sign-ins are completed in the ID app. A verified email address is an independent sign-in credential; Lumio does not auto-link profiles from an email claim supplied by a platform. Where 2FA is enabled, OAuth, password and PKCE authorization return a pending challenge with `mfaMethods` (`passkey` and/or `totp`) until an app code, passkey or recovery code is verified. A passkey sign-in completes 2FA in one browser ceremony. The confirmation link only verifies the address and does not sign anyone in.

Sensitive profile actions use a ten-minute session-bound step-up. With 2FA enabled, it accepts a passkey, authenticator app code or recovery code; otherwise an existing provider connection or email password can confirm identity. `STEP_UP_REQUIRED` means the client should ask the user to confirm again. See [REST profile security routes](/api-reference/rest-api#profile-security-and-data-routes).

Lumio resolves every incoming request into one of **eleven** authentication contexts. The auth middleware never rejects a request by itself - it resolves the strongest context it can and falls back to `Anonymous`; the individual route, resolver, or WebSocket gate then decides whether that context is sufficient.

## Auth Types

| Context | Prefix | Length | Carries RBAC | Purpose |
|---------|--------|--------|--------------|---------|
| System Key | `lm_sys_` | 71 | System-scope grants (may include `resource:*` / `*:*`) | Internal service-to-service and bot auth |
| User API Key | `lm_usr_` | 71 | Scoped subset of the creator's account permissions | Programmatic external API access |
| Service Key | `lm_svc_` | 71 | Scoped subset of the creator's account permissions (no user identity) | Account-owned CI/CD credential that survives member departure |
| Developer API Key | `lm_dev_` | 71 | The `extension-dev:*` family only, bound to a developer profile or team (no account) | `lumio deploy` / CI publishing for extension developers |
| JWT | `lm_` + `eyJ…` | variable | Admin, account and user permission sets | Logged-in browser sessions |
| Popout Token | `lm_pop_` | 71 | Narrow subset of the creator's permissions | OBS browser sources, dashboard popout windows |
| Overlay Token | `lm_overlay_` | 75 | none | Per-overlay browser-source access |
| Shared Overlay Token | `lm_share_` | 73 | none | Time-limited shared overlay links |
| Extension Token | `lm_ext_` | 71 | none | Extension iframe access to its own install data |
| Widget Token | `lm_widget_` | 74 | none | Per-widget-instance browser-source access |
| Anonymous | - | - | none | No credential presented |

Every non-JWT token is a prefix plus 32 random bytes hex-encoded (64 characters). Only the SHA-256 hash is stored; the raw value is shown once at creation.

### Channels being dissolved

While a channel is scheduled for dissolution (`dissolution_scheduled_for` set), the auth middleware checks the resolved credential right after resolution. Credentials bound to that channel - User API Keys, Service Keys, Popout, Overlay, Shared Overlay, Widget and Extension Tokens - are refused with `403 CHANNEL_DISSOLVING` (`details.dissolution_scheduled_for` names the date). They are not revoked and work again once the owner cancels the dissolution. A member's JWT session keeps its identity but holds no account permission for the channel: permission-gated routes answer `403 CHANNEL_DISSOLVING` (GraphQL `extensions.code`), while user-level routes - profile, `me` with the account list, switching and leaving accounts, the owner's cancel - keep working. The WebSocket upgrade is refused for every credential of the channel, sessions included. See [REST API → Channels being dissolved](./rest-api.md#channels-being-dissolved).

## Transports

Two transports are accepted, and **what each accepts differs**:

| Context | `Authorization: Bearer …` | `?token=…` query param |
|---------|---------------------------|------------------------|
| System Key (`lm_sys_`) | ✓ | ✗ |
| User API Key (`lm_usr_`) | ✓ | ✗ |
| Service Key (`lm_svc_`) | ✓ | ✗ |
| Developer API Key (`lm_dev_`) | ✓ | ✗ |
| JWT (`lm_eyJ…`) | ✓ | ✓ |
| Popout Token (`lm_pop_`) | ✗ | ✓ |
| Overlay Token (`lm_overlay_`) | ✓ | ✓ |
| Shared Overlay Token (`lm_share_`) | ✓ | ✓ |
| Extension Token (`lm_ext_`) | ✓ | ✓ |
| Widget Token (`lm_widget_`) | ✓ | ✓ |

Long-lived service credentials (System keys, User API keys) are header-only on purpose: query strings end up in access logs, browser history, and `Referer` headers. The query-param path exists because the browser `WebSocket` API cannot set custom headers.

Resolution is ordered: the `Authorization` header is inspected first and, when it carries a recognised prefix, that result is final - a `?token=` value is not consulted as a fallback. An unrecognised or invalid credential resolves to `Anonymous` rather than an error.

## Rate Limits

Limits are per auth context, fixed per tier - they are not derived from the account's plan.

| Context | Requests / minute |
|---------|-------------------|
| System Key | unlimited (rate limiting skipped) |
| User API Key | 1200 |
| JWT | 600 |
| Popout / Overlay / Shared Overlay / Extension / Widget Token | 600 |
| Anonymous | 120 |

Popout tokens are keyed on the SHA-256 hash of the token, so several popout tokens on the same account get independent buckets - one overactive OBS browser source cannot starve the account's other popouts.

Anonymous requests are keyed on a client IP the caller cannot forge: Cloudflare's `CF-Connecting-IP`, else the peer address. `X-Forwarded-For`, `X-Real-IP` and `X-Lumio-Client-IP` never choose the bucket of a direct request. An IPv6 client is counted per `/64` network, an IPv4 client per address.

A valid `X-Internal-Token` (our own Next.js servers calling the API) grants **no** exemption. An anonymous call our web, admin or id app makes on a visitor's behalf is counted in the `proxied:{ip}` bucket of the visitor IP it forwards in `X-Lumio-Client-IP`, at 600 requests / minute. That is more than a direct anonymous caller gets, because one server-rendered page view makes several API calls, and it is a separate bucket, so it never adds to that IP's direct budget. An internal call that forwards no visitor (background or build-time traffic) shares one `internal:anon` bucket of 1200 requests / minute. The forwarded IP is trusted only together with the internal token and only when it parses as an IP address. Authenticated internal calls are counted per credential as usual.

Inbound webhook receivers under `/v1/webhooks/*` are **not** rate limited: they live in a dedicated scope outside the limiter and are gated by per-platform signature verification instead. Platform deliveries arrive from a shared pool of the platform's own IPs, so the per-IP anonymous bucket would throttle every tenant's callbacks into a single 120/min cap (ZAF-1519). See [Webhooks → Rate limiting](/features/webhooks#rate-limiting--webhook-receivers-are-exempt).

## JWT (JSON Web Tokens)

Issued by the ID app (NextAuth) and validated by the API. A JWT resolves to the `User` context and carries three separate permission sets: `admin_permissions` (from admin roles), `account_permissions` (from the active account's role), and `user_permissions` (cross-account, non-admin - e.g. Ideas Hub).

```
Authorization: Bearer lm_eyJ...
```

The token may carry a `session_id` referencing the `sessions` row for the request. A JWT is tagged with its **use**: `access` (authorizes any REST/GraphQL/WebSocket request), `ws` (authorizes **only** the `/v1/ws` upgrade), or `refresh` (accepted only at `/auth/refresh`). The `issueWsToken` mutation (REST twin `POST /v1/auth/ws-token`) mints a dedicated **`ws`** JWT that deliberately carries **no** `session_id` and a short TTL (`auth.ws_token_expiration`, ~15 min), so a leaked WebSocket URL cannot be replayed against a REST/GraphQL mutation or a session-management endpoint. Raw JWTs passed in the `?token=` query string are honored only on the WebSocket upgrade path.

## User API Keys

Long-lived keys (`lm_usr_`) for programmatic access, created from **Settings → Channel → Access → API Keys** (or through the API key endpoints). The full key is shown once, only its hash is stored, and each key carries an explicit permission scope that can never exceed what its creator held at creation time. A personal key is **member-bound**: it stops authenticating once its owner is no longer a member of the key's account (removing the member purges their personal keys, and the auth layer refuses any `lm_usr_` key whose owner has left the account). For a credential that must outlive team changes, use an account-owned Service Key (`lm_svc_`) instead.

```
Authorization: Bearer lm_usr_...
```

`GET /v1/tokens/me` (and GraphQL `myPermissions`) returns the caller's **effective** permissions - a scoped key reports exactly its own scope, never a wildcard.

## Session-only Surfaces

A small class of operations defines **who you are**, **mints a credential**, or **moves money**. They accept **only an interactive sign-in session** (the JWT the ID App issues at login, which is bound to a revocable session row through its `session_id`). A user JWT that carries no `session_id` is not a session and is refused like an API key. A user's own API key (`lm_usr_`) is refused here **regardless of its scopes**, as is every token type and every system / service / developer key:

| Operation | REST | GraphQL |
|-----------|------|---------|
| Link or reconnect a login provider | `POST /v1/auth/link` | – (REST only; called by the ID App) |
| Switch or clear the active account | `PATCH /v1/users/me` with `active_account_id` / `clear_active_account` | `updateMe(input: { activeAccountId })` / `updateMe(input: { clearActiveAccount })` |
| Rearrange or remove login identities | `POST /v1/accounts/login-assignments`, `DELETE /v1/accounts/login-assignments/{provider}`, `DELETE /v1/login-connections/{id}`, `PUT /v1/users/me/name-source-connection`, `PATCH /v1/users/me/display-name`, `POST`/`DELETE /v1/users/me/avatar` | `assignLoginConnection`, `removeLoginAssignment`, `disconnectLoginConnection`, `setNameSourceConnection`, `updateDisplayName`, `removeAvatar` (the upload has no GraphQL twin) |
| Change the channel's name or picture (also needs `account:edit` and the active channel) | `PUT /v1/accounts/{id}/identity-source`, `PATCH /v1/accounts/{id}/name`, `POST`/`DELETE /v1/accounts/{id}/avatar` | `setAccountIdentitySource`, `updateAccountName`, `removeAccountAvatar`, deprecated `updateAccount` (the upload has no GraphQL twin) |
| Mint a WebSocket JWT | `POST /v1/auth/ws-token` | `issueWsToken` |
| Mint / rotate a personal API key | `POST /v1/api-keys`, `POST /v1/api-keys/{id}/rotate` | `createUserApiKey`, `rotateUserApiKey` |
| Mint / rotate an account service key | `POST /v1/service-keys`, `POST /v1/service-keys/{id}/rotate` | `createAccountServiceKey`, `rotateAccountServiceKey` |
| Mint a developer key | `POST /v1/developer/api-keys` | `createDeveloperApiKey` |
| Start a channel / bot OAuth connect | `GET /v1/connections/channel/{platform}/authorize`, `GET /v1/bot-connections/{platform}/authorize` | `authorizeChannel`, `authorizeBot` |
| Complete a channel / bot OAuth connect | `POST /v1/connections/oauth/{platform}/exchange`, `POST /v1/connections/channel/{platform}/exchange`, `POST /v1/bot-connections/{platform}/exchange` | – (REST only; called by the web callback) |
| Set the payout destination (Stripe Connect onboarding) | `POST /v1/developer/stripe-connect/onboard` | – (REST only) |
| Change developer payout settings | `POST /v1/developer/payouts` | `updateDeveloperPayoutSettings` |
| Request a developer payout | `POST /v1/developer/payouts/request` | `requestPayout` |
| Start a plan checkout, open the billing portal, cancel the subscription | `POST /v1/billing/checkout`, `POST /v1/billing/portal`, `POST /v1/billing/cancel` | `createCheckout`, `createPortal`, `cancelSubscription` |

A WebSocket JWT carries the user's full permission set, so an API key cannot mint one - present the `lm_usr_` key itself on `/v1/ws` (`Authorization` header). The popout ws-token path (`POST /v1/auth/popout/ws-token` / `issuePopoutWsToken`) is separate and unaffected. Popout-token creation (`POST /v1/tokens` / `createPopoutToken`) is **not** session-only: an API key may mint a popout token, capped to the key's own scopes.

A leaked or over-scoped API key therefore cannot redirect payouts or change billing. The money reads stay open to a user's own API key with the right scope: `GET /v1/developer/stripe-connect/status`, `GET /v1/developer/payout-settings` / `developerPayoutSettings`, payout history, revenue and the billing status / invoice reads. The billing mutations check the session before they check whether billing is enabled, so an API key always gets the session refusal.

Only the `active_account_id` and `clear_active_account` fields of `PATCH /v1/users/me` / `updateMe` are session-only (`email` is refused for every caller with `400 EMAIL_MANAGED_BY_LOGIN`; the profile email is set by the email sign-in) - an API key can still change the other profile fields (streamer mode, display preferences), and the response never carries a `token` for a non-session caller.

**A session JWT is only minted for a caller that already holds a session (ZAF-1922).** The account switch / clear above, account creation and account dissolution each hand back a replacement JWT bound to the caller's existing session (`lo_auth::reissue_session_token`). Creating an account (`POST /v1/accounts` / `createAccount`) and dissolving one (`DELETE /v1/accounts/{id}`) are not session-only - they run under their usual guards - but a caller without an interactive session gets `token: null`; GraphQL `dissolveAccount` returns no token at all.

Refusals are identical on both protocols: anonymous → `401` / `UNAUTHENTICATED` (`Authentication required`); any other credential → `403` / `FORBIDDEN` with `This action requires an interactive sign-in session`.

The channel / account-bot OAuth exchange is additionally **bound to the session that started it**: the authorize step records the signed-in user on the server-side `state` handle, and the exchange completes only for that same user's session, re-checking account access and the connect permission (`connections:create` / `bot-connections:create`). Any other caller is refused before a connection row is written, and the single-use `state` is spent. The admin global-bot connect is exempt: it returns through the web host, where the browser session is never an admin session, and only the admin-only authorize step can start it.

## Developer API Keys

Long-lived publishing credentials (`lm_dev_`) for extension developers - the key `lumio deploy` and CI use instead of a personal `lm_usr_` key. A developer key is deliberately **narrow** and differs from every other credential in three ways:

- **Bound to a developer identity, not an account or a member.** It is owned by a developer **profile** or a developer **team** (exactly one), and carries **no account** and **no member identity** - so it can never satisfy an account-scoped check and, like a Service Key, keeps authenticating after the member who minted it leaves the team.
- **Plan-decoupled.** Eligibility is *approved-developer status* (an existing developer profile / team membership), **not** the Pro plan. The `feature:extension_development` account plan gate does not apply to a developer key - free-tier developers keep publishing when API keys are Pro-only.
- **Scoped to `extension-dev:*` only.** A developer key can carry **only** the `extension-dev:*` permission family (`read`, `create`, `edit`, `delete`, `publish`, `analytics`, `payouts`) - never an ordinary account scope such as `chat:ban` and never a user-scoped scope such as `ideas:*`. Scopes can never exceed what the creator held at mint time.

It reaches the **extension-developer publishing routes and nothing else**: listing / reading / updating / deleting its own extensions, versions (create / upload / list), analytics, limits, purchases, testers, screenshots and the extension's secrets (`GET/PUT/DELETE …/secrets`; secrets belong to the extension, not to an account). It is refused (fail-closed) from:

- the **first-party developer surface** - developer profile, payout settings, revenue, payout requests and limit requests (these key off the acting logged-in user), plus `create` / `submit` / `invite tester` / `request deletion` (they require a first-party user);
- **developer-key management itself** - a `lm_dev_` key can never mint or revoke another developer key, and minting one requires an interactive sign-in session (see [Session-only Surfaces](#session-only-surfaces)).

Manage developer keys from **Settings → You → Developer → Developer keys** (`/dashboard/settings/developer/keys`; REST `/v1/developer/api-keys`, GraphQL `developerApiKeys` / `createDeveloperApiKey` / `updateDeveloperApiKey` / `revokeDeveloperApiKey`). The full key is returned once at creation and only its hash is stored.

```
Authorization: Bearer lm_dev_...
```

## System Keys

Service identities that are not bound to an account: a system key can act on any account, but only within the scopes it carries. Two provisioning surfaces resolve to the same `System` context: static keys from TOML configuration (an empty list in the deployed API - every live system key is admin-provisioned), and admin-provisioned keys stored in `api_keys` with `is_system = true`. System keys are the only contexts that legitimately hold `resource:*` or `*:*` grants.

Internal System surfaces check a **named grant**, not the key type alone: the bot fleet's feeds, the bot chat ingest, extension functions on any install, draft extension files and bundles, and the WebSocket `presence:*` / `sounds:*` channels require `bots:internal` (a [system-key-only permission](./permissions.md#system-key-only-permissions)), the audit ingest requires `audit:ingest`. The GraphQL `SystemGuard` takes the grant as an argument (`SystemGuard::new(grant)`); there is no type-only form. A system key without the grant is refused with `403` / `Missing permission: …`.

```
Authorization: Bearer lm_sys_...
```

## Popout Tokens & Popout Sessions

Popout tokens (`lm_pop_*`) back OBS browser sources and dashboard popout windows. Unlike overlay tokens they carry a **narrow RBAC permission subset** (never more than their creator holds) rather than being bound to a single overlay.

The raw token appears **only** in the very first page request. On that first load a popout page **exchanges** it once, server-side, for a short-lived **popout session**; the page then redirects to the token-less URL and every subsequent proxied API call, WebSocket subscription, and SSR fetch authenticates through the session cookie. The raw `lm_pop_*` token is never forwarded to a proxied API call - proxy auth reads the session cookie only, so a logged-in operator can never be downgraded to token-scoped rights by a `?token=` left in a URL.

```
POST /v1/auth/popout/exchange        { "token": "lm_pop_..." }
# or GraphQL: mutation { exchangePopoutToken(token: "lm_pop_...") { token expiresAt accountId } }
```

- The response returns an `lm_`-prefixed **session JWT** and also sets it as an httpOnly cookie `lumio-popout-token` (`Path=/`, `SameSite=Lax`, `Secure` outside development, `Max-Age` = 15 min). Store it as an httpOnly cookie - never expose it to client-side JavaScript.
- The session resolves to the **same** popout auth context as the raw token (identical account, permission subset, and OBS credential gate) - it is **not** a full user session, so it cannot escalate to the delegated user's roles.
- **TTL is 15 minutes.** When it expires, the popout page transparently re-exchanges the still-valid raw `lm_pop_*` token for a fresh session. Every request additionally revalidates the origin token (revoked, expired, deleted), so deleting or revoking the popout token kills active sessions immediately; an open WebSocket closes on its next 30-second [credential re-validation](./websocket.md#credential-re-validation), or with `TOKEN_EXPIRED` when its session JWT expires.
- Possession of a valid `lm_pop_*` token IS the authorization - the exchange endpoint has no permission guard, since presenting the raw popout token has always been proof of access. A revoked, expired, unknown, or non-popout token - or one assigned to a member who has left the account - is rejected with `Invalid or expired popout token`.
- **WebSocket credential.** A popout mints its `/v1/ws` token via `issuePopoutWsToken` (REST twin `POST /v1/auth/popout/ws-token`) - **not** `issueWsToken`, which is session-only (ZAF-469 / ZAF-1742) and rejects a popout. The popout mint carries the popout's **own** permission subset (never the account owner's), a WebSocket-only use tag, and no `session_id`, so the API honors it **only** on the `/v1/ws` upgrade path.

```
Authorization: Bearer <popout-session-jwt>   # forwarded from the httpOnly cookie
```

- **Profile writes: exactly two, both one-way.** A popout session is read-only for the represented user's profile (`updateMe` / `PATCH /v1/users/me` are first-party gated and reject it) with two deliberate exceptions for the seasonal look: **dismiss the season banner** (`popoutDismissSeasonBanner` / `POST /v1/auth/popout/season-banner/dismiss`) and **switch the seasonal look off** (`popoutSwitchOffSeasonLook` / `POST /v1/auth/popout/season-look/off`). Both only append a `<seasonId>:<year>` instance to `season_banner_dismissed`; the second also sets `season_look_enabled = false`. No popout path can switch the look back on or change strength, motion, creatures, language or any other field - that stays in dashboard Settings. These two routes are **popout-only**: anonymous gets `401`, every other credential (user session, API key, overlay, shared-overlay, widget, extension) `403 This endpoint requires a popout session`.

**Member-bound.** A popout token bound to a member stops working once that member is no longer part of the account: removing the member (or the member leaving) deletes the popout tokens assigned to them for that account, and the raw-token resolver, the exchange, the popout-session resolver and the WebSocket re-validation additionally refuse any token whose assigned member is neither a current member nor the owner of the token's account.

**Always bound to an explicit user (ZAF-1922).** Every popout token resolves to the user it is bound to - creating without a user binds the creator, unassigning binds the editor - and there is no fallback to the account owner. A token row with no bound user is rejected by the raw-token resolver, the exchange and the WebSocket re-validation like an invalid token.

A popout token's `user_id` is the user it is bound to, not the person presenting it, so first-party routes that treat the user id as the acting principal (profile edits, session revocation, notifications, developer application, account dissolution) use `first_party_user_id()` instead - that accessor returns a value only for `User` and `ApiKey` contexts and rejects the whole token class.

## Overlay Tokens

Per-overlay access tokens for OBS browser sources, bound 1:1 to a specific overlay row. They carry no RBAC permissions: `has_permission()` returns `false` for every input, and they cannot reach REST or GraphQL resources. Their sole capability is subscribing to the `overlay:{key}` WebSocket channel whose resolved overlay matches the token's `overlay_id`.

```
?token=lm_overlay_...
Authorization: Bearer lm_overlay_...
```

Sessions authenticated with an overlay token are re-validated against the database every 30 seconds, like every token-authenticated WebSocket session (see [Credential re-validation](./websocket.md#credential-re-validation)); a rotated, revoked or deleted token is disconnected with `TOKEN_REVOKED`.

## Shared Overlay Tokens

Time-limited links for sharing an overlay with collaborators or a backup streaming setup, without granting account access. Same capability envelope as an overlay token, plus an `expires_at`. Expiry is checked on every 5-second heartbeat tick (`TOKEN_EXPIRED`) and revocation on the 30-second [credential re-validation](./websocket.md#credential-re-validation) (`TOKEN_REVOKED`).

## Extension Tokens

Short-lived tokens (15-minute TTL, auto-refreshed via `postMessage`) issued to an extension iframe. Scoped to a single extension installation: `extension_id`, `install_id`, and `account_id`. They carry no RBAC permissions - capability comes from the permissions the extension declared in `lumio.config.json` and was granted at install time, plus access to the installation's isolated storage.

## Widget Tokens

Per-widget-instance access tokens for browser sources, bound 1:1 to a `widget_id`. No RBAC permissions; the sole capability is subscribing to the `widget:{widget_instance_id}` WebSocket channel matching the bound widget.

## Anonymous

The fallback context when no credential is presented or the presented credential does not resolve. Anonymous callers reach only explicitly public surfaces (health probes, public plan/provider reads, the fonts proxy, platform webhooks, and WebSocket channels whose gate is `Public` or `PublicWhenFeature`).

## RBAC

Authenticated requests are subject to role-based access control using `resource:action` permission strings, checked by `require_permission()` (REST), `PermissionGuard` (GraphQL), and the channel gate (WebSocket). See [Permissions](./permissions.md) for the full registry and [Feature Flags](/admin/feature-flags) for feature-level access control.

---

## API Reference / Permissions

Source: https://docs.lumio.vision/api-reference/permissions

# Permissions

Lumio uses role-based access control (RBAC) to manage what each team member can do within an account.

## How It Works

Each account has **roles** (e.g., Owner, Administrator, Moderator). Each role has a set of **permissions**. When a user performs an action, the system checks if their role grants the required permission.

Permission checks run on **all four protocol surfaces** with the same `resource:action` strings:

- **REST** - `require_permission()` in route handlers
- **GraphQL** - `PermissionGuard` on resolvers
- **WebSocket** - channel-subscribe gate in `crates/lo-websocket/src/gate.rs`
- **Frontend** - `<Gate permission>` and `hasPerm()` in client code

The WebSocket layer maps each channel type to one of several gate kinds - a `resource:action` permission on the account in the channel name, a user-scoped permission, plain account scoping, a bound token type, or public. Most account-scoped streams use a `:read` permission (`chat:{account_id}` → `chat:read`, `events:{account_id}` → `events:read`). See [WebSocket → RBAC gate](./websocket.md#rbac-gate-subscribe-time) for the full mapping. A caller that fails the gate receives `code: "UNAUTHORIZED"` on subscribe.

## Default Roles

Three roles are seeded for every new account, in this sort order: Owner, Administrator, Moderator. Accounts created earlier may have a fourth role named `viewer`: unused roles were deleted, while roles with a member or a redeemable invite are ordinary custom roles with unchanged permissions.

### Owner (`owner`)
Full account access. System role (`is_system: true`, cannot be deleted). Holds every account permission - the list is loaded explicitly, not via a wildcard.

### Administrator (`administrator`)
Everything Owner holds **except** `account:delete`, `plan:read`, `plan:edit`, and `extension-dev:payouts`. Account dissolution and plan changes are additionally enforced through an `owner_id` check rather than a permission.

### Moderator (`moderator`)
Chat moderation, event monitoring, Spotify playback control, and read access across the rest of the account.

| Category | Permissions |
|----------|------------|
| Events | `events:read`, `events:create`, `events:edit`, `events:userinfo` |
| Overlays | `overlays:read` |
| Spotify | `spotify:read`, `spotify:playback`, `spotify:queue`, `spotify:playlist`, `spotify:device` |
| Chat | `chat:read`, `chat:write`, `chat:userinfo`, `chat:delete`, `chat:ban`, `chat:timeout`, `chat:notes`, `chat:raid`, `chat:pin`, `chat:refresh_user`, `chat:poll`, `chat:prediction`, `chat:automod-read`, `chat:automod-allow`, `chat:automod-deny` |
| Connections | `connections:read` |
| Uploads | `uploads:read` |
| Rewards | `rewards:read` |
| Automations | `automations:read`, `automations:execute` |
| Members & Roles | `members:read`, `roles:read` |
| OBS | `obs:read` |
| Copyright | `copyright:vote`, `copyright:report`, `copyright:recommend` |
| Bot | `bot-modules:read`, `bot-connections:read`, `bot-commands:read`, `chat-bots:read` |
| Extensions | `extension-store:read`, `extension-store:review`, `extension-data:read` |
| Widgets | `widgets:read` |
| Sounds | `sounds:read`, `sounds:play` |
| Stream History | `history:read`, `history:export` |
| Setting Presets | `presets:share` |
| Public Stats | `public-stats:read` |

Custom roles can be created under **Dashboard > Settings > Roles**.

## Permission Reference

The account registry holds **133** permissions, pinned by `account_permission_infos_has_expected_count` in `crates/lo-auth/src/rbac.rs`. One is assignable and seeded on the default roles but the API does not re-check it - the dashboard `<Gate permission>` hides the UI, but the endpoints do not gate on them, so assigning or withholding them changes nothing on the API surface:

| Permission | Where it takes effect |
|-----------|----------------------|
| `events:userinfo` | Dashboard only - `<Gate permission>` hides the UI; the API does not re-check it |

> `sessions:read`/`sessions:delete`, `automations:history`, and `events:delete` were **removed** from the account registry in ZAF-1094 - they gated nothing (session management is self-scoped, there is no automation-history surface, and only the system retention sweep deletes events). `copyright:report`/`copyright:recommend` are **not** unenforced: they carry a `PermissionGuard` on the GraphQL mutations `createCopyrightReport` / `createSafeRecommendation`. There is simply no dedicated REST route - reporting and recommending both go through `POST /v1/copyright/vote` under `copyright:vote`.

The account role editor (`GET /v1/roles/permissions` and the GraphQL `accountPermissions` query) exposes **exactly** the account permissions listed below - the picker and the create/update validation registry share one source of truth (`get_all_account_permission_infos()`), so every permission you can assign is visible and vice-versa (ZAF-231). The admin panel's per-user and per-account permission-override pickers draw from the same source via the `adminAssignablePermissions` query (proxied as `GET /api/assignable-permissions`), so they list this exact set too and cannot drift (ZAF-430).

### Events
| Permission | Description |
|-----------|-------------|
| `events:read` | View events, notifications, and event history |
| `events:create` | Send test events and manage notifications |
| `events:edit` | Edit stored events: hide the buyer name of a Shopify order (`hideShopifyOrderName`, `POST /v1/connections/shopify/events/{event_id}/hide-name`). Owner and Administrator |
| `events:userinfo` | View user cards and profiles from event entries |

### Overlays
| Permission | Description |
|-----------|-------------|
| `overlays:read` | View overlay configurations |
| `overlays:create` | Create new overlays |
| `overlays:edit` | Edit existing overlays |
| `overlays:delete` | Delete overlays |
| `overlays:access-read` | Read per-overlay access entries/candidates and see all overlays (access-manager visibility) |
| `overlays:access-grant` | Grant (set) per-overlay access for a user |
| `overlays:access-revoke` | Revoke per-overlay access for a user |

### Widgets
| Permission | Description |
|-----------|-------------|
| `widgets:read` | View widget instances |
| `widgets:create` | Create and duplicate widget instances |
| `widgets:edit` | Edit widget configuration |
| `widgets:delete` | Delete widget instances |
| `widgets:access-read` | Read per-widget access entries/candidates and bypass per-widget restrictions (access-manager visibility) |
| `widgets:access-grant` | Grant (set) per-widget access for a user |
| `widgets:access-revoke` | Revoke per-widget access for a user |

### Extension Data
Gates **direct** account-actor calls to an installed extension's server functions (dashboard editor, `lumio run` CLI). Widget runtime calls authenticated by an Extension Token are governed by the install's own scope and are not gated by these permissions.

| Permission | Description |
|-----------|-------------|
| `extension-data:read` | Read installed-extension data via query functions (`queryRows`, query-category handlers) |
| `extension-data:edit` | Mutate installed-extension data via `insertRow` / `patchRow` / `deleteRow` and mutation/action handlers |

### Spotify
| Permission | Description |
|-----------|-------------|
| `spotify:read` | View now playing state, queue, devices, playlists, and search tracks |
| `spotify:playback` | Control playback: play, pause, skip, previous, seek, shuffle, repeat |
| `spotify:volume` | Change playback volume (gates the volume slider in the dashboard and popout player) |
| `spotify:queue` | Add tracks to the playback queue |
| `spotify:playlist` | Manage playlists: create, rename, delete, add/remove tracks, start playlist playback |
| `spotify:device` | Transfer playback between Spotify devices |
| `spotify:worker` | Start and stop the manual Spotify worker connect |

### Chat
| Permission | Description |
|-----------|-------------|
| `chat:read` | View chat messages, history, and emotes |
| `chat:write` | Send chat messages |
| `chat:userinfo` | View user profiles, follow status, and moderation log |
| `chat:delete` | Delete chat messages |
| `chat:ban` | Ban and unban users |
| `chat:timeout` | Timeout users |
| `chat:notes` | View and manage user notes |
| `chat:raid` | Cancel active raids |
| `chat:pin` | Pin, re-time and unpin Twitch chat messages |
| `chat:poll` | End active polls |
| `chat:prediction` | End active predictions |
| `chat:refresh_user` | Manually refresh a user's platform profile data |
| `chat:automod-read` | View Twitch messages held by AutoMod in the live chat and, with `history:read`, in a session's AutoMod log |
| `chat:automod-allow` | Allow a held Twitch message with the acting member's own Twitch sign-in |
| `chat:automod-deny` | Deny a held Twitch message with the acting member's own Twitch sign-in |

### Connections
| Permission | Description |
|-----------|-------------|
| `connections:read` | View connected platforms, credentials and live channel status (`channelStatus`, `GET /v1/channel-status`) |
| `connections:create` | Connect new platforms |
| `connections:edit` | Change connection settings: the Shopify customer label and order details (`updateShopifySettings`, `PUT /v1/connections/shopify/settings`) |
| `connections:delete` | Disconnect platforms |

### Settings
| Permission | Description |
|-----------|-------------|
| `settings:read` | View account settings |
| `settings:edit` | Modify account settings |

### Automations
| Permission | Description |
|-----------|-------------|
| `automations:read` | View automations and their configuration, and the handler logs of automation-node extension installs |
| `automations:create` | Create new automations |
| `automations:edit` | Edit automation metadata, nodes, edges |
| `automations:delete` | Delete automations |
| `automations:execute` | Manually trigger and start/stop automations |

### Members
| Permission | Description |
|-----------|-------------|
| `members:read` | View the members list and all invitations |
| `members:create` | Create invites, search users for direct invites |
| `members:edit` | Change member roles, create/edit/delete custom roles |
| `members:delete` | Remove members from the account, revoke pending invites |

### Uploads
| Permission | Description |
|-----------|-------------|
| `uploads:read` | View uploaded files |
| `uploads:create` | Upload new files |
| `uploads:delete` | Delete uploaded files |

### Rewards
| Permission | Description |
|-----------|-------------|
| `rewards:read` | View channel point rewards |
| `rewards:create` | Create new rewards |
| `rewards:edit` | Edit existing rewards |
| `rewards:delete` | Delete rewards |

### Tokens
| Permission | Description |
|-----------|-------------|
| `tokens:read` | View popout tokens |
| `tokens:create` | Create popout tokens |
| `tokens:edit` | Edit popout tokens |
| `tokens:delete` | Revoke popout tokens |

### API Keys
Personal **user API keys** (`lm_usr_…`) and account **service keys** (`lm_svc_…`) share one dedicated permission family, separate from popout tokens.

| Permission | Description |
|-----------|-------------|
| `apikeys:read` | View API keys (personal `lm_usr_` and account service `lm_svc_`) |
| `apikeys:create` | Create an API key (personal or account service key) |
| `apikeys:edit` | Rename an API key (label only) **and rotate its secret** |
| `apikeys:delete` | Revoke an API key |

A key **owner** can **rotate** their own key's secret under `apikeys:edit` - GraphQL `rotateUserApiKey` / `rotateAccountServiceKey`, REST `POST /v1/api-keys/{id}/rotate` / `POST /v1/service-keys/{id}/rotate`. Rotation regenerates the secret in place (id, label and scopes unchanged) and returns the new full key exactly once. Creating or rotating an account service key requires an interactive sign-in session and the caller must hold every permission carried by the key, including on rotation. API keys cannot mint or rotate service keys. (Scopes themselves stay immutable on the owner surface - see below.) Platform operators can additionally manage **any** account's/user's keys, including editing scopes, under the distinct admin-scope [`account-apikeys:*`](#admin-account--user-api-keys) family.

`tokens:create`, `tokens:edit` and `apikeys:create` only let a caller mint or edit a token/key **within their own permissions**: it can never be granted a permission the caller does not currently hold. Requesting one is rejected with `FORBIDDEN`, identically on GraphQL and REST. A key or popout token that mints or edits a credential grants from its own **capped** scope (see [API Keys](#api-keys)), so a scope that went dormant after a demotion cannot be copied onto a new credential. A `resource:*` grant (system keys only) lets the caller grant any action under that resource; a bare `*:*` / `*` is not a global wildcard (it grants nothing beyond a literal `*:*` / `*`).

**API-key scope registry (ZAF-1169).** Unlike popout tokens - which keep a deliberately narrow, fixed list - an API key may carry **any permission the account/user behind it holds**, minus a small deny-list. The assignable-scope registry is derived from the RBAC registries and exposed on both protocols (GraphQL `apiKeyAssignablePermissions(kind)` / REST `GET /v1/api-keys/permissions?kind=personal|service|developer`), guarded on `apikeys:read` + `feature:apikeys`:

- **Personal keys** (`lm_usr_`) can be assigned the account permissions **and** the user-scoped `ideas:*` family below - a personal key carries its member's user identity, so it can exercise user-scoped permissions (this is enforced end-to-end: `require_user_permission` accepts a personal API key that holds the scope).
- **Service keys** (`lm_svc_`) can be assigned the account permissions only - an account-owned key has no user identity, so user-scoped permissions are meaningless on it and are never offered or honoured.
- **Developer keys** (`lm_dev_`, ZAF-1176) can be assigned the **`extension-dev:*` family only** (derived from the account registry by prefix) - never an ordinary account scope such as `chat:ban`, never a user-scoped scope such as `ideas:*`. A developer key is a narrow publishing credential bound to a developer profile or team; it is minted from `/v1/developer/api-keys` (not the `/v1/api-keys` surface) and is **not** gated on `feature:apikeys`.
- **Deny-list (all kinds), never assignable:** `apikeys:create`, `apikeys:edit`, `tokens:create` (credential minting - a key that mints credentials would outlive the human it belongs to) and `account:delete` (tenant destruction).

Requested scopes are validated against this registry on create - an unknown or deny-listed string is rejected with `Invalid permission: {perm}` (the same message role writes use), **before** the subset check. Scopes are **immutable after creation**; a too-narrow key must be re-minted.

### Account
| Permission | Description |
|-----------|-------------|
| `account:read` | View account settings and information |
| `account:edit` | Edit account settings: the channel name/picture source, own name and own picture (`/v1/accounts/{id}/identity-source`, `/name`, `/avatar`), etc. |
| `account:delete` | Dissolve (permanently delete) the account |

### Plan
| Permission | Description |
|-----------|-------------|
| `plan:read` | View account plan and billing information |
| `plan:edit` | Change account plan, manage subscription |

### Login Assignments

Assignable to account roles, but enforced at the user level: own assignments are always allowed for any authenticated user, and these permissions only gate actions taken on behalf of *other* users on the account.

| Permission | Description |
|-----------|-------------|
| `login-assignments:read` | View login assignments for the active account. Own assignments are always visible without this permission. |
| `login-assignments:create` | Assign a login connection to an account on behalf of another user. Own assignments are always allowed without this permission. |
| `login-assignments:delete` | Remove a login assignment for the active account on behalf of another user. Own assignments are always removable without this permission. |

### Sessions

Session management is **not** an account-role permission. Every authenticated user can view and revoke their **own** active browser sessions regardless of account role (and with no active account selected). The surface is own-scoped on both GraphQL (`sessions` / `deleteSession` / `deleteAllOtherSessions`) and REST (`GET` / `DELETE /v1/users/me/sessions`): the acting user's own id selects the rows, and the only gate is the first-party principal check (ZAF-469 / ZAF-516). The former `sessions:read` / `sessions:delete` role permissions were **removed** in ZAF-1094 - they gated nothing.

### Extension Developer

Extension developer permissions gate access to the developer dashboard and extension management. They are assignable to account roles and are also exercised through developer team RBAC. See [Team-Scoped Permissions](#team-scoped-permissions-developer-teams) for the team permission model. This is also the **entire** scope surface of a developer API key (`lm_dev_`): such a key can carry any subset of this family and nothing else (ZAF-1176).

| Permission | Description |
|-----------|-------------|
| `extension-dev:read` | View extension developer dashboard and owned extensions |
| `extension-dev:create` | Create new extensions |
| `extension-dev:edit` | Edit owned extensions (metadata, code, assets) |
| `extension-dev:delete` | Delete owned extensions |
| `extension-dev:publish` | Submit extensions for review and publish approved versions |
| `extension-dev:analytics` | View extension analytics (installs, usage, ratings) |
| `extension-dev:payouts` | Manage extension revenue payouts |

### Sounds
| Permission | Description |
|-----------|-------------|
| `sounds:read` | View sounds |
| `sounds:create` | Upload sounds |
| `sounds:edit` | Edit sound metadata |
| `sounds:delete` | Delete sounds |
| `sounds:play` | Play sounds in browser sources |

### Bot Modules
| Permission | Description |
|-----------|-------------|
| `bot-modules:read` | View bot module configurations, and the handler logs of bot-module extension installs |
| `bot-modules:edit` | Edit bot module configurations |

### Copyright
| Permission | Description |
|-----------|-------------|
| `copyright:read` | View safe/blocked songs, copyright check results |
| `copyright:edit` | Add to this account's safe/blocked lists, import playlists |
| `copyright:delete` | Remove entries from safe/blocked lists |
| `copyright:vote` | Vote on community copyright-status candidates |
| `copyright:report` | Report a song's copyright status - GraphQL `createCopyrightReport` (`PermissionGuard`); no dedicated REST route (reporting goes through `POST /v1/copyright/vote` under `copyright:vote`) |
| `copyright:recommend` | Recommend songs for the global list - GraphQL `createSafeRecommendation` (`PermissionGuard`); no dedicated REST route (recommending goes through `POST /v1/copyright/vote` under `copyright:vote`) |

`copyright:moderate` is **not** an account permission - it is admin-scope (platform operator). See [Admin: Copyright Moderation](#admin-copyright-moderation). It was moved out of account scope in ZAF-742 because approving/dismissing vote candidates writes the account-less **global** catalogue.

### OBS
| Permission | Description |
|-----------|-------------|
| `obs:read` | View OBS integration configuration and status |
| `obs:edit` | Edit OBS integration settings and remote control |
| `obs:delete` | Delete the account's OBS integration configuration |

### Roles
| Permission | Description |
|-----------|-------------|
| `roles:read` | View account roles and the assignable-permission catalog |
| `roles:edit` | Create and edit custom account roles |
| `roles:delete` | Delete custom account roles (system roles are protected server-side) |

Role create/update validates every permission string against the account registry. A wildcard (`resource:*` / `*:*`) is rejected on both REST and GraphQL and can never be persisted into an account role.

### Bot Commands
| Permission | Description |
|-----------|-------------|
| `bot-commands:read` | View chat commands and their per-platform overrides |
| `bot-commands:create` | Create chat commands |
| `bot-commands:edit` | Edit chat commands and set overrides |
| `bot-commands:delete` | Delete chat commands and clear overrides |

### Account Chat Bots
| Permission | Description |
|-----------|-------------|
| `chat-bots:read` | Read the account bot list and automatically recognised bots (Owner, Administrator, Moderator) |
| `chat-bots:edit` | Mark or unmark a platform account as a bot (Owner and Administrator) |

These account-scoped permissions govern [Channel settings → Bots](../user-guide/channel-settings.md#bots) and the GraphQL/REST account-bot endpoints. They are separate from `bot-connections:*`, which manages the channel's connected bot identity.

### Bot Connections
| Permission | Description |
|-----------|-------------|
| `bot-connections:read` | View the account's custom bot identities |
| `bot-connections:create` | Start and complete the custom bot OAuth flow |
| `bot-connections:delete` | Remove a custom bot identity |

Declared in **both** account and admin scope with the same string; the admin-scope copy gates system-level bot connections through `require_admin_permission`.

### StreamElements
| Permission | Description |
|-----------|-------------|
| `se-tokens:read` | View stored StreamElements JWT tokens |
| `se-tokens:create` | Store a StreamElements JWT token |
| `se-tokens:delete` | Delete a stored StreamElements JWT token |

### Extension Store
| Permission | Description |
|-----------|-------------|
| `extension-store:read` | Browse the extension store and view installed extensions |
| `extension-store:install` | Install an extension into the account |
| `extension-store:uninstall` | Uninstall an extension from the account |
| `extension-store:configure` | Change an installed extension's configuration |
| `extension-store:review` | Write store reviews and ratings |

### Stream History
| Permission | Description |
|-----------|-------------|
| `history:read` | View stream/session history, reports and stats; also unlocks the current paid subscriber count on `channelConnections.paidSubscriberCount` / `GET /v1/connections/channel?include=paid_subscriber_count` (`null` without it) |
| `history:share` | Create, extend and revoke shareable report links |
| `history:export` | Export filtered history lists and finalized reports (CSV/PDF/TXT/JSON) |
| `history:delete` | Delete stored history sessions |
| `history:revenue-read` | View estimated revenue, its converted amounts and assumptions; allow revenue in share links |
| `history:revenue-edit` | Edit revenue assumptions |
| `history:keywords-edit` | Add, change or remove tracked chat keywords; `history:read` permits listing and pattern tests |

Default roles: **Owner** and **Administrator** hold all seven; **Moderator** holds `history:read` + `history:export`. Gated behind the `feature:stream_history` feature flag.

### Setting Presets
| Permission | Description |
|-----------|-------------|
| `presets:share` | Share one of your own setting presets with the members of your active account |

Default roles: **Owner**, **Administrator** and **Moderator** hold it. Only the *act of sharing* is gated - creating/editing/loading presets is user-scoped and needs no permission, and reading the shared section needs only account membership. Gated behind the `feature:setting_presets` feature flag.

### Public Stats
| Permission | Description |
|-----------|-------------|
| `public-stats:read` | View this account's channel publicness settings for the public Stats app |
| `public-stats:edit` | Toggle a channel's publicness / chatter-leaderboard suppression (opt-out / opt-in) |

Default roles: **Owner** and **Administrator** hold both; **Moderator** holds `public-stats:read`. Gated behind the `feature:public_stats_page` feature flag.

> **Crawler control moved to admin scope (ZAF-725).** The five `crawler:*`
> permissions that steer the platform-wide stats crawler are **admin-scope**
> (platform-operator) permissions, not account permissions - see
> [Admin: Crawler](#admin-crawler) below.

### Audit Log
| Permission | Description |
|-----------|-------------|
| `audit-log:read` | Read this account's audit log (`GET /v1/account/audit-log` / `accountAuditLog`) - role/permission changes, member-role assignment, channel connections |

Default roles: **Owner** and **Administrator** hold it; **Moderator** does not. This account-scope `audit-log:read` is a **distinct** permission from the identically-named admin-scope `audit-log:read` (see [Admin: Support, Audit & StreamElements](#admin-support-audit--streamelements)): the account grant reads a single account's log through `require_permission`, the admin grant reads the operator audit surface through `require_admin_permission`, and holding one never unlocks the other.

## Admin-Scope Permissions

Admin-scope permissions are checked against a user's **admin role** (not their account role). They gate the Lumio admin panel - `/admin`. The dashboard entry gate is `admin:access`, which is automatically included in every admin role.

> **Note:** Some permissions (marked below) share an identical string with an account-scope permission but are enforced in a different context (`require_admin_permission` vs `require_permission`). This mirrors the `bot-connections:*` precedent.

### Admin: Core Access
| Permission | Description |
|-----------|-------------|
| `admin:access` | Dashboard entry gate. Auto-injected into every admin role. Not a tenant bypass: it grants no access to another account's account-scoped surfaces (WebSocket channels, login assignments, OAuth callbacks). |

### Admin: Role Management
| Permission | Description |
|-----------|-------------|
| `admin-roles:read` | View admin roles, their permissions, and member lists |
| `admin-roles:create` | Create new admin roles |
| `admin-roles:edit` | Edit role name, description, permissions, and user assignments |
| `admin-roles:delete` | Delete admin roles (`is_system` roles are protected server-side) |

### Admin: Privacy
| Permission | Description |
|-----------|-------------|
| `admin:privacy-erase` | Erase persisted personal data on one channel's instruction (GDPR Art. 17). Powers `DELETE /v1/admin/privacy/youtube/member/{id}` (clears Lumio's cached YouTube member records across all accounts, and erases the member's chat data in the instructing account only) and `POST /v1/admin/privacy/chat/erase` (erases a data subject's chat messages, profile, moderator notes, AutoMod and moderation-log rows, bot-list entry and stream-history entries in the instructing account only, by Lumio user id or `platform`+`user_id`; both require `account_id` and `instruction_reference`, the chat erasure also `reason`), `POST /v1/admin/privacy/lumio/erase` (erases a person on Lumio's own surfaces only: the Lumio Stats suppression entry and, on YouTube, Lumio's member cache; no channel data; requires `instruction_reference` and `reason`), `POST /v1/admin/privacy/records/erase` (erases one record in the instructing account: a chat message, moderator note, moderation-log entry, AutoMod-log entry, bot-list entry or one person in one stream report; requires `account_id`, `instruction_reference` and `reason`), and `POST /v1/admin/storage/orphaned-extension-uploads/sweep` (finds - and with `apply` queues for deletion - extension upload files no row references any more). The chat, Lumio-only and record erasures are also available in the admin app under **Moderation → Privacy Erasure** (`/privacy-erasure`). Reserved for support tooling; assigned only to `system_admin`. |
| `admin:privacy-objection-create` | Record a chatter's GDPR Art. 21 objection in the global `chatter_suppressions`: the public Stats leaderboard masks the chatter on read, also on streams published earlier; channel reports, share links and AutoMod logs are not affected, and nothing is erased. Powers `POST /v1/admin/privacy/chat/objections` / GraphQL `addChatterObjection`. Assigned only to `system_admin`. |
| `admin:privacy-objection-delete` | Lift a recorded chatter objection (never an erasure entry). Powers `DELETE /v1/admin/privacy/chat/objections/{platform}/{user_id}` / GraphQL `removeChatterObjection`. Assigned only to `system_admin`. |
| `admin:privacy-erase-withdraw` | Withdraw one channel's erasure instruction for one chatter: deletes the chatter's row in that account's `account_chatter_suppressions`, so the channel's later reports name them again; nothing the erasure deleted comes back. Powers `POST /v1/admin/privacy/chat/erase/withdraw` / GraphQL `withdrawChannelChatterSuppression`. Assigned only to `system_admin`. |

### Admin: Developer Verifications
| Permission | Description |
|-----------|-------------|
| `developer-verification:read` | View developer applications and their details |
| `developer-verification:edit` | Approve or reject developer applications |

### Admin: Feature Flags
| Permission | Description |
|-----------|-------------|
| `features:read` | View feature flags |
| `features:edit` | Toggle feature flags |
| `feature-flags:read` | View the feature-flag registry detail view |
| `feature-flags:edit` | Edit feature-flag metadata (category, description, plan defaults) |

### Admin: Users & Accounts
| Permission | Description |
|-----------|-------------|
| `users:read` | View users, login connections, and membership details |
| `users:edit` | Edit user display name, email, overrides, and manage login connections |
| `users:delete` | Delete users |
| `accounts:read` | View account details, limits, features |
| `accounts:edit` | Update account name, plan, limits, feature overrides, members, and reconnect flags |
| `accounts:delete` | Delete accounts |
| `accounts:overrides-read` | Read per-account permission overrides |
| `accounts:overrides-edit` | Set or remove per-account permission overrides |

### Admin: Providers & Platforms
| Permission | Description |
|-----------|-------------|
| `providers:read` | View platform provider configurations |
| `providers:edit` | Toggle providers and sub-flags |
| `platforms:read` | View platform connection configuration |
| `platforms:edit` | Edit platform connection configuration |

### Admin: Infrastructure
| Permission | Description |
|-----------|-------------|
| `system-keys:read` | View system API keys; also reads the assignable-scope registry (`adminSystemKeyPermissions` / `GET /v1/admin/system-key-permissions`, ZAF-1213) |
| `system-keys:create` | Create system API keys (scopes validated against the derived assignable-scope registry, ZAF-1213) |
| `system-keys:delete` | Delete system API keys |
| `oauth-clients:read` | View OAuth client registrations |
| `oauth-clients:create` | Create OAuth clients |
| `oauth-clients:edit` | Edit OAuth clients |
| `oauth-clients:delete` | Delete OAuth clients |
| `system-connections:read` | View system-level platform connections |
| `system-connections:edit` | Create and update system-level platform connections |
| `system-connections:delete` | Delete system-level platform connections |

### Admin: Account & User API Keys
Platform-operator management of **any** account's or user's API keys - personal `lm_usr_` keys (in `api_keys`) and account service `lm_svc_` keys (in `account_service_keys`) - for support and incident response. Admin-scope (checked via `require_admin_permission` / `AdminPermissionGuard`), seeded to `system_admin`. This is a **distinct** family from the account-scope [`apikeys:*`](#api-keys), which manages the caller's **own** keys; holding one never grants the other.

| Permission | Description |
|-----------|-------------|
| `account-apikeys:read` | View any account's / user's API keys (never the secret) |
| `account-apikeys:edit` | Edit an API key's label and scopes |
| `account-apikeys:rotate` | Regenerate an API key's secret (new plaintext returned once) |
| `account-apikeys:delete` | Revoke (delete) any API key |

Scope edits validate against the ZAF-1170 assignable-scope registry for the key's kind (rejecting unknown, deny-listed, or user-scoped-on-service scopes). For a **personal** key the scopes are additionally capped to the key **owner's** own grantable permissions; for a **service** key the account is the principal, so the registry minus the deny-list is the ceiling - an operator can never push a key above its own principal. The rotated plaintext secret is returned exactly once, never in a list, never logged. Every operator action emits a **system-scope** audit event (`system:api_key_updated` / `system:api_key_rotated` / `system:api_key_revoked`) with the operator as the actor; these rows never surface in the target account's or user's own log. See [Admin: API Keys](../admin/api-keys.md).

### Admin: Developer Funds

| Permission | Description |
|---|---|
| `developer-funds:release-deletion` | Release a developer balance Lumio cannot pay out (no payout method, identity not verified) as a liability and delete the profile or the user, on the person's request. Always combined with the delete permission (`users:delete` or `developer-verification:edit`) and an interactive session. |
| `developer-funds:settle` | Record that a person presented the claim code of a released developer balance, and credit that balance to their new, verified developer profile. Interactive session required. |

Admin scope, seeded to `system_admin` by `20261025200000_developer_released_balances` (`release-deletion`) and `20261025210000_developer_funds_settle_permission` (`settle`); never an account-role permission. GraphQL `adminReleaseFundsAndDeleteUser` / `adminReleaseFundsAndDeleteDeveloper` use `AdminPermissionGuard` plus the shared `services::developer_funds_release::require_operator`; the REST twins call the same helper. GraphQL `adminStartReleasedBalanceClaim` / `adminSettleReleasedBalance` use `AdminPermissionGuard(DEVELOPER_FUNDS_SETTLE)` plus `services::developer_funds_settlement::require_operator`; the REST twins `POST /v1/admin/released-balances/{claim,settle}` call the same helper.

### Admin: Contract Declarations

The withdrawal and cancellation queue spans all accounts. These are admin-scoped grants, seeded to `system_admin`; they are not account-role permissions.

| Permission | Description |
|---|---|
| `contract-declarations:read` | List and inspect declarations across accounts. |
| `contract-declarations:edit` | Match an open public case, close a case, or extend retention; each mutation also requires an interactive session. |

The admin page is [Contract Declarations](/admin/contract-declarations). REST uses `require_admin_permission`; GraphQL uses `AdminPermissionGuard`, with matching permission strings.

### Admin: Billing, Plans & Coupons
| Permission | Description |
|-----------|-------------|
| `billing:read` | View billing data |
| `billing:edit` | Modify billing data |
| `plans:read` | View plans |
| `plans:create` | Create plans |
| `plans:edit` | Edit plans and their feature mappings |
| `plans:delete` | Delete plans |
| `subscriptions:read` | View subscriptions |
| `subscriptions:edit` | Modify subscriptions |
| `coupons:read` | View coupons |
| `coupons:create` | Create coupons |
| `coupons:edit` | Edit coupons |
| `coupons:delete` | Delete coupons |

### Admin: Bot Control & Commands
| Permission | Description |
|-----------|-------------|
| `bot-control:read` | View bot enabled/disabled status across all accounts |
| `bot-control:edit` | Toggle the bot on or off for an account |
| `bot-commands:read` | View chat commands across all accounts |
| `bot-commands:create` | Create chat commands on any account |
| `bot-commands:edit` | Edit chat commands on any account |
| `bot-commands:delete` | Delete chat commands on any account |
| `bot-connections:read` | View system bot connections |
| `bot-connections:create` | Create system bot connections |
| `bot-connections:delete` | Delete system bot connections |
| `discord-guilds:read` | View Discord guild connections across all accounts |
| `discord-guilds:delete` | Delete a Discord guild connection |

### Admin: Support, Audit & StreamElements
| Permission | Description |
|-----------|-------------|
| `support:read` | View support tickets |
| `support:edit` | Handle support tickets |
| `support:verify` | Reveal or check a user's hourly support code and read recent checks; admin scope only. GraphQL and REST use the same admin guard. |
| `audit:read` | Read the audit log |
| `audit:ingest` | Server-to-server user-scope audit ingest - the narrow grant `apps/id` needs to write `user:login` / `user:oauth_granted` to `POST /v1/internal/audit-ingest`. Declared in the admin registry so the [system-key mint](../admin/system-keys.md) accepts it, but **system-key-only in effect**: `authorize_ingest` requires an `AuthContext::System`, so a human admin holding it in a role can never write. Never seeded into any admin role (ZAF-1212). |
| `audit-log:read` | Read the admin (system-scope) audit log (`GET /v1/admin/audit-log`). Distinct from the identically-named **account-scope** [`audit-log:read`](#audit-log), which reads a single account's log via `require_permission`; this admin copy is checked via `require_admin_permission` and holding one never unlocks the other. |
| `csp-reports:read` | Read the CSP-violation calibration aggregate - `cspViolationReports` / REST `GET /v1/admin/csp-reports`. Distinct `(violated_directive, blocked_host)` pairs with counts, from the capped `csp_violation_reports` TimescaleDB table (≤5000 pairs, ≤30 d rolling). Admin-scope (platform operator) - seeded to `system_admin`, not assignable to any tenant role (ZAF-1051). |
| `devtools:read` | Open the Dev & Admin menu in the web app (`lumio.vision`, production included). A pure UI-visibility grant: the web app reads it from `me { adminPermissions }` / REST `GET /v1/users/me` (`admin_permissions`) - both resolve the same admin-role rows - and no resolver or route is guarded on it. The menu's actions (e.g. previewing a seasonal look) change only the viewer's own browser and are never sent to the server, so it emits no audit event. Admin-scope (platform operator) - seeded to `system_admin`, assignable to further admin roles via [Admin Roles](../admin/admin-roles.md), not assignable to any tenant role (ZAF-1668). |
| `se-tokens:read` | View StreamElements tokens across all accounts |
| `se-tokens:delete` | Delete a StreamElements token on any account |

### Admin: Extensions & Developers
| Permission | Description |
|-----------|-------------|
| `extension-review:read` | View the extension review queue and submission details |
| `extension-review:edit` | Approve, reject, or request changes on extension submissions |
| `developer-limits:read` | View developer rate limits and quotas |
| `developer-limits:edit` | Edit developer rate limits and quotas |
| `extension-purchases:read` | Read paid extension checkouts across all accounts that were never delivered - GraphQL `adminUndeliveredExtensionPurchases` / REST `GET /v1/admin/extension-purchases/undelivered` ([Admin › Extension Purchases](../admin/extension-purchases.md)). Admin scope - seeded to `system_admin`, not assignable to any tenant role (ZAF-2745). |

### Admin: Ideas Moderation
| Permission | Description |
|-----------|-------------|
| `ideas:moderate_read` | View all ideas with moderation details (reports, flags, internal notes) |
| `ideas:moderate_status` | Change idea status (approve, reject, mark as planned, close) |
| `ideas:moderate_edit` | Edit any idea regardless of ownership |
| `ideas:moderate_delete` | Delete any idea regardless of ownership |
| `ideas:moderate_comment` | Delete any comment on ideas regardless of ownership (comment editing is author-only) |

### Admin: Copyright Moderation
| Permission | Description |
|-----------|-------------|
| `copyright:moderate` | Approve/dismiss community vote candidates into the **global** cross-account safe/blocked catalogue (`approveReport`/`dismissReport` + REST `/v1/copyright/vote-candidates/{track_id}/approve`·`/dismiss`). Admin-scope (platform operator) - seeded to `system_admin`, not assignable to any tenant role (ZAF-742). |

### Admin: User Roles
| Permission | Description |
|-----------|-------------|
| `user-roles:read` | View user roles and their permissions |
| `user-roles:create` | Create new user roles |
| `user-roles:edit` | Edit user role name, description, permissions, and assignments |
| `user-roles:delete` | Delete user roles (`is_system` roles are protected server-side) |

### Admin: Crawler
Platform-operator control of the public stats crawler - a single **global**
resource (one crawler, one global scope flip). Moved from account scope to admin
scope in ZAF-725; enforced via `require_admin_permission` / `AdminPermissionGuard`
and seeded to the `system_admin` role only.

| Permission | Description |
|-----------|-------------|
| `crawler:scope-read` | Read the public stats crawler's scope mode (`GET /v1/crawler/scope` / `crawlerScope`) |
| `crawler:scope-edit` | Set the crawl scope mode, incl. the opt-in `global` flip (`PUT /v1/crawler/scope` / `setCrawlerScope`) |
| `crawler:watchlist-read` | List the crawl watchlist (`GET /v1/crawler/watchlist` / `crawlerWatchlist`) |
| `crawler:watchlist-create` | Add a channel to the crawl watchlist (`POST /v1/crawler/watchlist` / `addCrawlerWatchlistChannel`) |
| `crawler:watchlist-delete` | Remove a channel from the crawl watchlist (`DELETE /v1/crawler/watchlist/{platform}/{platform_channel_id}` / `removeCrawlerWatchlistChannel`) |

Actions are granular (the coarse `:manage` is disallowed); each scope change or watchlist mutation emits a **system-scope** audit event. The Admin app additionally gates entry on `admin:access`.

### Admin: Shared with Account Scope
Seventeen permission strings are declared in **both** admin scope and account scope. They share the same string value but are enforced by different guards (`require_admin_permission` against the user's admin role vs `require_permission` against their account role), so holding one does not grant the other:

| Permissions | Category |
|-------------|----------|
| `copyright:read`, `copyright:edit`, `copyright:delete` | Copyright |
| `obs:read`, `obs:edit` | OBS |
| `bot-modules:read`, `bot-modules:edit` | Bot Modules |
| `bot-commands:read`, `bot-commands:create`, `bot-commands:edit`, `bot-commands:delete` | Bot Commands |
| `bot-connections:read`, `bot-connections:create`, `bot-connections:delete` | Bot Connections |
| `se-tokens:read`, `se-tokens:delete` | StreamElements |
| `audit-log:read` | Audit Log |

## System-Key-Only Permissions

Grants that exist **only** for [system keys](../admin/system-keys.md). They are
listed in `lo_auth::rbac::system_key::SYSTEM_ONLY_PERMISSIONS`, offered by the
system-key mint registry (`adminSystemKeyPermissions` /
`GET /v1/admin/system-key-permissions`), and absent from the account, user and
admin (operator) registries - so no role can ever hold them: `create_role` /
`update_role` reject them as unknown permissions on both protocols. Each guarded
site checks them with `AuthContext::require_system_permission`, which requires a
System key **and** the grant.

| Permission | Description |
|-----------|-------------|
| `bots:internal` | The bot fleet's internal surface (ZAF-1922): GraphQL `botChannels`, `botCommandsForAccount`, `emitBotEvent`, `discordBotGuilds`, `discordBotGuildFeatures`, `discordBotAllGuildFeatures`, `updateDiscordGuildInfo`, `removeDiscordGuildByBot`, the bot chat ingest (`sendChatMessage` / `POST /v1/chat/message`) and the REST feeds `GET /v1/internal/bot-modules/{account_id}/triggers`, `GET /v1/internal/bot-modules/handlers`, `GET /v1/internal/automation-nodes/handlers`; and the cross-account extension and live surfaces (ZAF-1976): extension server functions on any install (`extensionQuery`, `extensionMutate`, `extensionExecuteHandler`; REST `POST /v1/extension-installs/{install_id}/{query,mutate,execute}/{function_name}`), draft/testing extension file trees (`extensionVersionFiles`; REST `GET /v1/extensions/{id}/versions/{version}/files`) and bundle bytes (`GET /v1/extension-bundles/...`), and the WebSocket `presence:*` and `sounds:*` channels. A non-System caller gets `FORBIDDEN` (`System access required`; REST feeds: `System key required for internal endpoints`); a System key without the grant gets `Missing permission: bots:internal`. Carried by the keys of `twitch-bot`, `kick-bot`, `youtube-bot`, `discord-bot`, `bot-module-worker` and `automation-worker`. |

`audit:ingest` (see [Admin: Support, Audit & StreamElements](#admin-support-audit--streamelements))
is system-key-only **in effect** by a different route: it is declared in the admin
registry, but its only consumer requires a System key.

## User-Scoped Permissions

User-scoped permissions are **global** - they are not tied to a specific account. They control access to platform-wide features that exist outside the account context, such as the Ideas Hub. User-scoped permissions are assigned via **user roles** (`user_roles` / `user_role_permissions`), not account roles. Enforcement uses `auth.require_user_permission()` on the backend, which is satisfied by a logged-in user session **or a personal API key** (`lm_usr_`) that carries the scope - a personal key acts with its member's user identity (ZAF-1169). An account **service key** (`lm_svc_`) has no user identity and is always rejected here, fail-closed.

### Ideas Hub

| Permission | Description |
|-----------|-------------|
| `ideas:read` | Read ideas |
| `ideas:create` | Create new ideas |
| `ideas:edit` | Edit own ideas |
| `ideas:delete` | Delete own ideas |
| `ideas:vote` | Vote on ideas |
| `ideas:comment_read` | Read comments on ideas |
| `ideas:comment_create` | Create comments on ideas |
| `ideas:comment_edit` | Edit own comments |
| `ideas:comment_delete` | Delete own comments |
| `ideas:comment_vote` | Vote on comments and replies |

### Default User Roles

Three system user roles are seeded by default:

#### Member

Assigned to all users automatically. Grants full Ideas Hub participation.

| Category | Permissions |
|----------|------------|
| Ideas | `ideas:read`, `ideas:create`, `ideas:edit`, `ideas:delete`, `ideas:vote` |
| Comments | `ideas:comment_read`, `ideas:comment_create`, `ideas:comment_edit`, `ideas:comment_delete`, `ideas:comment_vote` |

#### Restricted

Limited to read-only access.

| Category | Permissions |
|----------|------------|
| Ideas | `ideas:read` |
| Comments | `ideas:comment_read` |

#### Moderator

Full user permissions plus admin-level moderation capabilities. The five `ideas:moderate_*` permissions are admin-scoped - see [Admin: Ideas Moderation](#admin-ideas-moderation) above.

| Category | Permissions |
|----------|------------|
| Ideas | `ideas:read`, `ideas:create`, `ideas:edit`, `ideas:delete`, `ideas:vote` |
| Comments | `ideas:comment_read`, `ideas:comment_create`, `ideas:comment_edit`, `ideas:comment_delete`, `ideas:comment_vote` |
| Moderation (admin-scoped) | `ideas:moderate_read`, `ideas:moderate_status`, `ideas:moderate_edit`, `ideas:moderate_delete`, `ideas:moderate_comment` |

## Team-Scoped Permissions (Developer Teams)

Team-scoped permissions control what each member can do within a developer team. They are separate from both account-scope and admin-scope permissions and are defined in `crates/lo-auth/src/rbac.rs::team`. Team management uses `require_team_permission()` in REST and an equivalent GraphQL helper. Extension actions use the same shared team-role check on both protocols after ownership is established. That check reads the role from the database, so a role change applies on the next extension request. Missing grants return `403 Missing team permission: <permission>`; non-members fail the ownership check first.

### Extension Development

| Permission | Description |
|-----------|-------------|
| `team-extensions:create` | Create extensions within the team |
| `team-extensions:edit` | Update metadata; upload or delete icons and screenshots |
| `team-extensions:delete` | Delete a draft extension or request deletion |
| `team-extensions:publish` | Submit a version for review |
| `team-extensions:analytics` | View extension analytics |
| `team-versions:create` | Create or upload an extension version |
| `team-versions:edit` | Edit extension versions |

### Secrets

| Permission | Description |
|-----------|-------------|
| `team-secrets:read` | List the key names of a team extension's secrets (`…/secrets`, `developerExtensionSecrets`) |
| `team-secrets:edit` | Set or delete a team extension's secrets; create, rename and revoke the team's developer API keys |

### Testers

| Permission | Description |
|-----------|-------------|
| `team-testers:read` | List testers, private access grants, and access invites |
| `team-testers:invite` | Invite testers, grant private access, and create access invites |
| `team-testers:remove` | Remove testers, revoke private access, and delete access invites |

### Team Members

| Permission | Description |
|-----------|-------------|
| `team-members:read` | Read team member list |
| `team-members:invite` | Invite new team members |
| `team-members:edit` | Edit team member roles |
| `team-members:remove` | Remove team members |

### Team Settings

| Permission | Description |
|-----------|-------------|
| `team-settings:read` | Read team settings |
| `team-settings:edit` | Edit team settings |

### Payouts

| Permission | Description |
|-----------|-------------|
| `team-payouts:read` | Read team payout information |
| `team-payouts:edit` | Edit team payout configuration |

`team-versions:edit`, `team-settings:read`, and `team-payouts:read`/`team-payouts:edit` are present in the team-role catalogue, but no current extension action checks those grants. Assigning one does not grant a version-edit or payout action by itself.

### Default Team Roles

Three roles are seeded for every new developer team:

#### Owner (`team-owner`)

System role (cannot be deleted). All 20 team permissions.

#### Admin (`team-admin`)

Manage extensions and team members. All permissions except `team-settings:edit`, `team-payouts:edit`, and `team-members:remove`.

#### Member (`team-member`)

View and develop extensions. Permissions: `team-extensions:create`, `team-extensions:edit`, `team-extensions:analytics`, `team-versions:create`, `team-members:read`, `team-secrets:read`, `team-settings:read`.

Members can edit and create versions, but cannot submit, delete, manage private access or testers, or list testers without a custom role granting those actions. Solo extensions have no team-role gate. A developer API key bound to a team can act only on that team's extensions.

## Popout Tokens

Popout tokens inherit specific permissions when created. A popout token can only have permissions that the creating user's role grants. For example, a Moderator cannot create a popout token with `settings:edit`.

The `/popout/test-events` link needs `events:create` in its own permission list to show the catalog and send a test. The Events feed popout uses `events:read`. A token without `events:create` sees a permission notice on the test page and cannot send. `spotifyManualStatus` remains gated on `spotify:read`; live `channelStatus` uses `connections:read` on GraphQL and REST.

## Overlay Tokens

Overlay tokens (`lm_overlay_*`) have **no RBAC permissions**. They cannot access any REST or GraphQL endpoint. Their sole capability is subscribing to the `overlay:{key}` WebSocket channel where the token's bound `overlay_id` matches the resolved overlay key.

- `has_permission(_)` always returns `false`
- Cannot broadcast to any channel
- Cannot subscribe to any channel other than the one matching their bound overlay
- Rate-limited at 600 requests/min (same tier as Popout tokens)

## Shared Overlay Tokens

Shared overlay tokens (`lm_share_*`) provide temporary, time-limited access to a specific overlay. They are designed for sharing overlays with collaborators or backup streaming setups without granting permanent account access.

- Prefix: `lm_share_` (9 characters)
- Body: 32 random bytes, hex-encoded (64 characters)
- Total length: 73 characters
- Transport: `?token=lm_share_…` query parameter or `Authorization: Bearer lm_share_…` header
- Rate-limited at 600 requests/min (same tier as Popout and Overlay tokens)
- `has_permission(_)` always returns `false`
- Cannot access REST or GraphQL endpoints
- Can only subscribe to the `overlay:{key}` WebSocket channel matching the token's bound overlay
- Server checks expiry every heartbeat tick (5s) - disconnects with `TOKEN_EXPIRED` when elapsed
- Server checks DB revocation every 30 seconds - disconnects with `TOKEN_REVOKED` if revoked (the same [credential re-validation](./websocket.md#credential-re-validation) every token-authenticated WebSocket session gets)

### Token Types

| Type | Prefix | Length | Purpose |
|------|--------|--------|---------|
| System Key | `lm_sys_` | 71 | Internal service-to-service auth |
| User API Key | `lm_usr_` | 71 | External API access |
| JWT | `lm_` + `eyJ...` | variable | Session-based auth |
| Popout Token | `lm_pop_` | 71 | Overlay/popout access with a scoped permission subset |
| Overlay Token | `lm_overlay_` | 75 | Per-overlay browser source access |
| Shared Overlay Token | `lm_share_` | 73 | Temporary shared overlay link |
| Extension Token | `lm_ext_` | 71 | Extension iframe, scoped to one install |
| Widget Token | `lm_widget_` | 74 | Per-widget-instance browser source access |

Popout tokens accept an optional `expires_at`; absent or `null` means the token never expires. See [Authentication](./authentication.md) for transports and rate limits.

## Extension Permissions

Extension tokens (`lm_ext_*`) have no RBAC permissions (`has_permission()` always returns `false`). Instead, extensions declare required permissions in `lumio.config.json` and are granted only those capabilities at install time. The Lumio API validates each action call against the extension's declared permission set.

### Available Extension Permissions

The manifest validator accepts exactly these strings in `lumio.config.json` `permissions` - anything else fails validation at upload:

| Permission | Description | Review level |
|-----------|-------------|--------------|
| `events:read` | Read events from the Lumio event bus | Standard |
| `events:emit` | Emit custom events | Standard |
| `chat:read` | Read chat messages | Standard |
| `chat:send` | Send chat messages | Standard |
| `chat:delete` | Delete chat messages | Enhanced |
| `chat:ban` | Ban and unban users, timeout users | Enhanced |
| `obs:set_scene` | Switch the active OBS scene | Standard |
| `obs:set_source_visible` | Toggle OBS source visibility | Standard |
| `obs:start_stream` | Start the OBS stream | Standard |
| `obs:stop_stream` | Stop the OBS stream | Standard |
| `overlay:update_layer` | Update overlay layer properties | Standard |

**Enhanced review:** Extensions requesting `chat:ban` or `chat:delete` receive additional scrutiny during the approval process. Reviewers verify that the extension implements appropriate safeguards (e.g., confirmation prompts, configurable thresholds, exempt role support) and that the moderation logic does not create excessive false positives. The `chat:ban` permission grants `ban`, `unban`, and `timeout` capabilities through a single declaration.

### Action-to-declaration mapping

At call time, each action resolves to the manifest permission the install must have declared; an undeclared permission is rejected before the action runs:

| Action | Required declaration |
|--------|---------------------|
| `chat:send`, `chat:delete` | `chat:read` |
| `events:emit` | `events:read` |
| `overlay:update_layer` | `overlays:edit` |
| `obs:set_scene`, `obs:set_source_visible`, `obs:start_stream`, `obs:stop_stream` | `obs:control` |

`obs:control` and `overlays:edit` are the strings this mapping checks for; they are not among the values the manifest validator accepts, so the OBS and overlay-layer actions cannot currently be authorised through a validated manifest.

## API Keys

A User API key carries an explicit permission list stored on the key row. At creation that list can never exceed what the creator holds. On every request the key is also capped to its owner's **current** role: the auth middleware keeps only the stored scopes that the owner's account-role and user-scoped permissions still grant. A member demoted from Administrator to Viewer therefore loses every Administrator scope on their keys at the next request, and a re-promotion restores them, because the stored list is never rewritten. Popout tokens and popout sessions are capped to their bound member the same way. The ceiling comes from the same permission cache a signed-in session uses, so a role change or role edit reaches keys exactly as fast as it reaches the dashboard. If the ceiling cannot be read, the request fails with `503 authorization_unavailable`; it never falls back to the stored list. Account owners without a membership row are capped to the account's owner role. `GET /v1/tokens/me` (GraphQL `myPermissions`) reports the capped scope, never a wildcard. Key and popout-token responses carry both `permissions` (stored) and `effective_permissions` (what authorizes requests now); a stored scope missing from `effective_permissions` is dormant. Service keys (`lm_svc_`) and developer keys (`lm_dev_`) have no bound member and are not capped this way. Keys may carry an `expires_at`; an expired key resolves to `Anonymous` rather than erroring. Rate limits differ by auth type - see [Authentication](./authentication.md).

---

## Developer Guide / RBAC & Permissions

Source: https://docs.lumio.vision/developer-guide/rbac-permissions

# RBAC & Permissions

Lumio uses a role-based access control (RBAC) system with granular permissions. Every authenticated action is checked against the user's assigned role for the active account.

## Default Roles

Every new account is created with three default roles:

| Role | Slug | Color | `is_system` | `is_default` | Notes |
|------|------|-------|:-----------:|:------------:|-------|
| Owner | `owner` | `#f59e0b` | true | true | Every account registry permission, listed explicitly in `ROLE_OWNER`. Cannot be edited or deleted. |
| Administrator | `administrator` | `#ef4444` | false | true | Everything except `account:delete`, `plan:read`, `plan:edit`, and `extension-dev:payouts`. |
| Moderator | `moderator` | `#22c55e` | false | true | Chat moderation, event monitoring, read access (49 permissions). |

The role rows are seeded by `create_default_roles()` in `apps/api/src/db/roles.rs` from the `DEFAULT_ROLES` slice in `crates/lo-auth/src/rbac.rs`; `is_default` is set to `true` for all three at insert time.

### Role Properties

| Property | Type | Description |
|----------|------|-------------|
| `slug` | `string` | Machine-readable identifier. Stable, lowercase, used in code checks. Never changes. |
| `name` | `string` | Human-readable display name. Editable on custom roles, translated for default roles. |
| `is_system` | `bool` | Cannot be edited or deleted. Only the Owner role. |
| `is_default` | `bool` | Cannot be deleted. All three default roles have this set. |
| `color` | `string` | Hex color for UI display (e.g., `"#f59e0b"`). |

### Role Name Translation

Default role names are translated via the `useTranslateRole()` hook in `apps/web/src/lib/translate-role.ts`. The hook returns a `(slug, name) => string` function that checks if the slug matches a known default role and returns the localized name; custom roles fall back to their `name` field.

Translation keys live in `apps/web/messages/{en,de}.json` under `"roles.labels"`:

```json
{
  "roles": {
    "labels": {
      "owner": "Owner",
      "administrator": "Administrator",
      "moderator": "Moderator"
    }
  }
}
```

## Permission Format

All permissions follow the `resource:action` format. Examples:

- `events:read`, `events:create`
- `chat:ban`, `chat:timeout`, `chat:notes`
- `automations:execute`

### Rules

1. **Always granular.** Every resource needs at minimum `read` plus granular `create`/`edit`/`delete`.
2. **Domain-specific actions** are added when CRUD is insufficient (e.g., `automations:execute`, `chat:ban`).
3. **Never use wildcards.** No `resource:*` / `*:*` account-level permissions. Account actions are always granular verbs - there is no coarse `:manage` action; management surfaces are split into discrete permissions (for example `overlays:access-read` / `overlays:access-grant` / `overlays:access-revoke`).

## Account Permissions

The tables below summarize the major account permission categories. The authoritative list of constants lives in `crates/lo-auth/src/rbac.rs` (under `pub mod account {}`) - treat that file as the source of truth; categories and counts may shift as features evolve. The registry holds **133** account permissions across 31 categories (pinned by `account_permission_infos_has_expected_count`): API Keys, Account, Audit Log, Automations, Bot Commands, Bot Connections, Bot Modules, Chat, Connections, Copyright, Events, Extension Data, Extension Developer, Extension Store, Login Assignments, Members, OBS, Overlays, Plan, Public Stats, Rewards, Roles, Setting Presets, Settings, Sounds, Spotify, Stream History, StreamElements, Tokens, Uploads, Widgets. Crawler control belongs to admin scope (see [Admin-Scope Permissions → Crawler](#crawler-admin-scope)). For the complete permission-by-role matrix see [Complete Permissions Reference](./roles-permissions-guide.md#complete-permissions-reference).

`lo_auth::rbac::account::get_all_account_permission_infos()` is the **single source of truth** for the account permission set - it returns every account permission with its picker `label` and `category`. Both role-editor pickers (REST `GET /v1/roles/permissions` and GraphQL `availablePermissions`, both guarded on `roles:read`) map this list, and the create/update validation registry `get_all_account_permissions()` derives its key set from it. As a result the role editor exposes **exactly** the set of assignable permissions - there are no "shadow" permissions that validation accepts but the editor hides (ZAF-231).

The **admin-app permission-override pickers** derive from the same registry (ZAF-430). Both the per-user override picker (`/admin/users/[id]`) and the per-account override picker (`/admin/accounts/[id]`) fetch the registry from the API - the admin proxy `GET /api/assignable-permissions` calls the `adminAssignablePermissions` GraphQL query (guarded `admin:access`), which maps `get_all_account_permission_infos()`. They hold **no** hardcoded permission arrays, so a new registry key appears in every picker automatically and the admin pickers can never drift from validation. (Before ZAF-430 these two pickers carried hand-maintained copies of the registry that had silently drifted.)

### Events

| Permission | Label |
|-----------|-------|
| `events:read` | Read Events |
| `events:create` | Create Events |
| `events:edit` | Edit Events |
| `events:userinfo` | Event User Info |

### Overlays (7)

| Permission | Label |
|-----------|-------|
| `overlays:read` | Read Overlays |
| `overlays:create` | Create Overlays |
| `overlays:edit` | Edit Overlays |
| `overlays:delete` | Delete Overlays |
| `overlays:access-read` | Read Overlay Access |
| `overlays:access-grant` | Grant Overlay Access |
| `overlays:access-revoke` | Revoke Overlay Access |

### Widgets (7)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `widgets:read` | View Widgets | x | x | x |
| `widgets:create` | Create Widgets | x | x | |
| `widgets:edit` | Edit Widgets | x | x | |
| `widgets:delete` | Delete Widgets | x | x | |
| `widgets:access-read` | Read Widget Access | x | x | |
| `widgets:access-grant` | Grant Widget Access | x | x | |
| `widgets:access-revoke` | Revoke Widget Access | x | x | |

### Extension Data (2)

Gates direct account-actor calls to an installed extension's server functions. Widget-runtime calls made with an Extension Token use the install's own scope and are not checked against these permissions.

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `extension-data:read` | Read Extension Data | x | x | x |
| `extension-data:edit` | Edit Extension Data | x | x | |

### Spotify (7)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `spotify:read` | Read Spotify | x | x | x |
| `spotify:playback` | Spotify Playback | x | x | x |
| `spotify:volume` | Spotify Volume | x | x | |
| `spotify:queue` | Spotify Queue | x | x | x |
| `spotify:playlist` | Spotify Playlists | x | x | x |
| `spotify:device` | Spotify Devices | x | x | x |
| `spotify:worker` | Spotify Worker | x | x | |

### Chat (16)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `chat:read` | Read Chat | x | x | x |
| `chat:write` | Write Chat | x | x | x |
| `chat:userinfo` | Chat User Info | x | x | x |
| `chat:delete` | Delete Chat Messages | x | x | x |
| `chat:ban` | Ban Chat Users | x | x | x |
| `chat:timeout` | Timeout Chat Users | x | x | x |
| `chat:notes` | Chat User Notes | x | x | x |
| `chat:raid` | Cancel Raids | x | x | x |
| `chat:pin` | Manage Twitch chat pins | x | x | x |
| `chat:poll` | End Polls | x | x | x |
| `chat:prediction` | End Predictions | x | x | x |
| `chat:refresh_user` | Refresh User Profile | x | x | x |
| `chat:automod-read` | Read AutoMod Queue | x | x | x |
| `chat:automod-allow` | Allow Held Messages | x | x | x |
| `chat:automod-deny` | Deny Held Messages | x | x | x |

The live queue uses `chat:automod-read`; the session AutoMod log also needs `history:read`. Allow and deny use separate permissions and the acting member's Twitch login. Popout tokens can carry all three AutoMod permissions for the live chat, but cannot read the session log. AutoMod rows in `mergedChatHistory` and `GET /v1/chat/history/merged` require `feature:multichat`, `chat:read` and `chat:automod-read`; `history:read` permits the account's full chat plan window, otherwise the server returns only holds from the last 24 hours. Members, user and service keys, and popout tokens use that same window rule.

### Connections

| Permission | Label |
|-----------|-------|
| `connections:read` | Read Connections and channel live status (`channelStatus`, `GET /v1/channel-status`) |
| `connections:create` | Create Connections |
| `connections:edit` | Edit Connections |
| `connections:delete` | Delete Connections |

### Settings (2)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `settings:read` | Read Settings | x | x | |
| `settings:edit` | Edit Settings | x | x | |

### Members (4)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `members:read` | Read Members | x | x | x |
| `members:create` | Create Invites | x | x | |
| `members:edit` | Edit Members | x | x | |
| `members:delete` | Delete Members | x | x | |

### Roles (3)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `roles:read` | Read Roles | x | x | x |
| `roles:edit` | Edit Roles | x | x | |
| `roles:delete` | Delete Roles | x | x | |

### Uploads

| Permission | Label |
|-----------|-------|
| `uploads:read` | Read Uploads |
| `uploads:create` | Create Uploads |
| `uploads:delete` | Delete Uploads |

### Sounds (5)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `sounds:read` | Read Sounds | x | x | x |
| `sounds:create` | Upload Sounds | x | x | |
| `sounds:edit` | Edit Sounds | x | x | |
| `sounds:delete` | Delete Sounds | x | x | |
| `sounds:play` | Play Sounds | x | x | x |

### Stream History (7)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `history:read` | Read Stream History | x | x | x |
| `history:share` | Share History Reports | x | x | |
| `history:export` | Export History Reports | x | x | x |
| `history:delete` | Delete Stream History | x | x | |
| `history:revenue-read` | Read Estimated Revenue | x | x | |
| `history:revenue-edit` | Edit Revenue Assumptions | x | x | |
| `history:keywords-edit` | Edit Tracked Keywords | x | x | |

Gated behind the `feature:stream_history` feature flag.

### Setting Presets (1)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `presets:share` | Share Setting Presets | x | x | x |

Only the *act of sharing* a preset with your account is gated; creating/editing/loading presets is user-scoped (no permission), and reading the shared section needs only account membership. Gated behind the `feature:setting_presets` feature flag.

### Public Stats (2)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `public-stats:read` | Read Public Stats Settings | x | x | x |
| `public-stats:edit` | Edit Public Stats Settings | x | x | |

Gated behind the `feature:public_stats_page` feature flag.

> **Crawler control moved to admin scope (ZAF-725).** The five `crawler:*`
> permissions are no longer account permissions - steering the single global
> stats crawler is a platform-operator action, so they now live in `pub mod
> global` and are gated by `AdminPermissionGuard` / `require_admin_permission`.
> See [Admin-Scope Permissions → Crawler](#crawler-admin-scope).

### Audit Log (1)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `audit-log:read` | Read Audit Log | x | x | |

Reads this account's `scope=account` audit rows (`accountAuditLog` / `GET /v1/account/audit-log`). The identical string in `pub mod global {}` is a **separate** admin-scope permission for the system audit log - see [Admin-Scope Permissions](#admin-scope-permissions).

### Rewards

| Permission | Label |
|-----------|-------|
| `rewards:read` | Read Rewards |
| `rewards:create` | Create Rewards |
| `rewards:edit` | Edit Rewards |
| `rewards:delete` | Delete Rewards |

### Tokens

Popout tokens (OBS browser-source docks).

| Permission | Label |
|-----------|-------|
| `tokens:read` | Read Tokens |
| `tokens:create` | Create Tokens |
| `tokens:edit` | Edit Tokens |
| `tokens:delete` | Delete Tokens |

### API Keys

Personal user API keys (`lm_usr_…`) - a dedicated family, separate from popout tokens.

A personal key, a popout token and a popout session are **member-bound**: the auth middleware caps their stored scopes to the bound member's current account-role and user-scoped permissions on every request (`lo_api::middleware::auth::load_member_permission_ceiling`), through the same Redis permission cache `resolve_jwt` reads. Role changes and role edits already invalidate that cache, so they need no extra hook for credentials. A ceiling that cannot be loaded returns `AuthUnavailable` (`503`). Response objects expose the capped list as `effective_permissions` / `effectivePermissions` via `services::token_permissions::EffectivePermissions`. Service and developer keys have no member and are not capped.

| Permission | Label |
|-----------|-------|
| `apikeys:read` | Read API Keys |
| `apikeys:create` | Create API Keys |
| `apikeys:edit` | Edit API Keys |
| `apikeys:delete` | Delete API Keys |

### Automations (6)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `automations:read` | Read Automations | x | x | x |
| `automations:create` | Create Automations | x | x | |
| `automations:edit` | Edit Automations | x | x | |
| `automations:delete` | Delete Automations | x | x | |
| `automations:execute` | Execute Automations | x | x | x |

### Account (3)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `account:read` | Read Account | x | x | |
| `account:edit` | Edit Account | x | x | |
| `account:delete` | Delete Account | x | | |

### Plan (2)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `plan:read` | View Plan & Billing | x | | |
| `plan:edit` | Change Plan | x | | |

Both plan permissions are owner-only in the default roles - Administrator carries neither.

### User-Level Permissions

The following permission categories are tied to the authenticated **user identity** rather than to an account resource. **Own** actions (managing your own login assignments) are allowed regardless of account role. Because they live in the account permission registry, they are still assignable in the account role editor - the picker exposes the complete account registry (ZAF-231).

#### Sessions

Session management is **not** a role permission. Every authenticated user can view and revoke their **own** sessions regardless of account role: `sessions` / `deleteSession` / `deleteAllOtherSessions` (GraphQL) and `GET`/`DELETE /v1/users/me/sessions` (REST) select and delete strictly by the acting user's id, carrying `AuthGuard` plus the first-party check `lo_graphql::require_first_party_user()` (ZAF-469). The former `sessions:read` / `sessions:delete` account constants were **removed** in ZAF-1094 (ZAF-516) - they lived in the registry and seeded roles but no handler ever enforced them, since a user on their personal profile carries an empty `account_permissions` list.

#### Login Assignments (3)

Controls access to login assignment management. Own assignments are always allowed for any authenticated user regardless of role - the permissions below only gate actions performed on behalf of other users.

| Permission | Label |
|-----------|-------|
| `login-assignments:read` | Read Login Assignments |
| `login-assignments:create` | Create Login Assignments |
| `login-assignments:delete` | Delete Login Assignments |

### Extension Developer (7)

Extension developer permissions gate access to the developer dashboard, extension CRUD, publishing, analytics, and payouts. They are account-scope permissions and **are** seeded on the default roles: Owner carries all seven, Administrator carries all but `extension-dev:payouts`; Moderator carries none. Work performed *inside a developer team* is additionally checked against team-scope permissions (see [Team RBAC](#team-rbac-developer-teams) below).

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `extension-dev:read` | View Developer Dashboard | x | x | |
| `extension-dev:create` | Create Extensions | x | x | |
| `extension-dev:edit` | Edit Extensions | x | x | |
| `extension-dev:delete` | Delete Extensions | x | x | |
| `extension-dev:publish` | Publish Extensions | x | x | |
| `extension-dev:analytics` | View Extension Analytics | x | x | |
| `extension-dev:payouts` | Manage Extension Payouts | x | | |

### Extension Store (5)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `extension-store:read` | Browse Extension Store | x | x | x |
| `extension-store:install` | Install Extensions | x | x | |
| `extension-store:uninstall` | Uninstall Extensions | x | x | |
| `extension-store:configure` | Configure Extensions | x | x | |
| `extension-store:review` | Review Extensions | x | x | x |

### Copyright (6)

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `copyright:read` | View Copyright | x | x | |
| `copyright:edit` | Edit Copyright Lists | x | x | |
| `copyright:delete` | Delete Copyright Entries | x | x | |
| `copyright:vote` | Vote on Songs | x | x | x |
| `copyright:report` | Create Copyright Reports | x | x | x |
| `copyright:recommend` | Recommend Songs | x | x | x |

`copyright:moderate` is **not** in this account-role matrix - it is an **admin-scope** (platform-operator) permission, seeded to the `system_admin` admin role and not assignable to any tenant role. It governs the **global** community catalogue (approving/dismissing vote candidates into the cross-account blocked/safe lists); `copyright:edit` only touches the account's own lists. It was moved out of account scope in ZAF-742 (mirroring the ZAF-725 crawler move) because writing the account-less global catalogue is a platform-operator action.

### OBS, Bot Modules, Bot Commands, Bot Connections, StreamElements

| Permission | Label | Owner | Admin | Mod |
|-----------|-------|:-----:|:-----:|:---:|
| `obs:read` | View OBS Config | x | x | x |
| `obs:edit` | Edit OBS Config | x | x | |
| `obs:delete` | Delete OBS Config | x | x | |
| `bot-modules:read` | View Bot Modules | x | x | x |
| `bot-modules:edit` | Edit Bot Modules | x | x | |
| `bot-commands:read` | View Bot Commands | x | x | x |
| `bot-commands:create` | Create Bot Commands | x | x | |
| `bot-commands:edit` | Edit Bot Commands | x | x | |
| `bot-commands:delete` | Delete Bot Commands | x | x | |
| `chat-bots:read` | View Account Chat Bots | x | x | x |
| `chat-bots:edit` | Edit Account Chat Bots | x | x | |
| `bot-connections:read` | View Bot Connections | x | x | x |
| `bot-connections:create` | Create Bot Connections | x | x | |
| `bot-connections:delete` | Delete Bot Connections | x | x | |
| `se-tokens:read` | View SE Tokens | x | x | |
| `se-tokens:create` | Create SE Tokens | x | x | |
| `se-tokens:delete` | Delete SE Tokens | x | x | |

### Ideas Hub (User-Scoped)

The Ideas Hub introduces a **user-scoped permissions layer** that is distinct from both account-scoped and admin-scoped permissions. User-scoped permissions are global (not tied to a specific account) and are assigned via the `user_roles` and `user_role_permissions` tables.

Enforcement uses `auth.require_user_permission()`. The moderation checks use `has_moderate_permission()`, which accepts BOTH user-scoped and admin-scoped grants.

**User-scoped permissions:**

| Permission | Label |
|-----------|-------|
| `ideas:read` | Read Ideas |
| `ideas:create` | Create Ideas |
| `ideas:edit` | Edit Own Ideas |
| `ideas:delete` | Delete Own Ideas |
| `ideas:vote` | Vote on Ideas |
| `ideas:comment_read` | Read Comments |
| `ideas:comment_create` | Create Comments |
| `ideas:comment_edit` | Edit Own Comments |
| `ideas:comment_delete` | Delete Own Comments |
| `ideas:comment_vote` | Vote on Comments |

**Admin-scoped moderation permissions:**

| Permission | Label |
|-----------|-------|
| `ideas:moderate_read` | Read All Ideas (Admin) |
| `ideas:moderate_status` | Change Idea Status |
| `ideas:moderate_edit` | Edit Any Idea |
| `ideas:moderate_delete` | Delete Any Idea |
| `ideas:moderate_comment` | Delete Any Comment |

Admin-scoped moderation permissions are enforced via `auth.require_admin_permission()` and live in `crates/lo-auth/src/rbac.rs::global`.

## Admin-Scope Permissions

The admin-scope `support:verify` grant controls the Support Identity card on an admin user detail page. The reveal and check operations, and the recent-check list, use `AdminPermissionGuard` on GraphQL and `require_admin_permission` on REST. Revealing or checking a code emits a system-scope audit event; a failed code check is still recorded. The separate `users:edit` grant controls an operator's 2FA reset, which requires a reason. Neither grant can be supplied by an account role.

Admin-scope permissions gate the Lumio admin panel (`/admin`) and are entirely separate from account-scope permissions. They are stored in the `admin_permissions` column of `CachedPermissions` (not `account_permissions`) and enforced by `require_admin_permission()`.

### Permission Modules

The `crates/lo-auth/src/rbac.rs` file defines three permission modules:

- **`pub mod account {}`** - Account-scope permission constants (listed above)
- **`pub mod global {}`** - Admin-scope permission constants
- **`pub mod team {}`** - Team-scope permission constants (see [Team RBAC](#team-rbac-developer-teams))

Constants in `global` use the same `resource:action` format. The canonical list is exposed via:

```rust
lo_auth::rbac::all_admin_permissions() -> Vec<(&'static str, &'static str)>
// Returns (permission_string, category_label) pairs
```

This function is used by the permission picker UI and the REST/GraphQL permission validation.

### Admin Roles

Admin roles are managed in the `admin_roles` / `admin_role_permissions` / `user_admin_roles` tables; the seeded roles (`system_admin`, `support`, `billing`, …) and their grants are maintained by migrations such as `20260330000005_feature_flag_phase1` and `20260412000001_seed_admin_refactor_permissions`. Unlike account roles, admin roles:

- Are **global** (not account-scoped)
- Have `is_system: bool` - system roles cannot be deleted
- Auto-receive `admin:access` (the dashboard entry gate) on create **and** on update - both the REST handler and the GraphQL mutation push it back into the permission list if it is missing
- Are CRUD-managed via `adminRoles*` GraphQL mutations and `GET/POST/PATCH/DELETE /v1/admin/admin-roles`

### Shared Permissions

Some permission strings (e.g., `copyright:read`, `obs:read`, `bot-modules:read`) are declared in **both** `pub mod account {}` and `pub mod global {}` with identical string values. This is intentional - the same string gates different resources in different contexts:

- Account scope: enforced by `auth.require_permission(account::COPYRIGHT_READ)` in account route handlers
- Admin scope: enforced by `auth.require_admin_permission(global::COPYRIGHT_READ)` in admin route handlers

This follows the precedent set by `bot-connections:*`.

### `admin:access`

`admin:access` is the single gate that controls dashboard access. Any user without this permission sees a "No Access" page. It is:

- Always present in the `global` module as `admin::ACCESS`
- Auto-injected into every admin role at creation time (both REST and GraphQL mutation)
- Never removed by the permission diff algorithm
- **Not** a tenant bypass. `AuthContext::can_access_account` lets only System keys reach a foreign account. An operator session holding `admin:access` reaches only its own active account on every account-scoped check: WebSocket subscribes, login-assignment writes, and OAuth callbacks/exchanges. Admin features that legitimately span accounts (`/v1/admin/*`, `admin*` GraphQL) are gated on their own granular admin permission, such as `accounts:read` or `account-apikeys:rotate`. A new operator cross-tenant need gets its own dedicated admin permission key, seeded and checked at that call site, never `admin:access`.

### `admin:privacy-erase`

GDPR-Art-17 erasure tooling. It gates three surfaces, each with matching REST and GraphQL entry points:

| Surface | REST | GraphQL |
|---------|------|---------|
| YouTube member-badge erasure - clears Lumio's cached YouTube member-channel records across all accounts and erases the member's chat data in the instructing account only | `DELETE /v1/admin/privacy/youtube/member/{member_channel_id}` | `eraseYoutubeMemberData` |
| Chat-subject erasure - erases a chat subject's stored messages and profile data in the instructing account only (`account_id`, `instruction_reference` and `reason` required) | `POST /v1/admin/privacy/chat/erase` | `eraseChatSubjectData` |
| Lumio-only erasure - records a person's `erasure` entry for Lumio Stats and clears Lumio's YouTube member cache; touches no channel data (`instruction_reference` and `reason` required) | `POST /v1/admin/privacy/lumio/erase` | `eraseChatSubjectAtLumio` |
| Record erasure - erases one record (chat message, note, moderation-log entry, AutoMod-log entry, bot-list entry, or one person in one stream report) in the instructing account only (`account_id` + `instruction_reference` + `reason` required) | `POST /v1/admin/privacy/records/erase` | `eraseChatRecord` |
| Orphaned extension upload sweep - finds (dry run) or queues for deletion (`apply`) extension upload files no row references | `POST /v1/admin/storage/orphaned-extension-uploads/sweep` | `adminSweepOrphanedExtensionUploads` |

The erasure handlers check the permission by hand against the caller's `admin_permissions` (`lo_auth::rbac::global::ADMIN_PRIVACY_ERASE`) rather than via a route-level macro; the sweep uses the admin router's `require_permission` (REST) and `AdminPermissionGuard` (GraphQL) with the same string. It is seeded on the `system_admin` role only (migration `20260428000002_seed_admin_privacy_erase`) and is not auto-injected into any other admin role. The audit log records each erasure as one system-scoped event (`chat_pii_erasure`, or `youtube_member_erasure` for the member path).

### `admin:privacy-objection-create` / `admin:privacy-objection-delete`

GDPR-Art-21 objection tooling for Lumio's global suppression list (`chatter_suppressions`). Recording an objection keeps the chatter off every public Stats leaderboard (masked on read, so also on streams published earlier), without erasing anything; channel stream reports, exports, share links and AutoMod logs are not affected. Lifting it names the chatter again on the public leaderboard.

| Permission | REST | GraphQL |
|------------|------|---------|
| `admin:privacy-objection-create` | `POST /v1/admin/privacy/chat/objections` | `addChatterObjection` |
| `admin:privacy-objection-delete` | `DELETE /v1/admin/privacy/chat/objections/{platform}/{user_id}` | `removeChatterObjection` |

Both protocols check the permission by hand against the caller's `admin_permissions` (`require_admin_permission`, the same guard type as `admin:privacy-erase`) and share the validation in `ChatterObjection::from_parts`. Both are seeded on the `system_admin` role only (migration `20261015120000_create_chatter_suppressions`). The events are `privacy:chatter_objection_added` / `privacy:chatter_objection_removed` (system scope).

### `admin:privacy-erase-withdraw`

Withdraws one channel's erasure instruction for one chatter: deletes the chatter's row in that account's suppression list (`account_chatter_suppressions`), so the channel's stream reports frozen afterwards name them again. Nothing the erasure deleted or blanked is restored, and the global `chatter_suppressions` list is not touched. It is a separate permission from `admin:privacy-erase`, so an operator role can carry out erasures without being able to undo their suppression.

| Permission | REST | GraphQL |
|------------|------|---------|
| `admin:privacy-erase-withdraw` | `POST /v1/admin/privacy/chat/erase/withdraw` | `withdrawChannelChatterSuppression` |

Both protocols check it by hand against the caller's `admin_permissions` (`require_admin_permission`) with the same error code and text (`Forbidden: Missing required permission: admin:privacy-erase-withdraw`), and share the validation in `SuppressionWithdrawal::from_parts`. It is seeded on the `system_admin` role only (migration `20261022120000_admin_privacy_erase_withdraw`). The event is `privacy:channel_suppression_withdrawn` (system scope).

### Crawler (Admin Scope)

Platform-operator control of the public stats crawler (scope mode + watchlist).
Declared in `pub mod global`, surfaced by `all_admin_permissions()`, and seeded to
the `system_admin` admin role (migration `20260825000001_crawler_perms_to_admin_scope`).

| Permission | Label |
|-----------|-------|
| `crawler:scope-read` | Read Crawler Scope |
| `crawler:scope-edit` | Edit Crawler Scope |
| `crawler:watchlist-read` | Read Crawler Watchlist |
| `crawler:watchlist-create` | Add Crawler Watchlist Channels |
| `crawler:watchlist-delete` | Remove Crawler Watchlist Channels |

Actions are granular (the coarse `:manage` is disallowed); each mutation emits a
system-scope audit event. Originally (ZAF-706) these were account permissions
seeded to `owner`, but the Admin app that consumes them gates on admin scope only - so the control was unreachable and every account owner could flip the global
crawl scope via the API. ZAF-725 moved them to admin scope and dropped the
account-side seed.

### CSP Reports (Admin Scope)

Platform-operator read of the CSP-violation calibration aggregate (ZAF-1051 —
observability for the ZAF-995 CSP enforce-flip). Declared in `pub mod global`,
surfaced by `all_admin_permissions()`, and seeded to the `system_admin` admin
role (migration `20260904000004_seed_csp_reports_read_permission`).

| Permission | Label |
|-----------|-------|
| `csp-reports:read` | Read CSP Violation Reports |

It gates GraphQL `cspViolationReports` (`AdminPermissionGuard`) and REST
`GET /v1/admin/csp-reports` (`require_admin_permission`) - same guard type,
string, and errors on both. It reads the capped `csp_violation_reports`
TimescaleDB aggregate (distinct `(violated_directive, blocked_host)` pairs with
counts; ≤5000 pairs, ≤30 d rolling). The rows carry no viewer identity
(host-only), so this is a read of non-personal calibration data, not an account
resource - admin scope only, never assignable to a tenant role.

### Developer Funds (Admin Scope)

`developer-funds:release-deletion` is declared in `lo_auth::rbac::global` (`DEVELOPER_FUNDS_RELEASE_DELETION`), included in `all_admin_permissions()` (category `developer-funds`) and seeded to `system_admin` by `20261025200000_developer_released_balances`. It is absent from the account registry.

It gates the release of an unpayable developer balance as a liability before an admin delete. GraphQL `adminReleaseFundsAndDeleteUser` and `adminReleaseFundsAndDeleteDeveloper` carry `AdminPermissionGuard(DEVELOPER_FUNDS_RELEASE_DELETION)`; both protocols then call `services::developer_funds_release::require_operator(auth, delete_permission)`, which requires the release permission, the plain delete permission (`users:delete` for a user, `developer-verification:edit` for a profile) and an interactive session. The plain deletes keep their own guards and still refuse a positive balance.

`developer-funds:settle` (`DEVELOPER_FUNDS_SETTLE`, same category, seeded to `system_admin` by `20261025210000_developer_funds_settle_permission`) gates the settlement of a released balance when the person comes back. GraphQL `adminStartReleasedBalanceClaim` and `adminSettleReleasedBalance` carry `AdminPermissionGuard(DEVELOPER_FUNDS_SETTLE)`; both protocols then call `services::developer_funds_settlement::require_operator(auth)`, which requires the permission and an interactive session. It is separate from `billing:edit` on purpose: it moves money into a developer balance that the normal payout then pays out.

### Contract Declarations (Admin Scope)

`contract-declarations:read` and `contract-declarations:edit` are declared in `lo_auth::rbac::global`, included in `all_admin_permissions()`, and seeded to `system_admin` by `20261024130102_seed_contract_declarations_permissions`. They are absent from the account permission registry: public declarations and the queue contain personal details across tenants.

The queue's GraphQL readers (`adminContractDeclarations`, `adminContractDeclaration`) use `AdminPermissionGuard("contract-declarations:read")`; REST `GET /v1/admin/contract-declarations` and `GET /v1/admin/contract-declarations/{id}` use `require_admin_permission` with the same key. Close, match and retention mutations use `contract-declarations:edit` on both protocols and additionally require an interactive session. The admin sidebar and page require read; each action uses `<Gate permission="contract-declarations:edit">`.

Signed-in withdrawal uses `plan:edit` for a plan, `extension-store:uninstall` for an extension purchase, or only an interactive session for a free-text `other` contract. Plan cancellation needs `plan:edit`; extension subscription cancellation needs `extension-store:uninstall`. Public withdrawal and cancellation need no role, but are rate limited and Turnstile protected. Both protocols call `services::contract_declarations` for the same validation and result.

### Extension Purchases (Admin Scope)

Platform-operator read of paid extension checkouts across accounts (ZAF-2745).
Declared in `pub mod global`, surfaced by `all_admin_permissions()`, and seeded
to the `system_admin` admin role (migration
`20261023120001_seed_extension_purchases_read_permission`).

| Permission | Label |
|-----------|-------|
| `extension-purchases:read` | Read Extension Purchases |

It gates GraphQL `adminUndeliveredExtensionPurchases` (`AdminPermissionGuard`)
and REST `GET /v1/admin/extension-purchases/undelivered`
(`require_admin_permission`) - same guard type, string, fields, validation and
errors on both (`services::undelivered_purchases`). It reads other accounts'
payments, so it is admin scope only and never assignable to a tenant role; the
account-scope string of the same name does not exist.

### Dev & Admin Menu (Admin Scope)

Gate for the Dev & Admin menu inside the web app, production included
(ZAF-1668). Declared in `pub mod global`, surfaced by
`all_admin_permissions()`, and seeded to the `system_admin` admin role
(migration `20260930000001_seed_devtools_read_permission`). Operators grant it
to further admin roles (e.g. a "Developer" role) in the admin-roles UI.

| Permission | Label |
|-----------|-------|
| `devtools:read` | Open Dev & Admin Menu (web app) |

Only admins — users who can sign in to the admin app — ever hold it: it lives
only in admin roles (which always carry `admin:access`), and it is absent from
the account and user registries, so no channel role, web-app user, or developer
grant can carry it. The web app shows the menu only when `adminPermissions`
contains **both** `admin:access` and `devtools:read`.

It is a UI-visibility grant only: the web app reads it from
`me { adminPermissions }` / REST `GET /v1/users/me` (`admin_permissions`), and
both protocols resolve the same `user_admin_roles` → `admin_role_permissions`
rows via `db::auth::get_user_admin_permissions`. No resolver or route is
guarded on it. Everything the menu does is client-side and viewer-local (e.g.
previewing a seasonal look), so it emits no audit event. A future server-side
action behind the menu (e.g. forcing a season for all users) needs its own
granular admin permission, a real `AdminPermissionGuard` /
`require_admin_permission` guard on both protocols, and an audit event.

### System-Key Assignable-Scope Registry

A System key (`lm_sys_*`) is a machine credential: `is_system = true`, not bound
to an account, so any grant it holds is effectively platform-wide - but it reaches
only what its grants allow. It
needs two classes of grant - **service grants** (what the machine does:
`events:*`, `chat:*`, `overlays:*`, `connections:*`, the user-scope family,
`audit:ingest`) and **platform-operator grants** (the `all_admin_permissions()`
family, for admin-automation keys).

Both create paths (`adminCreateSystemKey` and `POST /v1/admin/system-keys`)
validate every requested permission against **one derived registry** —
`lo_auth::rbac::system_key::get_assignable_permissions()` (ZAF-1213), never a
hand-maintained list. It unions the admin, account, and user registries,
removes a two-category **deny-list** (`SYSTEM_KEY_PERMISSION_DENY_LIST`), and
adds the system-only grants (`SYSTEM_ONLY_PERMISSIONS`, see
[System-Only Permissions](#system-only-permissions-botsinternal) below):

- **credential minting** - `system-keys:create`, `apikeys:create`/`apikeys:edit`,
  `tokens:create`, `admin-roles:create`/`edit`/`delete`, `oauth-clients:create`
  (a key that mints or manages long-lived credentials outlives its purpose and
  self-escalates);
- **tenant / platform destruction** - `accounts:delete`, `account:delete`,
  `admin:privacy-erase`.

Widening the deny-list beyond these two categories needs founder sign-off on
ZAF-1169. Validating against the operator registry alone was the ZAF-1213 bug
(every account-scope service chip was rejected); validating against nothing was
the earlier ZAF-735 hole.

**Wildcards** (`admin:*`, `*:*`) are never registry members, so the mint rejects
them - they stay legitimate only for config-provisioned system keys. There is no
`admin:access` auto-injection on the system-key mint (a machine credential is not
a dashboard seat, unlike `adminCreateRole`).

The registry is served for the picker by `adminSystemKeyPermissions` /
`GET /v1/admin/system-key-permissions`, guarded on `system-keys:read` (the same
grant that lists keys) - **not** `admin-roles:read`, which the mint operator need
not hold, so guarding on it would render the picker empty.

### Audit Ingest (System-Key-Only)

The narrow grant `apps/id` needs to write user-scope security events
(`user:login`, `user:oauth_granted`) to `POST /v1/internal/audit-ingest`
(ZAF-1212). Declared in `pub mod global` and surfaced by `all_admin_permissions()`
so it is derived into the [system-key assignable-scope
registry](#system-key-assignable-scope-registry) above, which the
[system-key mint](../admin/system-keys.md) validates against - that is the sole
supported provisioning path.

| Permission | Label |
|-----------|-------|
| `audit:ingest` | Server-to-Server Audit Ingest (system keys only) |

Unlike every other admin-registry permission it is **not** a functional
admin-role grant and is **never seeded into any admin role** (no migration seeds
it). The ingest endpoint's `authorize_ingest` calls `require_system()` before
`require_permission("audit:ingest")`, so only an `AuthContext::System` (an
`lm_sys_*` key) can ever write - a human admin who is handed `audit:ingest` in a
role holds an inert string. This is deliberate: the assignable-scope registry is
the single "what may an operator put on a system key" allowlist, and audit ingest
is a legitimate system-key grant even though it is meaningless on a user/admin
principal. The endpoint is deliberately REST-only (a server-to-server
infrastructure write for one trusted internal caller), so it has no
GraphQL/WebSocket counterpart to keep in parity.

### System-Only Permissions (`bots:internal`)

`lo_auth::rbac::system_key::SYSTEM_ONLY_PERMISSIONS` holds the grants that exist
**only** for System keys. They are chained into the assignable-scope registry
(so the mint and its picker offer them - `bots:internal` shows under category
`bots`), but they are in **none** of the account, user or admin registries, so no
role can ever hold one: `create_role` / `update_role` reject them as unknown
permission strings, identically on both protocols. A unit test
(`bots_internal_is_system_key_only`) pins that split.

| Permission | Constant | Guards |
|-----------|----------|--------|
| `bots:internal` | `system_key::BOTS_INTERNAL` | The bot fleet's internal surface (ZAF-1922): GraphQL `botChannels`, `botCommandsForAccount`, `emitBotEvent`, `discordBotGuilds`, `discordBotGuildFeatures`, `discordBotAllGuildFeatures`, `updateDiscordGuildInfo`, `removeDiscordGuildByBot`, `sendChatMessage`; REST `POST /v1/chat/message`, `GET /v1/internal/bot-modules/{account_id}/triggers`, `GET /v1/internal/bot-modules/handlers`, `GET /v1/internal/automation-nodes/handlers`; and the cross-account extension and live surfaces (ZAF-1976): extension server functions on any install (`extensionQuery`, `extensionMutate`, `extensionExecuteHandler`; REST `POST /v1/extension-installs/{install_id}/{query,mutate,execute}/{function_name}`), draft/testing extension file trees (`extensionVersionFiles`; REST `GET /v1/extensions/{id}/versions/{version}/files`) and bundle bytes (`GET /v1/extension-bundles/...`), and the WebSocket `presence:*` and `sounds:*` channels |

The keys of `twitch-bot`, `kick-bot`, `youtube-bot`, `discord-bot`,
`bot-module-worker` and `automation-worker` carry it (see
[Provisioning bot and worker keys](../admin/system-keys.md#provisioning-bot-and-worker-keys));
the `apps/id` audit-ingest key carries only `audit:ingest` and reaches none of it.

**`require_system_permission`.** `AuthContext::require_system_permission(perm)`
is `require_system()` followed by `require_permission(perm)`: a non-System caller
gets `Forbidden("System access required")`, a System key without the grant gets
`MissingPermission`. The REST internal feeds share
`routes::internal_extension_handlers::require_bots_internal`, which returns
`403 System key required for internal endpoints` for a non-System caller and
`403 Missing permission: bots:internal` for a System key without the grant.

**Rule for new internal System surfaces:** check a **named grant** with
`require_system_permission` (adding a new entry to `SYSTEM_ONLY_PERMISSIONS` when
no existing grant fits), never `require_system()` alone. `require_system()` is a
type-only gate that every System key passes - including narrow single-grant keys
such as the audit-ingest key - so a type-only gate makes the surface reachable by
every system key ever minted. No `AuthContext::System` branch is type-only any
more (ZAF-1976): the former cross-account branches (extension function calls on
behalf of any install, draft extension bundles / file trees, WS `presence:*` and
`sounds:*`) require `bots:internal` like the fleet surface, and the GraphQL
`SystemGuard` takes its grant as an argument (`SystemGuard::new(grant)`). A
match arm that only *labels* a System caller (the extension handler's auth role,
the rate-limit skip, the auth-type name) or that refuses it (first-party / session
gates) is not an authorization grant. The tripwire
`apps/api/tests/zaf1976_system_grant_gate.rs` lists every System arm in
`apps/api/src` as gated or exempt; a new arm fails it until classified.

### Account & User API Keys (Admin Scope)

Platform-operator management of **any** account's or user's API keys - personal
`lm_usr_` keys (in `api_keys`) and account service `lm_svc_` keys (in
`account_service_keys`) - for support and incident response. Declared in
`pub mod global`, surfaced by `all_admin_permissions()`, and seeded to the
`system_admin` admin role (migration
`20260909000001_seed_account_apikeys_operator_permissions`). This is a **distinct**
family from the account-scope [`apikeys:*`](#api-keys) that a member uses on their
**own** keys; the strings differ (`account-apikeys:*` vs `apikeys:*`), so holding
one never grants the other.

| Permission | Label |
|-----------|-------|
| `account-apikeys:read` | Read Account/User API Keys |
| `account-apikeys:edit` | Edit Account/User API Keys |
| `account-apikeys:rotate` | Rotate Account/User API Keys |
| `account-apikeys:delete` | Delete Account/User API Keys |

Gated by `AdminPermissionGuard` (GraphQL `adminAccountApiKeys` / `adminUserApiKeys`
/ `adminUpdateApiKey` / `adminRotateApiKey` / `adminDeleteApiKey`) and
`require_admin_permission` (REST `GET /v1/admin/accounts/{account_id}/api-keys`,
`GET /v1/admin/users/{user_id}/api-keys`, `PATCH` / `POST .../rotate` /
`DELETE /v1/admin/api-keys/{kind}/{id}`) - same guard type, string and errors on
both. Scope edits validate against the ZAF-1170 assignable-scope registry for the
key's kind, and a **personal** key is additionally capped to its owner's own
grantable permissions (a **service** key's ceiling is the account registry minus
the deny-list), so an operator can never push a key above its own principal. The
rotated plaintext secret is returned exactly once, never listed or logged. Each
write emits a **system-scope** audit event (`system:api_key_updated` /
`system:api_key_rotated` / `system:api_key_revoked`) with the operator as actor.

## Team RBAC (Developer Teams)

Developer teams use a **third permission scope** - team-scoped - that is separate from both account-scope and admin-scope. Team permissions are defined in `crates/lo-auth/src/rbac.rs::team` and enforced by the local `require_team_permission()` in `apps/api/src/routes/developer_teams.rs` and by `lo_graphql::check_team_permission(ctx, team_id, permission)` in resolvers. Neither is a route-level guard attribute - call it explicitly at the top of each handler. Permissions are cached in Redis per `(team_id, user_id)` pair; an empty resolved set means "not a team member" and returns 403 before the permission itself is examined.

### Three Modules, Three Contexts

The `crates/lo-auth/src/rbac.rs` file now defines three permission modules:

- **`pub mod account {}`** - Account-scope permission constants
- **`pub mod global {}`** - Admin-scope permission constants
- **`pub mod team {}`** - Team-scope permission constants

### Team Permissions (18)

All team permissions follow the `team-resource:action` naming convention.

| Permission | Label |
|-----------|-------|
| `team-extensions:create` | Create Extensions |
| `team-extensions:edit` | Edit Extensions |
| `team-extensions:delete` | Delete Extensions |
| `team-extensions:publish` | Publish Extensions |
| `team-extensions:analytics` | View Extension Analytics |
| `team-versions:create` | Create Versions |
| `team-versions:edit` | Edit Versions |
| `team-secrets:read` | Read Secrets (list a team extension's secret key names) |
| `team-secrets:edit` | Edit Secrets (set/delete a team extension's secrets; manage team developer API keys) |
| `team-testers:read` | Read Testers |
| `team-testers:invite` | Invite Testers |
| `team-testers:remove` | Remove Testers |
| `team-members:read` | Read Members |
| `team-members:invite` | Invite Members |
| `team-members:edit` | Edit Member Roles |
| `team-members:remove` | Remove Members |
| `team-settings:read` | Read Settings |
| `team-settings:edit` | Edit Settings |
| `team-payouts:read` | Read Payouts |
| `team-payouts:edit` | Edit Payouts |

For extension operations, the REST and GraphQL twins call `services::developer_extensions::ensure_extension_team_permission` (or the version-ID wrapper) after ownership resolution. The check reads current role grants from the database rather than the Redis team-role cache. Missing grants return `403 Missing team permission: <permission>` in REST and `FORBIDDEN` with the same message in GraphQL. An outsider receives a not-found ownership response first. Solo extensions have no team-role requirement; a team-bound developer key is limited to its own team.

| Permission | Extension operations |
|---|---|
| `team-extensions:edit` | Metadata update; icon and screenshot upload; screenshot delete |
| `team-extensions:delete` | Draft deletion and deletion request |
| `team-extensions:publish` | Submit a version for review |
| `team-extensions:analytics` | Analytics |
| `team-versions:create` | Version creation and upload |
| `team-testers:invite` | Tester invite, private access grant, access invite creation |
| `team-testers:remove` | Tester removal, access revoke, access invite deletion |
| `team-testers:read` | Tester, access grant, and access invite lists |

`team-versions:edit`, `team-settings:read`, and `team-payouts:read|edit` remain catalogue keys without a corresponding extension-action guard. The role editor can assign them, but no version-edit or payout endpoint relies on them today.

### Default Team Roles

Every new developer team is seeded with three roles:

| Role | Slug | `is_system` | `is_default` | Notes |
|------|------|:-----------:|:------------:|-------|
| Owner | `team-owner` | true | false | All 20 team permissions. Cannot be deleted. |
| Admin | `team-admin` | false | true | All permissions except `team-settings:edit`, `team-payouts:edit`, `team-members:remove`. |
| Member | `team-member` | false | true | Edit extensions, create/upload versions, view analytics and read members/secrets/settings; cannot submit, delete, or manage/list testers and private access. |

Custom team roles can be created via `POST /v1/developer/teams/{id}/roles` or the `createDeveloperTeamRole` GraphQL mutation.

### Team Permission Cache

Team permissions are cached in Redis similarly to account permissions:

- **Cache key:** `lumio:team_perms:{team_id}:{user_id}`
- **Invalidation:** On role assignment changes, role permission updates, and member removal — on the team-owner routes and on the admin `/v1/admin/developer-teams/{id}/members/{member_id}` routes alike (see [Invalidation rule](#invalidation-rule))

### `is_developer` Field

The `me` query (GraphQL) and `GET /users/me` (REST) expose an `isDeveloper` / `is_developer` boolean field. This field is `true` when the authenticated user has a row in the `developer_profiles` table OR has the `extension_dev_mode` admin override enabled. It drives access to the developer dashboard and extension management features.

## Guard selection

When writing a GraphQL resolver, pick the right guard:

- **`AdminPermissionGuard::new("resource:action")`** - admin-scope operations (the permission lives in `crates/lo-auth/src/rbac.rs::global`). Only users with admin permissions can call these; account-scope role permissions do NOT grant access.
- **`PermissionGuard::new("resource:action")`** - account-scope operations (the permission lives in `rbac.rs::account`). System admins can also act (their admin role has the permission via `is_system = true`).
- **`AuthGuard`** - any-authenticated operations, no specific permission required.
- **`auth.require_system_permission("resource:action")`** - internal System-key-only surfaces (the bot fleet, workers). Called in the resolver/handler body; requires a System key **and** the named grant (see [System-Only Permissions](#system-only-permissions-botsinternal)). Never gate a System surface on `require_system()` alone.
- **`lo_graphql::check_team_permission(ctx, team_id, permission)`** - team-scope operations (the permission lives in `rbac.rs::team`). Called inside the resolver body, not as a `#[graphql(guard = ...)]`. The REST twin is `require_team_permission(state, user_id, team_id, permission)` in `apps/api/src/routes/developer_teams.rs`.

## Backend Enforcement

### GraphQL: PermissionGuard and AdminPermissionGuard

GraphQL resolvers use one of two guards from `crates/lo-graphql/src/guard.rs`.

Account-scope resolvers use `PermissionGuard`:

```rust
#[graphql(guard = "lo_graphql::PermissionGuard::new(\"events:read\")")]
async fn events(&self, ctx: &Context<'_>) -> async_graphql::Result<Vec<Event>> {
    // ...
}
```

Admin-scope resolvers use `AdminPermissionGuard`:

```rust
#[graphql(guard = "lo_graphql::AdminPermissionGuard::new(\"users:edit\")")]
async fn admin_edit_user(&self, ctx: &Context<'_>) -> async_graphql::Result<AdminUser> {
    // ...
}
```

`PermissionGuard` checks `AuthContext::has_permission()`, which accepts both admin and account permissions (system admins pass both). `AdminPermissionGuard` delegates exclusively to `auth.require_admin_permission()`, which only inspects `admin_permissions` - account-scope role grants do NOT satisfy it.

### REST: require_permission

Every Actix route handler uses `require_permission()` from `crates/lo-auth/src/context.rs`:

```rust
use lo_auth::rbac::account;

pub async fn list_events(auth: Auth, state: web::Data<AppState>) -> Result<HttpResponse, ApiError> {
    auth.require_permission(account::EVENTS_READ)
        .map_err(from_auth_error)?;
    // ...
}
```

This returns an `AuthError::MissingPermission` which maps to HTTP 403.

### Guard parity (standing in-PR review question)

The live channel-status pair uses the same account permission: GraphQL `channelStatus` has `PermissionGuard::new("connections:read")`; REST `GET /v1/channel-status` calls `require_permission("connections:read")`. The separate `spotifyManualStatus` query remains behind `spotify:read`. A popout token may read channel status only when its own permission list includes `connections:read`.

Because every feature exposes both GraphQL and REST, a permission that guards one protocol must guard its twin **identically**. Treat guard parity as a standing review question in every PR - the same class of check as "does this need an audit event?" and "is RBAC seeded for the `owner` slug?".

For each field, route, or resolver a PR adds or touches, confirm the GraphQL and REST twins agree on all three of:

1. **The permission string** - the exact same `resource:action` constant on both (use the `rbac.rs` constant, never a string literal, so a rename can't drift one side).
2. **The guard *type* / scope** - account-scope (`PermissionGuard` ↔ `require_permission`), admin-scope (`AdminPermissionGuard` ↔ `require_admin_permission`), user/first-party-scope (`AuthGuard` + `require_first_party_user()` ↔ the REST first-party check), team-scope (`check_team_permission` ↔ `require_team_permission`), or an explicit ownership check where the resource is owned by the caller. A `UserPermission`/user-scope check where an account `PermissionGuard` was required - or a bare authenticated gate where an ownership check was needed - is a guard-type mismatch even when the permission string matches.
3. **Fail-closed behaviour** - both deny by default and surface the same 403/FORBIDDEN error.

The recurring defect class is **"REST enforces, GraphQL doesn't"** (or the reverse) and **"wrong guard type"**. A one-sided or mismatched guard is a security bug, not a style nit. If a single-protocol path is deliberate, document *why* at the call site. (ZAF-722 findings #4/#8/#9/A1; standing rule ZAF-738.)

### Permission Constants

All permission constants are defined in `crates/lo-auth/src/rbac.rs` inside `pub mod account {}`. Use the constants (not string literals) in REST handlers to prevent typos.

### WebSocket: channel gate

The WebSocket layer (`crates/lo-websocket/src/gate.rs`) maps each channel type to a gate. The `WsSession` calls `channel_gate_for(channel_type)` on every subscribe request, then runs the check against the same `AuthContext` the REST/GraphQL layers see. "Reach the account" below means `AuthContext::can_access_account`: the caller's own account, or a System key. `admin:access` grants no cross-tenant reach.

`ChannelGate` is not permission-only - the variants are:

| Variant | Meaning |
|---------|---------|
| `Permission("resource:action")` | Caller must reach the account ID in the channel name **and** hold the permission |
| `AccountScoped` | Caller must reach the account ID; no RBAC permission (used where Widget/Overlay tokens must subscribe) |
| `UserPermission("resource:action")` | Checked against the caller's **user-scoped** permissions; the channel ID is not an account UUID |
| `Authenticated` | Any non-anonymous identity |
| `Public` | Anyone |
| `PublicWhenFeature("flag")` | Anyone, as long as the named system flag is on; otherwise `FEATURE_DISABLED` |
| `OverlayToken` / `WidgetToken` | Requires that token type, with a matching `overlay_id` / `widget_id` |
| `ExtensionOwner` | Requires that the subscriber owns the extension in the channel ID |
| `Unknown` | Default arm - always rejects |

Current channel mapping:

| Channel type | Gate | Feature flag (`channel_feature_for`) |
|--------------|------|--------------------------------------|
| `overlay` | `OverlayToken` | `feature:overlays` |
| `events` | `Permission("events:read")` | `feature:events` |
| `spotify` | `Permission("spotify:read")` | `feature:music` |
| `chat` | `Permission("chat:read")` | `feature:multichat` |
| `automations` | `Permission("automations:read")` | `feature:automation` |
| `history` | `Permission("history:read")` | `feature:stream_history` |
| `ext-storage` | `ExtensionStorage` (the install's extension token, `extension-store:read` in the install's account, or an overlay/widget token that renders the install) | `feature:extensions` |
| `ext-install-logs` | `InstallLogs` (`bot-modules:read` or `automations:read` by install category) | `feature:bot_module_extensions` |
| `sounds` | `AccountScoped` | `feature:sounds` |
| `widget` | `WidgetToken` | `feature:widgets` |
| `ext-logs` | `ExtensionOwner` | `feature:extension_development` |
| `presence` | `PresenceScoped` (signed-in members of the owning account; a widget token only for its own widget) | - |
| `login-assignments` | `Public` | - |
| `ideas` | `PublicWhenFeature("system:ideas_hub_public")` | `system:ideas_hub` |

`sounds` is `AccountScoped` rather than `Permission("sounds:read")` on purpose: Widget and Overlay tokens carry an account but no account-level RBAC, so a permission gate would lock them out - while the account check still stops cross-account subscribes.

After RBAC, the same module runs the feature-flag check via the `FeatureGate` trait (implemented by `FeatureService` in `apps/api/src/websocket/mod.rs`). Channels mapped in `channel_feature_for` reject subscribes for accounts whose plan/account-feature row has the flag off. Adding a new paid-tier channel: extend both functions in one edit.

For `overlay` and `widget` the channel suffix is not an account UUID (an overlay key, a widget id), so the feature check resolves the **owning account** from the `lm_overlay_*` / `lm_share_*` / `lm_widget_*` token instead of parsing the channel id.

There is no client publish path. The WebSocket protocol has no `broadcast` frame, so a client can only read. Server-side `WsServer::broadcast_raw` is the only publisher on every channel, and its callers (REST/GraphQL mutations, workers, ingest) carry their own write guards.

A subscribe failure raises a typed error message back to the client: `code: "UNAUTHORIZED"` for missing permissions and `code: "FEATURE_DISABLED"` for disabled feature flags. Clients should surface both as user-facing "no access" / "upgrade plan" hints.

**Important:** when adding a new account-scoped WebSocket channel type, you MUST extend `channel_gate_for` in the same PR - the default match arm returns `ChannelGate::Unknown` which rejects the subscribe with `UNAUTHORIZED` for *every* caller, including Owners. Forgetting this step ships a broken channel that nobody can use.

## Frontend Enforcement

### PermissionProvider

The `PermissionProvider` React context (`apps/web/src/contexts/permission-context.tsx`) receives the user's permissions from the server layout and makes them available to all client components via hooks.

### Gate Component

Declaratively renders children only when the user has the required permission:

```tsx
<Gate permission="overlays:create">
  <Button>Create Overlay</Button>
</Gate>
```

`<Gate>` and `useHasPerm()` resolve against the permission list handed to `PermissionProvider`; the only wildcard they honour is a literal `"*"` entry, which no account role can carry.

### PermissionErrorBoundary

Wraps entire page content to show a "No Access" fallback for users without the permission:

```tsx
<PermissionErrorBoundary permission="spotify:read">
  <MusicPlayer />
</PermissionErrorBoundary>
```

### Imperative Checks

For use in hooks or event handlers:

```tsx
const canEdit = useHasPerm("overlays:edit");
```

See [Frontend Permission System](./frontend-permissions.md) for the full API reference.

## Redis Cache

Permissions are cached in Redis to avoid database lookups on every request.

### CachedPermissions

The `CachedPermissions` struct in `crates/lo-cache/src/client.rs` stores permissions split by scope, stamped with the cache generation they were loaded under:

```rust
pub struct CachedPermissions {
    #[serde(flatten)]
    pub stamp: PermissionStamp, // { epoch, ver } at load time
    pub global: Vec<String>,    // Admin-scope permissions
    pub account: Vec<String>,   // Account-scope permissions
    pub user: Vec<String>,      // User-scope permissions (Ideas Hub etc.)
}
```

| Cache | Key | TTL | Invalidator |
|-------|-----|-----|-------------|
| Account + admin + user, per active account | `lumio:perms:v2:{user_id}:{account_id}` | 300 s | exact `DEL` via `invalidate_permission_cache()`, or a generation bump |
| User-scope only, account-independent | `lumio:user_perms:v2:{user_id}` | 300 s | generation bump |
| Team scope | `lumio:team_perms:{team_id}:{user_id}` | 300 s | `RedisClient::invalidate_team_permissions()` |

Two **generation keys** make entries invalid without enumerating them:

| Key | Value | TTL | Bumped by |
|-----|-------|-----|-----------|
| `lumio:perms:ver:{user_id}` | unique token (UUID v4) | 900 s | `lo_api::middleware::auth::invalidate_user_permission_cache()` |
| `lumio:perms:epoch` | unique token (UUID v4) | 900 s | `lo_api::middleware::auth::invalidate_all_permission_caches()` |

`resolve_jwt` reads `lumio:perms:epoch`, `lumio:perms:ver:{user}`, the combined entry and the user-scope entry in **one `MGET`** (`RedisClient::read_permission_cache`). An entry counts as a hit only while its stamp equals both current values (an absent key equals an absent stamp). On a miss the DB load is cached under the stamp read **before** the load, so an edit committed during the load leaves a stale stamp and the next request misses again. The combined entry is written on a miss only, so its 300 s TTL is a real upper bound.

The generation values are unique tokens, never counters: a counter that expires and is incremented again can repeat an old value and re-validate a stale entry. The generation TTL (900 s) is longer than the entry TTL (300 s), so an entry stamped "key absent" has expired before the key can expire and be set again.

### Invalidation rule

TTL is only the backstop. Every write that changes what a cached set would resolve to **invalidates in the same code path, after the database write, on both GraphQL and REST**. A one-sided invalidation is a security bug: the other protocol leaves a revoked permission usable until the TTL expires.

| Write | Invalidation | Shared helper |
|-------|--------------|---------------|
| Role permission set edited (`PATCH /v1/roles/{id}` · `updateRole`) | `DEL lumio:perms:v2:{member}:{account}` for every member of the role | `services::roles::invalidate_cache_for_role` |
| Role deleted (`DELETE /v1/roles/{id}` · `deleteRole`) | same — members are collected before the delete and dropped after it | `services::roles::role_member_user_ids` + `invalidate_permission_cache_for_users` |
| Member role changed / member removed / member left | `DEL lumio:perms:v2:{user}:{account}` | `lo_api::middleware::auth::invalidate_permission_cache` |
| Admin adds or removes an account member (`/v1/admin/accounts/{id}/members` · `adminAddAccountMember` / `adminRemoveAccountMember`) | `DEL lumio:perms:v2:{user}:{account}` | `invalidate_permission_cache` |
| Account permission override set/removed (admin) | `DEL lumio:perms:v2:{member}:{account}` for every member | `RedisClient::invalidate_permissions` |
| User role assigned/removed, user override set/removed (`/v1/users/{id}/roles*`, `/v1/users/{id}/permission-overrides*` · `assignUserRole` / `removeUserRole` / `setUserPermissionOverride` / `removeUserPermissionOverride`) | bump `lumio:perms:ver:{user}` — every entry of that user, in every account | `invalidate_user_permission_cache` |
| Admin role assigned/unassigned (`/v1/admin/admin-roles/{id}/members*` · `adminAssignUserRole` / `adminUnassignUserRole`) | bump `lumio:perms:ver:{user}` | `invalidate_user_permission_cache` |
| User role permissions edited or role deleted (`PATCH`/`DELETE /v1/user-roles/{id}` · `updateUserRole` / `deleteUserRole`) | bump `lumio:perms:epoch` — the holders include every user without an assignment when the role is the default role, so they cannot be enumerated | `invalidate_all_permission_caches` |
| Admin role permissions edited or role deleted (`PATCH`/`DELETE /v1/admin/admin-roles/{id}` · `adminUpdateRole` / `adminDeleteRole`) | bump `lumio:perms:epoch` | `invalidate_all_permission_caches` |
| Team member role changed / removed (team owner **and** admin surfaces) | `DEL lumio:team_perms:{team}:{user}` | `RedisClient::invalidate_team_permissions` |

An epoch bump makes every active user reload from the database once on their next request. Role-definition edits are rare platform-operator actions, so this costs a handful of indexed queries per active user a few times a month. Invalidation is best-effort: a failed Redis write is logged, and the 300 s TTL bounds the damage.

A role that still has members cannot be deleted (the membership foreign key refuses it), so a delete never leaves a member holding a removed role's grants.

API-key, service-key and developer-key permissions are **not** cached — they are read from their key row on every request, so editing or revoking a key takes effect immediately. There is no pub/sub permission-invalidation channel: the cache is shared Redis, so a `DEL` or a generation bump is visible to every replica at once and no in-process permission cache exists to notify.

## Key Files

| File | Purpose |
|------|---------|
| `crates/lo-auth/src/rbac.rs` | Permission constants (`account` / `global` / `team` / `user`), `get_all_account_permission_infos()` registry, default roles, `all_admin_permissions()` |
| `crates/lo-auth/src/context.rs` | `AuthContext::has_permission()` + `require_permission()` + `require_admin_permission()` + `require_user_permission()` |
| `crates/lo-graphql/src/guard.rs` | `PermissionGuard` (account-scope) + `AdminPermissionGuard` (admin-scope) for GraphQL resolvers |
| `crates/lo-websocket/src/gate.rs` | `channel_gate_for` / `channel_feature_for` |
| `crates/lo-cache/src/client.rs` | `CachedPermissions`, `PermissionStamp`, `read_permission_cache` + Redis cache/invalidation (account, user, team) |
| `apps/api/src/graphql/roles.rs` | GraphQL `availablePermissions` picker + role create/update validation |
| `apps/api/src/graphql/admin.rs` | GraphQL `adminRoles*` queries/mutations + `adminAssignablePermissions` (admin scope) |
| `apps/api/src/routes/roles.rs` | REST `GET /v1/roles/permissions` picker + validation |
| `apps/api/src/routes/admin.rs` | REST `admin-roles` + `admin-permissions` + account permission overrides |
| `apps/api/src/db/admin_roles.rs` | DB helpers for admin role CRUD |
| `apps/web/src/contexts/permission-context.tsx` | `PermissionProvider` + `usePermissions()` + `useHasPerm()` |
| `apps/web/src/components/gate.tsx` | `<Gate>` declarative permission component |
| `apps/web/src/components/permission-error-boundary.tsx` | Page-level access denial |
| `apps/web/src/lib/translate-role.ts` | `useTranslateRole()` hook for default role names |

---

## Developer Guide / Roles and Permissions Guide

Source: https://docs.lumio.vision/developer-guide/roles-permissions-guide

# Roles and Permissions Guide

This guide covers everything you need to know when adding new permissions or modifying the roles system in Lumio.

---

## Concepts

### Permission Format

Permissions follow the `resource:action` format:

- `events:read`, `events:create`
- `chat:ban`, `chat:timeout`
- `automations:execute`

**Rules:**
- Use granular scopes. Every resource needs at minimum `read` plus granular `create`/`edit`/`delete`.
- Add domain-specific actions where the CRUD model is insufficient (e.g., `automations:execute`, `chat:ban`).
- Never use wildcard permissions like `resource:*` or `*:*` for account-level permissions. `:manage` action names are not used for account permissions; choose granular actions.

### Role Properties

| Property | Type | Description |
|----------|------|-------------|
| `slug` | `string` | Machine-readable identifier (lowercase, stable - used in code checks) |
| `name` | `string` | Human-readable display name (user-editable on custom roles) |
| `is_system` | `bool` | Cannot be edited or deleted. Only the Owner role is a system role. |
| `is_default` | `bool` | Cannot be deleted. All three default roles have this set. |
| `color` | `string` | Hex color string, e.g. `"#f59e0b"` |

### Default Roles

Lumio creates three default roles for every new account:

| Role | Slug | Color | Notes |
|------|------|-------|-------|
| Owner | `owner` | `#f59e0b` | System role - every account registry permission, cannot be deleted or edited |
| Administrator | `administrator` | `#ef4444` | all but four account permissions - everything except `account:delete`, `plan:read`, `plan:edit`, `extension-dev:payouts` |
| Moderator | `moderator` | `#22c55e` | 49 permissions - chat moderation, event monitoring, read access |

The definitions live in `ROLE_OWNER` / `ROLE_ADMIN` / `ROLE_MODERATOR` in `crates/lo-auth/src/rbac.rs` and are inserted by `create_default_roles()` (`apps/api/src/db/roles.rs`), which sets `is_default = true` on all three.

---

## Adding New Permissions

### Step 1 - Define constants in `rbac.rs`

All account-level permission constants live in `crates/lo-auth/src/rbac.rs` inside the `pub mod account {}` block.

```rust
// crates/lo-auth/src/rbac.rs
pub mod account {
    // ... existing permissions ...

    /// Read resource data.
    pub const RESOURCE_READ: &str = "resource:read";
    /// Create new resource entries.
    pub const RESOURCE_CREATE: &str = "resource:create";
    /// Edit existing resource entries.
    pub const RESOURCE_EDIT: &str = "resource:edit";
    /// Delete resource entries.
    pub const RESOURCE_DELETE: &str = "resource:delete";
}
```

Use descriptive doc comments - they serve as inline documentation for the permission's purpose.

### Step 2 - Add to default roles in `rbac.rs`

Update the `ROLE_OWNER`, `ROLE_ADMIN`, and `ROLE_MODERATOR` constants in the same file.

**Decision guide:**

| Role | Gets the permission? |
|------|----------------------|
| Owner | Always - Owner gets ALL permissions |
| Administrator | Yes, unless it is owner-only (`account:delete`, `plan:read`, `plan:edit`, `extension-dev:payouts`) |
| Moderator | Read permissions + feature-specific actions relevant to moderation |

```rust
pub const ROLE_OWNER: DefaultRole = DefaultRole {
    // ...
    permissions: &[
        // ... existing ...
        account::RESOURCE_READ,
        account::RESOURCE_CREATE,
        account::RESOURCE_EDIT,
        account::RESOURCE_DELETE,
    ],
    // ...
};

pub const ROLE_ADMIN: DefaultRole = DefaultRole {
    // ...
    permissions: &[
        // ... existing ...
        account::RESOURCE_READ,
        account::RESOURCE_CREATE,
        account::RESOURCE_EDIT,
        account::RESOURCE_DELETE,
    ],
    // ...
};

pub const ROLE_MODERATOR: DefaultRole = DefaultRole {
    // ...
    permissions: &[
        // ... existing ...
        account::RESOURCE_READ,
    ],
    // ...
};
```

### Step 3 - Add GraphQL guards

Every GraphQL resolver that touches the new resource needs a `PermissionGuard`:

```rust
// apps/api/src/graphql/resource.rs
impl ResourceQuery {
    #[graphql(guard = "lo_graphql::PermissionGuard::new(\"resource:read\")")]
    async fn resources(&self, ctx: &Context<'_>) -> async_graphql::Result<Vec<Resource>> {
        // ...
    }
}

impl ResourceMutation {
    #[graphql(guard = "lo_graphql::PermissionGuard::new(\"resource:create\")")]
    async fn create_resource(
        &self,
        ctx: &Context<'_>,
        input: CreateResourceInput,
    ) -> async_graphql::Result<Resource> {
        // ...
    }

    #[graphql(guard = "lo_graphql::PermissionGuard::new(\"resource:edit\")")]
    async fn update_resource(
        &self,
        ctx: &Context<'_>,
        id: Uuid,
        input: UpdateResourceInput,
    ) -> async_graphql::Result<Resource> {
        // ...
    }

    #[graphql(guard = "lo_graphql::PermissionGuard::new(\"resource:delete\")")]
    async fn delete_resource(
        &self,
        ctx: &Context<'_>,
        id: Uuid,
    ) -> async_graphql::Result<bool> {
        // ...
    }
}
```

### Step 4 - Add REST guards

Every Actix route handler that touches the new resource needs a permission check. Use the constant from `rbac.rs` rather than a string literal:

```rust
// apps/api/src/routes/resource.rs
use lo_auth::rbac::account;

pub async fn list_resources(
    auth: Auth,
    state: web::Data<AppState>,
) -> Result<HttpResponse, ApiError> {
    auth.require_permission(account::RESOURCE_READ)
        .map_err(from_auth_error)?;
    // ...
}

pub async fn create_resource(
    auth: Auth,
    state: web::Data<AppState>,
    body: web::Json<CreateResourceRequest>,
) -> Result<HttpResponse, ApiError> {
    auth.require_permission(account::RESOURCE_CREATE)
        .map_err(from_auth_error)?;
    // ...
}
```

### Step 5 - Register the permission in the registry

There is exactly **one** list to edit: `account::get_all_account_permission_infos()` in `crates/lo-auth/src/rbac.rs`. It returns every account permission with the `label` and `category` the role editor renders.

```rust
// crates/lo-auth/src/rbac.rs — inside get_all_account_permission_infos()
// Resource
p!(RESOURCE_READ, "Read Resource", "Resource"),
p!(RESOURCE_CREATE, "Create Resource", "Resource"),
p!(RESOURCE_EDIT, "Edit Resource", "Resource"),
p!(RESOURCE_DELETE, "Delete Resource", "Resource"),
```

Everything downstream derives from it and needs no edit:

- `account::get_all_account_permissions()` - the validation registry consulted by role create/update on both protocols (`apps/api/src/{graphql,routes}/roles.rs`). It maps the info list's keys, so a key the editor hides can never be accepted by validation and vice versa (ZAF-231).
- The web role editor pickers: REST `GET /v1/roles/permissions` and GraphQL `availablePermissions`, both guarded on `roles:read`.
- The admin override pickers via `adminAssignablePermissions` (ZAF-430).

Unit tests in both `roles.rs` files assert the picker set equals the registry set, so a divergence fails CI rather than shipping.

### Step 6 - Write a DB migration

Existing accounts already have their roles in the database. The migration must backfill the new permissions for default roles. New migrations use the reversible format with `.up.sql` and `.down.sql` suffixes (`YYYYMMDD######_description.up.sql` / `.down.sql`); see `apps/api/migrations/` for examples.

```sql
-- apps/api/migrations/20260401000001_add_resource_permissions.up.sql
--
-- Add resource permissions to existing default roles.

-- Owner: all permissions
INSERT INTO account_role_permissions (role_id, permission)
SELECT ar.id, perm.permission
FROM account_roles ar
CROSS JOIN (
    VALUES
        ('resource:read'),
        ('resource:create'),
        ('resource:edit'),
        ('resource:delete')
) AS perm(permission)
WHERE ar.slug = 'owner'
ON CONFLICT DO NOTHING;

-- Administrator: all permissions
INSERT INTO account_role_permissions (role_id, permission)
SELECT ar.id, perm.permission
FROM account_roles ar
CROSS JOIN (
    VALUES
        ('resource:read'),
        ('resource:create'),
        ('resource:edit'),
        ('resource:delete')
) AS perm(permission)
WHERE ar.slug = 'administrator'
ON CONFLICT DO NOTHING;

-- Moderator: read only
INSERT INTO account_role_permissions (role_id, permission)
SELECT ar.id, perm.permission
FROM account_roles ar
CROSS JOIN (
    VALUES
        ('resource:read')
) AS perm(permission)
WHERE ar.slug = 'moderator'
ON CONFLICT DO NOTHING;
```

Note: `ON CONFLICT DO NOTHING` makes migrations safe to re-run.

---

## Frontend Translations (Critical)

Translations must be updated in **both** `apps/web/messages/en.json` and `apps/web/messages/de.json`.

### Permission labels

Each permission key must have a translation in the `"permissions"` namespace:

```json
{
  "permissions": {
    "resource:read": "Read Resource",
    "resource:create": "Create Resource",
    "resource:edit": "Edit Resource",
    "resource:delete": "Delete Resource"
  }
}
```

### Permission category

Each distinct `category` value used in `get_all_account_permissions()` must have a translation under `"permissions.categories"`:

```json
{
  "permissions": {
    "categories": {
      "Resource": "Resource"
    }
  }
}
```

### Default role names

Default role display names are translated via `"roles.labels"` keyed by slug:

```json
{
  "roles": {
    "labels": {
      "owner": "Owner",
      "administrator": "Administrator",
      "moderator": "Moderator"
    }
  }
}
```

Use the `useTranslateRole()` hook (from `apps/web/src/lib/translate-role.ts`) when displaying role names - it returns a `(slug, name) => string` function. Default role slugs are translated; custom roles fall back to their `name` field unchanged.

---

## Frontend Permission Checks

### Sidebar navigation

Add a permission-gated nav entry in `apps/web/src/app/(main)/(app)/shell.tsx`:

```tsx
// apps/web/src/app/(main)/(app)/shell.tsx
{
  label: "manage",
  items: [
    // ...
    {
      href: "/dashboard/resource",
      icon: Box,
      translationKey: "resource",
      permission: "resource:read",
    },
  ],
},
```

The shell filters out items where the user lacks the required permission.

### Page-level boundary

Wrap the main page content in `<PermissionErrorBoundary>` to show a "No Access" fallback for users without the permission:

```tsx
// apps/web/src/app/(main)/(app)/dashboard/resource/resource-list.tsx
import { PermissionErrorBoundary } from "@/components/permission-error-boundary";
import { Gate } from "@/components/gate";

export function ResourceList() {
  return (
    <PermissionErrorBoundary permission="resource:read">
      <div>
        <Gate permission="resource:create">
          <Button>Create Resource</Button>
        </Gate>
        {/* list content */}
      </div>
    </PermissionErrorBoundary>
  );
}
```

### Component-level checks

For ad-hoc imperative checks (e.g., inside hooks or event handlers):

```tsx
const canEdit = useHasPerm("resource:edit");

if (canEdit) {
  // show edit button
}
```

`useHasPerm` resolves as `perms.includes("*") || perms.includes(permission)`. An **empty** permission array grants nothing - it means the identity has no account-scope grants (for example a user whose active context is their personal profile), so every gate closes. Never hand-roll a `permissions.length === 0` escape hatch.

Use `<Gate permission="...">` for declarative rendering and `useHasPerm("...")` for boolean checks. See [Frontend Permission System](./frontend-permissions.md) for the full API reference.

### Next.js proxy routes

The frontend never calls the Rust GraphQL endpoint directly. Follow the established proxy pattern:

```
Browser → Next.js API route → serverGql() → Rust GraphQL
```

```ts
// apps/web/src/app/api/resource/route.ts
import { NextRequest, NextResponse } from "next/server";
import { serverGql } from "@/lib/server-gql";
import { transformKeys } from "@/lib/transform";

const RESOURCES_QUERY = `
  query Resources {
    resources {
      id accountId name createdAt updatedAt
    }
  }
`;

export async function GET(request: NextRequest) {
  try {
    const { data } = await serverGql<{ resources: unknown[] }>(
      request,
      RESOURCES_QUERY,
    );
    return NextResponse.json({
      data: (data.resources || []).map(transformKeys),
    });
  } catch (e) {
    const status = (e as Error & { status?: number }).status ?? 500;
    return NextResponse.json(
      { error: (e as Error).message },
      { status },
    );
  }
}
```

---

## Complete Permissions Reference

Every account-scope permission in `account::get_all_account_permission_infos()`, with its role-editor label, picker category, and the default roles that carry it. 129 entries - Owner holds every one of them.

| Permission | Label | Category | Owner | Admin | Moderator |
|-----------|-------|----------|:-----:|:-----:|:---------:|
| `events:read` | Read Events | Events | ✓ | ✓ | ✓ |
| `events:create` | Create Events | Events | ✓ | ✓ | ✓ |
| `events:userinfo` | Event User Info | Events | ✓ | ✓ | ✓ |
| `overlays:read` | Read Overlays | Overlays | ✓ | ✓ | ✓ |
| `overlays:create` | Create Overlays | Overlays | ✓ | ✓ |  |
| `overlays:edit` | Edit Overlays | Overlays | ✓ | ✓ |  |
| `overlays:delete` | Delete Overlays | Overlays | ✓ | ✓ |  |
| `overlays:access-read` | Read Overlay Access | Overlays | ✓ | ✓ |  |
| `overlays:access-grant` | Grant Overlay Access | Overlays | ✓ | ✓ |  |
| `overlays:access-revoke` | Revoke Overlay Access | Overlays | ✓ | ✓ |  |
| `spotify:read` | Read Spotify | Spotify | ✓ | ✓ | ✓ |
| `spotify:playback` | Spotify Playback | Spotify | ✓ | ✓ | ✓ |
| `spotify:volume` | Spotify Volume | Spotify | ✓ | ✓ |  |
| `spotify:queue` | Spotify Queue | Spotify | ✓ | ✓ | ✓ |
| `spotify:playlist` | Spotify Playlists | Spotify | ✓ | ✓ | ✓ |
| `spotify:device` | Spotify Devices | Spotify | ✓ | ✓ | ✓ |
| `spotify:worker` | Spotify Worker | Spotify | ✓ | ✓ |  |
| `chat:read` | Read Chat | Chat | ✓ | ✓ | ✓ |
| `chat:write` | Write Chat | Chat | ✓ | ✓ | ✓ |
| `chat:userinfo` | Chat User Info | Chat | ✓ | ✓ | ✓ |
| `chat:delete` | Delete Chat Messages | Chat | ✓ | ✓ | ✓ |
| `chat:ban` | Ban Chat Users | Chat | ✓ | ✓ | ✓ |
| `chat:timeout` | Timeout Chat Users | Chat | ✓ | ✓ | ✓ |
| `chat:notes` | Chat User Notes | Chat | ✓ | ✓ | ✓ |
| `chat:raid` | Cancel Raids | Chat | ✓ | ✓ | ✓ |
| `chat:refresh_user` | Refresh User Profile | Chat | ✓ | ✓ | ✓ |
| `chat:poll` | End Polls | Chat | ✓ | ✓ | ✓ |
| `chat:prediction` | End Predictions | Chat | ✓ | ✓ | ✓ |
| `chat:automod-read` | Read AutoMod Queue | Chat | ✓ | ✓ | ✓ |
| `chat:automod-allow` | Allow Held Messages | Chat | ✓ | ✓ | ✓ |
| `chat:automod-deny` | Deny Held Messages | Chat | ✓ | ✓ | ✓ |
| `chat-bots:read` | Read Bot List | Chat | ✓ | ✓ | ✓ |
| `chat-bots:edit` | Edit Bot List | Chat | ✓ | ✓ |  |
| `connections:read` | Read Connections | Connections | ✓ | ✓ | ✓ |
| `connections:create` | Create Connections | Connections | ✓ | ✓ |  |
| `connections:edit` | Edit Connections | Connections | ✓ | ✓ |  |
| `connections:delete` | Delete Connections | Connections | ✓ | ✓ |  |
| `settings:read` | Read Settings | Settings | ✓ | ✓ |  |
| `settings:edit` | Edit Settings | Settings | ✓ | ✓ |  |
| `account:read` | Read Account Settings | Account | ✓ | ✓ |  |
| `account:edit` | Edit Account Settings | Account | ✓ | ✓ |  |
| `account:delete` | Delete Account | Account | ✓ |  |  |
| `plan:read` | View Plan & Billing | Plan | ✓ |  |  |
| `plan:edit` | Change Plan | Plan | ✓ |  |  |
| `members:read` | Read Members | Members | ✓ | ✓ | ✓ |
| `members:create` | Create Invites | Members | ✓ | ✓ |  |
| `members:edit` | Edit Members | Members | ✓ | ✓ |  |
| `members:delete` | Delete Members | Members | ✓ | ✓ |  |
| `roles:read` | Read Roles | Roles | ✓ | ✓ | ✓ |
| `roles:edit` | Edit Roles | Roles | ✓ | ✓ |  |
| `roles:delete` | Delete Roles | Roles | ✓ | ✓ |  |
| `login-assignments:read` | View Login Assignments | Login Assignments | ✓ | ✓ |  |
| `login-assignments:create` | Assign Login Connections | Login Assignments | ✓ | ✓ |  |
| `login-assignments:delete` | Remove Login Assignments | Login Assignments | ✓ | ✓ |  |
| `uploads:read` | Read Uploads | Uploads | ✓ | ✓ | ✓ |
| `uploads:create` | Create Uploads | Uploads | ✓ | ✓ |  |
| `uploads:delete` | Delete Uploads | Uploads | ✓ | ✓ |  |
| `rewards:read` | Read Rewards | Rewards | ✓ | ✓ | ✓ |
| `rewards:create` | Create Rewards | Rewards | ✓ | ✓ |  |
| `rewards:edit` | Edit Rewards | Rewards | ✓ | ✓ |  |
| `rewards:delete` | Delete Rewards | Rewards | ✓ | ✓ |  |
| `tokens:read` | Read Tokens | Tokens | ✓ | ✓ |  |
| `tokens:create` | Create Tokens | Tokens | ✓ | ✓ |  |
| `tokens:edit` | Edit Tokens | Tokens | ✓ | ✓ |  |
| `tokens:delete` | Delete Tokens | Tokens | ✓ | ✓ |  |
| `automations:read` | Read Automations | Automations | ✓ | ✓ | ✓ |
| `automations:create` | Create Automations | Automations | ✓ | ✓ |  |
| `automations:edit` | Edit Automations | Automations | ✓ | ✓ |  |
| `automations:delete` | Delete Automations | Automations | ✓ | ✓ |  |
| `automations:execute` | Execute Automations | Automations | ✓ | ✓ | ✓ |
| `obs:read` | View OBS Config | OBS | ✓ | ✓ | ✓ |
| `obs:edit` | Edit OBS Config | OBS | ✓ | ✓ |  |
| `obs:delete` | Delete OBS Config | OBS | ✓ | ✓ |  |
| `copyright:read` | View Copyright | Copyright | ✓ | ✓ |  |
| `copyright:edit` | Edit Copyright Lists | Copyright | ✓ | ✓ |  |
| `copyright:delete` | Delete Copyright Entries | Copyright | ✓ | ✓ |  |
| `copyright:vote` | Vote on Songs | Copyright | ✓ | ✓ | ✓ |
| `copyright:report` | Create Copyright Reports | Copyright | ✓ | ✓ | ✓ |
| `copyright:recommend` | Recommend Songs | Copyright | ✓ | ✓ | ✓ |
| `copyright:moderate` | Moderate Global Copyright List | Copyright | ✓ | ✓ |  |
| `bot-modules:read` | View Bot Modules | Bot Modules | ✓ | ✓ | ✓ |
| `bot-modules:edit` | Edit Bot Modules | Bot Modules | ✓ | ✓ |  |
| `bot-commands:read` | View Bot Commands | Bot Commands | ✓ | ✓ | ✓ |
| `bot-commands:create` | Create Bot Commands | Bot Commands | ✓ | ✓ |  |
| `bot-commands:edit` | Edit Bot Commands | Bot Commands | ✓ | ✓ |  |
| `bot-commands:delete` | Delete Bot Commands | Bot Commands | ✓ | ✓ |  |
| `bot-connections:read` | View Bot Connections | Bot Connections | ✓ | ✓ | ✓ |
| `bot-connections:create` | Create Bot Connections | Bot Connections | ✓ | ✓ |  |
| `bot-connections:delete` | Delete Bot Connections | Bot Connections | ✓ | ✓ |  |
| `se-tokens:read` | View SE Tokens | StreamElements | ✓ | ✓ |  |
| `se-tokens:create` | Create SE Tokens | StreamElements | ✓ | ✓ |  |
| `se-tokens:delete` | Delete SE Tokens | StreamElements | ✓ | ✓ |  |
| `extension-dev:read` | View Developer Dashboard | Extension Developer | ✓ | ✓ |  |
| `extension-dev:create` | Create Extensions | Extension Developer | ✓ | ✓ |  |
| `extension-dev:edit` | Edit Extensions | Extension Developer | ✓ | ✓ |  |
| `extension-dev:delete` | Delete Extensions | Extension Developer | ✓ | ✓ |  |
| `extension-dev:publish` | Publish Extensions | Extension Developer | ✓ | ✓ |  |
| `extension-dev:analytics` | View Extension Analytics | Extension Developer | ✓ | ✓ |  |
| `extension-dev:payouts` | Manage Extension Payouts | Extension Developer | ✓ |  |  |
| `extension-store:read` | Browse Extension Store | Extension Store | ✓ | ✓ | ✓ |
| `extension-store:install` | Install Extensions | Extension Store | ✓ | ✓ |  |
| `extension-store:uninstall` | Uninstall Extensions | Extension Store | ✓ | ✓ |  |
| `extension-store:configure` | Configure Extensions | Extension Store | ✓ | ✓ |  |
| `extension-store:review` | Review Extensions | Extension Store | ✓ | ✓ | ✓ |
| `extension-data:read` | Read Extension Data | Extension Data | ✓ | ✓ | ✓ |
| `extension-data:edit` | Edit Extension Data | Extension Data | ✓ | ✓ |  |
| `widgets:read` | View Widgets | Widgets | ✓ | ✓ | ✓ |
| `widgets:create` | Create Widgets | Widgets | ✓ | ✓ |  |
| `widgets:edit` | Edit Widgets | Widgets | ✓ | ✓ |  |
| `widgets:delete` | Delete Widgets | Widgets | ✓ | ✓ |  |
| `widgets:access-read` | Read Widget Access | Widgets | ✓ | ✓ |  |
| `widgets:access-grant` | Grant Widget Access | Widgets | ✓ | ✓ |  |
| `widgets:access-revoke` | Revoke Widget Access | Widgets | ✓ | ✓ |  |
| `sounds:read` | View Sounds | Sounds | ✓ | ✓ | ✓ |
| `sounds:create` | Upload Sounds | Sounds | ✓ | ✓ |  |
| `sounds:edit` | Edit Sounds | Sounds | ✓ | ✓ |  |
| `sounds:delete` | Delete Sounds | Sounds | ✓ | ✓ |  |
| `sounds:play` | Play Sounds | Sounds | ✓ | ✓ | ✓ |
| `history:read` | Read Stream History | Stream History | ✓ | ✓ | ✓ |
| `history:share` | Share History Reports | Stream History | ✓ | ✓ |  |
| `history:export` | Export History Reports | Stream History | ✓ | ✓ | ✓ |
| `history:delete` | Delete Stream History | Stream History | ✓ | ✓ |  |
| `history:revenue-read` | Read Estimated Revenue | Stream History | ✓ | ✓ |  |
| `history:revenue-edit` | Edit Revenue Assumptions | Stream History | ✓ | ✓ |  |
| `history:keywords-edit` | Edit Tracked Keywords | Stream History | ✓ | ✓ |  |
| `public-stats:read` | Read Public Stats Settings | Public Stats | ✓ | ✓ | ✓ |
| `public-stats:edit` | Edit Public Stats Settings | Public Stats | ✓ | ✓ |  |
| `audit-log:read` | Read Audit Log | Audit Log | ✓ | ✓ |  |

User-scope (`ideas:*`) and admin-scope permissions are separate registries - see [User Roles](./user-roles.md) and [RBAC & Permissions](./rbac-permissions.md#admin-scope-permissions).

---

`chat:pin` is an account permission seeded for Owner, Administrator and Moderator. It guards the GraphQL and REST Twitch pin actions; reading the current card uses `chat:read`. The acting moderator also needs a Twitch login with `moderator:manage:chat_messages`.

## Checklist for Adding a New Feature with Permissions

Use this checklist whenever you add a new feature that requires access control:

- [ ] **1. Define constants** in `crates/lo-auth/src/rbac.rs` (`pub mod account {}`)
  - `RESOURCE_READ`, `RESOURCE_CREATE`, `RESOURCE_EDIT`, `RESOURCE_DELETE`
  - Add domain-specific actions if needed (e.g., `RESOURCE_EXECUTE`)
- [ ] **2. Add to default roles** in `rbac.rs`
  - Owner: all new permissions
  - Administrator: all except `account:delete` and `plan:edit`
  - Moderator: read + relevant domain actions
- [ ] **3. Add GraphQL guards** to all resolvers in `apps/api/src/graphql/`
  - `#[graphql(guard = "lo_graphql::PermissionGuard::new(\"resource:read\")")]`
- [ ] **4. Add REST guards** to all route handlers in `apps/api/src/routes/`
  - `auth.require_permission(account::RESOURCE_READ).map_err(from_auth_error)?;`
- [ ] **5. Register the permission once** in `crates/lo-auth/src/rbac.rs`
  - Add a `p!(KEY, "Label", "Category")` entry to `account::get_all_account_permission_infos()`
  - **All pickers derive from it automatically** - no per-picker edits:
    - Web role editor: REST `GET /v1/roles/permissions` + GraphQL `availablePermissions`
      (`apps/api/src/{routes,graphql}/roles.rs`) map the registry
    - **Admin override pickers (ZAF-430):** the per-user (`/admin/users/[id]`) and per-account
      (`/admin/accounts/[id]`) override pickers fetch `GET /api/assignable-permissions`
      (→ `adminAssignablePermissions` GraphQL, mapping the same registry). **No hardcoded
      arrays** - do not reintroduce the old `ALL_USER_PERMISSIONS` / `ALL_ACCOUNT_PERMISSIONS`
      shadow lists that once drifted.
- [ ] **6. Write DB migration** in `apps/api/migrations/`
  - Backfill permissions for all affected default roles
  - Use `ON CONFLICT DO NOTHING` for idempotency
- [ ] **7. Add translations** in `apps/web/messages/en.json` and `apps/web/messages/de.json`
  - Permission labels under `"permissions"`: `"resource:read": "Read Resource"`
  - Category under `"permissions.categories"`: `"Resource": "Resource"`
- [ ] **8. Add sidebar nav entry** in `apps/web/src/app/(main)/(app)/shell.tsx`
  - `{ href: "/dashboard/resource", permission: "resource:read", ... }`
- [ ] **9. Wrap page** with `<PermissionErrorBoundary permission="resource:read">`
- [ ] **10. Gate write controls** with `<Gate permission="resource:create">` etc.
- [ ] **11. Create Next.js proxy routes** in `apps/web/src/app/api/resource/`
  - `GET` → `serverGql()` → Rust GraphQL query
  - `POST` / `PATCH` / `DELETE` → `serverGql()` → Rust GraphQL mutation
- [ ] **12. Run lint** - `just lint-all` (clippy + ESLint, zero warnings)

---

## Key Files Reference

| File | Purpose |
|------|---------|
| `crates/lo-auth/src/rbac.rs` | Permission constants, `get_all_account_permission_infos()` registry, default role definitions |
| `apps/api/src/graphql/roles.rs` | GraphQL `availablePermissions` picker + role create/update validation |
| `apps/api/src/routes/roles.rs` | REST `GET /v1/roles/permissions` picker + validation |
| `apps/api/src/db/roles.rs` | `create_default_roles()` - inserts the three default roles per account |
| `apps/api/src/graphql/admin.rs` | GraphQL `adminAssignablePermissions` (admin override pickers, ZAF-430) |
| `apps/admin/src/app/api/assignable-permissions/route.ts` | Admin proxy serving the registry to the override pickers |
| `apps/api/migrations/` | DB migrations for backfilling permissions |
| `apps/web/messages/en.json` | English translations for permissions + role names |
| `apps/web/messages/de.json` | German translations for permissions + role names |
| `apps/web/src/app/(main)/(app)/shell.tsx` | Sidebar nav with permission filtering |
| `apps/web/src/lib/translate-role.ts` | `useTranslateRole()` hook for default role names |
| `apps/web/src/contexts/permission-context.tsx` | `PermissionProvider`, `usePermissions()`, `useHasPerm()` |
| `apps/web/src/components/gate.tsx` | `<Gate>` declarative permission component |
| `apps/web/src/components/permission-error-boundary.tsx` | Page-level access denial component |

---

## Developer Guide / Frontend Permission System

Source: https://docs.lumio.vision/developer-guide/frontend-permissions

# Frontend Permission System

This guide explains how the frontend permission system works and how to use it when developing new features.

## Architecture

Permissions flow from the backend to every component:

1. **Server Layout** calls `getMe()` which returns `permissions: string[]` for the active account
2. **PermissionProvider** (React Context) makes permissions available to all client components
3. **Hooks and components** use `usePermissions()`, `useHasPerm()`, `<Gate>`, and `<PermissionErrorBoundary>` to gate UI elements

## API Reference

### `usePermissions(): string[]`

Returns the full array of permissions for the current user's active account.

```tsx
const permissions = usePermissions();
```

### `useHasPerm(permission: string): boolean`

Returns whether the current user has a specific permission. The check is `perms.includes("*") || perms.includes(permission)` - the `"*"` wildcard is only ever present on a System-key identity, never on an account role.

```tsx
const canEdit = useHasPerm("overlays:edit");
```

Permissions are granular: there is no `resource:write`. Write actions map to `create` / `edit` / `delete` (plus domain actions such as `overlays:access-grant`).

### `<Gate permission="...">`

Conditionally renders children only if the user has the specified permission. Renders nothing otherwise.

```tsx
<Gate permission="overlays:create">
  <Button onClick={createOverlay}>Create Overlay</Button>
</Gate>
```

### `<PermissionErrorBoundary permission="...">`

Renders a "No Access" fallback UI when the user lacks the required permission. Use this to wrap entire page content for direct URL access protection.

```tsx
<PermissionErrorBoundary permission="spotify:read">
  <MusicPlayer />
</PermissionErrorBoundary>
```

### `useToast()`

Exposes `showToast(message, type)` for displaying toast notifications. Used for 403 error feedback.

```tsx
const { showToast } = useToast();

if (res.status === 403) {
  showToast(t("permissions.forbidden"), "error");
}
```

## Adding New Permissions

When adding a new permission to the system, follow this checklist:

1. **Add constant** in `crates/lo-auth/src/rbac.rs` (in `pub mod account {}`)
2. **Update default roles** in `rbac.rs` (`ROLE_OWNER`, `ROLE_ADMIN`, `ROLE_MODERATOR`)
3. **Register it once** in `account::get_all_account_permission_infos()` (same file) - a `p!(KEY, "Label", "Category")` entry. Every picker and the validation registry derive from that list; there is no second list to edit.
4. **Write DB migration** to add the permission to existing roles
5. **Add GraphQL guard** -- `#[graphql(guard = "lo_graphql::PermissionGuard::new(\"perm:name\")")]`
6. **Add REST guard** -- `auth.require_permission("perm:name").map_err(...)?;`
7. **Add `#[utoipa::path]` description** noting the required permission
8. **Add sidebar mapping** in `apps/web/src/app/(main)/(app)/shell.tsx`
9. **Wrap page** with `<PermissionErrorBoundary permission="perm:read">`
10. **Gate write controls** with `<Gate permission="perm:create">` / `perm:edit` / `perm:delete`
11. **Update docs** in `apps/docs/docs/api-reference/permissions.md`
12. **Update docs** in `apps/docs/docs/user-guide/roles-and-permissions.md`

## Route-segment gates

Hiding a nav item in `shell.tsx` does not close the route - a deep link still renders the page. Two layers cover that:

- **Feature flags** - each gated dashboard segment has a `layout.tsx` that wraps `children` in `<FeatureRouteGate feature="feature:...">` (`apps/web/src/components/feature-route-gate.tsx`), so every page and nested route under the segment is covered by one gate.
- **Permissions** - page content is wrapped in `<PermissionErrorBoundary permission="...">`. Wrap the top-level client component of the segment, not individual widgets, so direct URL access is caught too.

Sidebar entries in `shell.tsx` carry both a `permission` and (where applicable) a `feature` key; the shell filters items on both and hides sections that end up empty.

## Popout Pages

Popout pages (music, events, chat) operate outside the dashboard layout and need their own permission handling.

### Pattern

1. **Server component** fetches permissions:
   - Popout token: `GET /v1/tokens/me?token=xxx` via `serverFetch()`
   - Cookie auth: `getMe(config).permissions`
2. **Client wrapper** wraps content in `<PermissionProvider>` + `<ToastProvider>`
3. **Components** use `<Gate>` and `useHasPerm()` - same as dashboard
4. **Hooks** pass popout token via `withToken()` to all API calls

## Key Files

| File | Purpose |
|------|---------|
| `apps/web/src/contexts/permission-context.tsx` | PermissionProvider + hooks |
| `apps/web/src/contexts/toast-context.tsx` | Toast system |
| `apps/web/src/components/gate.tsx` | Declarative permission gate |
| `apps/web/src/components/permission-error-boundary.tsx` | Page-level access denial |
| `apps/web/src/components/feature-route-gate.tsx` | Feature-flag gate used by segment `layout.tsx` files |
| `apps/web/src/app/(main)/(app)/shell.tsx` | Sidebar permission + feature filtering |
| `crates/lo-auth/src/rbac.rs` | Permission constants, default roles, and `get_all_account_permission_infos()` registry |
| `apps/api/src/graphql/roles.rs` | GraphQL `availablePermissions` picker (maps the registry) |
| `apps/api/src/routes/roles.rs` | REST `GET /v1/roles/permissions` picker + role validation |

---

## Developer Guide / Frontend Overlays: Dialogs and Full-Screen Panels

Source: https://docs.lumio.vision/developer-guide/frontend-overlays

# Frontend Overlays: Dialogs and Full-Screen Panels

The `@lumio/ui` design system (`shared/ui`) has two modal surfaces. This page covers how they
stack, how Escape and scroll locking compose, and the one rule that keeps a nested dialog visible.

| Primitive | Renders | Use for |
|-----------|---------|---------|
| `Dialog` / `DialogContent` | **Portaled** to `<body>`, or into the panel or dialog that opened it; `fixed inset-0 z-[100]` | Confirmations, warnings, small forms and `variant="sheet"` side sheets |
| `FullscreenPanel` | Portaled to `<body>` or the enclosing overlay layer, `fixed inset-0 z-[100]` | Full-page views and the dashboard settings window |
| `FullscreenWizard` | `FullscreenPanel` + the `WizardSteps` core (progress bar, Back/Next footer) | Create/edit flows with steps |
| `SetupWizard` | `Dialog` + the same `WizardSteps` core | Stepped flows inside a dialog |

## Layer scale

`DialogContent variant="sheet"` uses the same Dialog focus trap, Escape stack and scroll lock. It sits on the right at desktop widths and fills a phone screen; `hideClose` suppresses the built-in close button when the sheet header provides one. `AlertDeck` also accepts controlled `selectedKey` and `onSelectedKeyChange`; the dashboard shell's `ConnectionAlertsContext.focusAlert(key)` restores, selects, scrolls to and focuses a connection notice.

`FullscreenPanel frame="window"` renders the dashboard settings window as a card up to 1536 × 960 px, with 24 px desktop edge spacing. Below 768 px it fills the screen. The root remains a full-screen overlay layer, while the backdrop and card are children, so nested dialogs and wizards can cover the whole viewport. `onBackdropClick` runs only when pointerdown and click both land on the backdrop and the window was topmost at pointerdown. Nested `FullscreenPanel` and `FullscreenWizard` instances portal into the enclosing layer root; their focus traps count only their own layer's tab stops. Escape closes the topmost layer first, and the shared reference-counted scroll lock remains until the last layer closes.

`DialogContent mobile="fullscreen"` fills the screen below `sm` for forms, selections and stepped flows. Its header and footer stay visible while the body scrolls, and footer buttons stack with the primary action first. Confirmations and identity step-up use the default card treatment. Motion preferences reduce the phone entrance to a fade or make it instant.

Stacking order, low to high:

| z-index | Layer |
|---------|-------|
| `z-40` | Dropdown/menu backdrops |
| `z-50` | Full-screen side panels and inline dropdowns (popout settings, chat-shell menus) |
| `z-[100]` | Modal layer: `Dialog`, `FullscreenPanel`, `FullscreenWizard`, editor modals |
| `z-[9999]` | Popovers that must float above their own dialog (`ColorPicker`) |
| `z-[10000]` | Toasts (`ToastProvider`, portaled to `<body>`), above modals and full-screen editors |
| `99999` | Tooltips (`TooltipProvider`) |

`ToastProvider` portals the toast stack to `<body>` after mount. An ancestor with its own z-index
creates a stacking context that could otherwise trap an inline toast behind a modal or full-screen
editor. The body portal keeps toasts above those surfaces and below tooltips.

## Toast dismissal

Every success, info and error toast has a close (✕) button, including toasts with an action such as
**Undo**. The button sits above `SeasonToastAccent` so the seasonal decoration cannot cover it or
intercept clicks. Each toast dismisses automatically after five seconds. Its own countdown pauses while
the pointer is over that toast or it has keyboard focus, then resumes with the remaining time. Closing
one toast leaves the others' countdowns alone.

Clicking ✕ uses the same 150 ms exit fade as automatic dismissal; with Motion Off, the toast disappears
immediately. A toast does not register with the Escape dismiss stack: Escape does not close it, even
when its close button has focus. Escape remains available to the topmost dialog or panel underneath.

## The stacking rule: nest dialogs inside the panel

`DropdownMenu` (the ⋯ menus) portals into the enclosing overlay layer — a `Dialog` or
`FullscreenPanel` root such as the settings window — and only falls back to `<body>`. Its `z-50`
then counts inside that layer, so a menu opened in a dialog or in the settings window stacks above
it instead of behind it.

`Dialog` and `FullscreenPanel` sit on the **same** `z-[100]`. On a tie the browser paints by DOM
order. A panel root is an overlay layer: a `Dialog` rendered in the panel's React subtree portals into
the panel root, so it is a DOM descendant and stacks above the panel. A Dialog rendered as a
**sibling** of a panel portals to `<body>` beside it and can be painted **behind** it, invisible:

```tsx
// ✗ Wrong — the Dialog is a sibling of the panel and can land behind it.
<>
  <FullscreenPanel …>{content}</FullscreenPanel>
  <Dialog open={confirmOpen} …>…</Dialog>
</>
```

Render every overlay the panel's content opens **inside** the panel. The `layers` slot exists for this:
its children render last inside the portal root, so they stack above the panel content:

```tsx
// ✓ Right — the Dialog is a DOM descendant of the panel root.
<FullscreenPanel
  title={<h2 id={titleId}>{name}</h2>}
  ariaLabelledBy={titleId}
  closeLabel={tc("close")}
  onClose={onClose}
  layers={
    <>
      {pending && <Dialog open onOpenChange={() => setPending(null)}>…</Dialog>}
      <LinkWarningDialog url={pendingLink} onClose={() => setPendingLink(null)} />
    </>
  }
>
  {content}
</FullscreenPanel>
```

Cover it with a test that asserts DOM descendancy
(`panel.contains(dialog)` where `panel = document.querySelector("[data-fullscreen-panel]")`), like
`apps/web/__tests__/components/info-user-modal-layers.test.tsx` does for the user info card.

Absolutely positioned menus are the other trap: inside a scrolling region (`overflow-y-auto`) they
are clipped at its edge. Prefer an inline disclosure (the user card's Timeout durations), or a
component that portals itself (`Select`, `DropdownMenu`).

A box marked `data-popover-boundary` (`POPOVER_BOUNDARY_ATTR` from `@lumio/ui`) bounds the floating
lists opened inside it. The settings window card carries it, so a `Select` list in the window stays
within the card: it is at most as wide as the card, flips to the trigger's other edge or shifts
against the card's sides, and opens upwards when it does not fit below. Outside such a box the
viewport bounds the list. Rows truncate by default; `SelectItem wrap` lets a row with an explanation
under its label wrap instead (the member role picker).

The channel picker that `?account_select=true` shows after a sign-in with several channels sits on
`z-[110]`, above the modal layer. While it is up the dashboard shell keeps the settings window
closed, even with `#settings…` in the address; picking a channel reloads the same address without
the parameter, and the window opens on the chosen channel.

## Why the Dialog root portals

`DialogContent` portals its `fixed inset-0` root to `<body>` (or into the enclosing overlay layer, see
above). Rendered inline, the root would take on its parents' layout:

- a `space-y-*` parent gives it a `margin-bottom`, so the backdrop stops short of the bottom edge and a
  strip of the page stays sharp and clickable;
- an ancestor with `transform`, `filter`, `backdrop-filter` or `contain` becomes its containing block,
  so the backdrop covers only that ancestor's box;
- an ancestor with its own z-index (the app footer's `relative z-10`) traps the dialog's `z-[100]` in
  its stacking context, below the dashboard sidebar (`sticky z-30`) and the mobile header (`fixed z-50`).

Call sites therefore render a `Dialog` wherever its trigger lives; no local `createPortal` is needed.
`shared/ui/__tests__/dialog-portal.test.tsx` covers the body and in-panel cases;
`apps/web/__tests__/components/cookie-manager-portal.test.tsx` asserts the footer case
(`footer.contains(dialog) === false`).

## Dialogs on a phone

A centred dialog taller than the viewport starts at the top edge and the backdrop scrolls (the root is
`items-start overflow-y-auto`, the panel centres with `my-auto`). Initial focus does not scroll, so a
dialog opens at its top. A dialog with a header and a footer band keeps both on screen: the panel is
`flex max-h-full flex-col`, header and footer are `shrink-0`, and the middle is
`min-h-0 overflow-y-auto`. The Settings/Security frame (`HubDialogContent`, `HubDialogBody`,
`HubDialogFooter` in `apps/web/src/components/account-hub/hub-dialog.tsx`) does this for every dialog
built on it; a `<form>` that wraps body and footer needs `flex min-h-0 flex-col` as well. Cap a dialog
with `max-h-full` or `dvh` units, not `vh`: in mobile Safari `90vh` is taller than the visible area.

## Escape: only the topmost layer closes

Every overlay registers on one shared, ordered dismiss stack (`useEscapeDismiss` in
`shared/ui/src/escape-dismiss.ts`), driven by a single capture-phase listener. Escape runs only the
topmost layer's handler and is consumed. So with a confirmation open on a panel, the first Escape
closes the confirmation and the second closes the panel. Never add an ad-hoc `keydown` Escape
listener inside an overlay. Register with `useEscapeDismiss(onDismiss, active)` instead.

## Scroll lock

`Dialog` and `FullscreenPanel` share one reference-counted page scroll lock (`useScrollLock` in
`shared/ui/src/scroll-lock.ts`). The page is locked while at least one holder is open, so a nested
Dialog closing, or a closed Dialog mounting, never releases a panel's lock, whatever order React
runs the cleanups in.

The lock sets `overflow: hidden` on `<html>` only and never touches `<body>`. If both carry a
non-`visible` overflow, `<body>` becomes a scroll container of its own and every `position: sticky`
element sticks to it instead of the window: the dashboard sidebar would slide up by the page's scroll
offset whenever a dialog opens. Do not pin the body with `position: fixed; top: -scrollY` either; it
causes the same jump. While locked, `<html>` is padded by the width of the page scrollbar, so content
does not shift sideways on systems with classic scrollbars (nothing is added with overlay
scrollbars). Scrolling regions inside an overlay use `overscroll-contain`, so a touch scroll that
reaches their end does not move the page behind (the `FullscreenPanel` body region already does).

## `FullscreenPanel` API

| Prop | Purpose |
|------|---------|
| `title` | Header title slot (the caller renders its own heading) |
| `actions` | Header actions, right-aligned before the close button |
| `closeLabel` | **Required.** Translated accessible name of the close (X) button |
| `onClose` | Called by the X button and Escape |
| `showClose` | Hide the X (Escape still calls `onClose`) |
| `children` / `scrollBody` | Body content; scrolls inside the body region unless `scrollBody={false}` (the wizard manages its own scrolling) |
| `footer` | Optional pinned footer row |
| `layers` | Nested overlays (see the stacking rule) |
| `accentColor` | 2-px accent line along the top edge (e.g. a platform colour) |
| `backdrop` | `"opaque"` (default, `bg-background`) or `"blur"` (`bg-background/85` + `backdrop-blur-md`) |
| `overlay` | Decorative background slot behind all content (e.g. a platform gradient) |
| `ariaLabelledBy` / `ariaLabel` | Turn on dialog semantics: `role="dialog"`, `aria-modal`, focus moved in on open, Tab trapped, focus restored on close |

There is **no `open` prop**. The caller mounts the panel only while it should be visible
(`if (!open) return null;`), so its scroll lock and Escape layer live for exactly one open lifetime.
`FullscreenWizard` follows the same rule.

---

## Developer Guide / Dashboard UI Primitives

Source: https://docs.lumio.vision/developer-guide/frontend-ui-primitives

# Dashboard UI Primitives

## Overview

`@lumio/ui` provides presentation and interaction primitives used by the Stream History list and report. The app supplies translated text, data loading, links and permissions. Import the components and helpers from `@lumio/ui` rather than copying their layout or drawing code into a dashboard feature.

| Primitive | What it supplies | Current History use |
|-----------|------------------|---------------------|
| `Sparkline` and `sparklineGeometry` | A trend line in real SVG pixels, with an optional filled area and a `peak` or `last` marker | Viewer trends in the history table and the start page's recent streams, KPI trends in reports and on the start page |
| `StatTile` and `STAT_TILE_FRAME` | A figure tile with `icon`, `label`, `value`, `sub`, `aside` and `footer` slots; the frame constant also fits its loading skeleton | Overview tiles and report KPIs |
| `CalendarHeatmap` and its model helpers | A keyboard-accessible year grid with range highlighting, a legend and a day tooltip | Streaming activity calendar |
| `Button` toolbar sizes and `TOOLBAR_CONTROL_CLASS` | Matching 36 px controls with rounded corners | History filters, export and sort controls |
| `Badge` variants `live` and `accent` | Soft red and brand-tinted labels | Live and multistream indicators |
| `PlatformButton` | A brand-coloured button that leads to a platform, with logo, pending state and corner badge | Sign-in, step-up, linking, channel and bot connect, reconnect |
| `LumioMark` | The Lumio logo mark, `brand` (teal gradient) or `admin` (grey) | Every app header, footer and sign-in card |

## Trend lines and tiles

`Sparkline` accepts numeric `values`, a required pixel `height`, an optional fixed `width`, `area`, `marker` (`peak`, `last` or `none`), and `markerTone` (`line` or `destructive`). Without a width it measures its container, so the line and dots keep their proportions. `sparklineGeometry()` returns the line and area paths, the peak and last coordinates, and `points` (the box coordinates of every value, `null` for a gap); fewer than two finite points return `null`.

An optional `hover` (`{ label(index), value(value, index) }`) turns on the hover mode: a pointer move, or tap-and-drag on touch, snaps to the nearest step with a value (`sparklineNearestIndex()`) and shows a vertical rule, a dot and a tooltip with the label and the formatted value. A gap shows "–", never 0. The tooltip uses the popover surface, appears without motion, stays inside the box horizontally and sits above it, so the parent must not clip it. On touch the step stays after the finger lifts and clears on the next tap outside. `activeIndex` and `onActiveIndexChange` make the step controlled, so several sparklines can show the same step. The component stays `aria-hidden` and adds no tab stop: hover mode is a pointer enhancement, and the accessible values belong in a full chart or table next to it. Without `hover` the sparkline is the static line.

The graphic is always `aria-hidden` and has no animation. Place the number and its meaning in nearby text. History uses a peak marker for finalized viewer trends and viewer/message KPIs, a red last marker for live viewer trends, and a last marker for follower growth. The per-session viewer trend is one component, `ViewerTrend` (`apps/web/src/components/history/viewer-trend.tsx`), used by both the history table and the start page's recent-stream rows, so the two cannot drift apart; it takes its width from `className`. The start page's KPI tiles plot one value per day, so they keep the area and mark the peak, like the per-step KPIs of a report.

`StatTile` renders its label, large value and secondary line with optional top-right `aside` and bottom `footer`. Its `STAT_TILE_FRAME` gives skeletons the same outer dimensions as the populated tile, so loading does not move the surrounding layout.

## Activity calendar

`CalendarHeatmap` receives local-day buckets, today's local date, first weekday, locale, translated `labels`, and a `describeCell` callback for accessible day names. `onSelectDay` handles click, Enter and Space. Optional `selectedFrom` and `selectedTo` dim days outside a selection. The grid uses one tab stop and arrow-key navigation; on phones it scrolls horizontally toward today.

The grid fills its container's width and available height. Its seven rows share that height, with a width-derived square cell as the minimum: cells stay square in a width-bound card and grow taller when a neighboring card makes the row taller. The legend stays at the bottom. Give the component a height-bearing flex-column parent, as the History list's `HeatmapFrame` does, so the grid can use that extra space.

The component uses the shared `Popover` for a day tooltip on hover, focus or tap. The caller supplies its content through `renderTooltip`. History's `ActivityHeatmap` wrapper owns the translated stream details, any data fetch and the report link; the shared grid contains none of those app rules. See [Frontend Overlays](/developer-guide/frontend-overlays) for the floating-panel behavior.

The model exports `buildHeatmap`, `toggleDay`, `moveFocus`, `inRange`, `levelFor`, `HEATMAP_WEEKS`, and the `CalendarHeatmapDay` / `HeatmapCell` types. Use them for calendar calculations rather than duplicating date-grid logic.

## Toolbar controls and badges

Use `Button` sizes `toolbar` and `toolbar-icon` for filter rows. `TOOLBAR_CONTROL_CLASS` gives a `SelectTrigger` or popover trigger the same 36 px height, `rounded-md` corners and label weight. A `Select` menu is as wide as its widest option, including the full placeholder of a `searchable` menu's search field: never narrower than the trigger, and at most 24rem and the viewport width minus 16 px. Under a compact trigger every option therefore stays on one line. Near a window edge the menu keeps that width and moves instead of shrinking. It opens under the trigger's left edge when it fits there. Otherwise it lines up with the trigger's right edge and opens towards the left. Only when neither edge fits is it shifted to stay 8 px inside the window. `Popover` panels with `align="start"` or `"end"` flip between the two trigger edges the same way. A menu only gets narrower than its content when the viewport itself is narrower, as on a phone. Option rows then stay on one line, are truncated with an ellipsis, and show their full text as a tooltip on hover. The menu never scrolls sideways. The size is fixed when the menu opens, so typing in a `searchable` menu does not resize it. Pass `matchTriggerWidth` to `SelectContent` only when the menu must be exactly as wide as its trigger. `Badge` variant `live` is a soft red indicator; `accent` is a soft brand tint for a neutral tag such as Multi.

## Text fields on phones

iOS Safari zooms the whole page in when a text field with a font size below 16 px gets focus. `@lumio/ui/globals.css`, which every app imports, therefore sets every text-entry field to at least 16 px below the `sm` breakpoint (640 px). That covers `<input>` (except checkbox, radio, range, colour, file and button types), `<textarea>`, `<select>` and contenteditable editors such as the chat input. From `sm` up nothing changes, so `Input` and the other primitives keep `text-sm` on desktop.

The rule is unlayered and `!important`, so it wins over a caller's `text-xs` or `text-sm` and over an inline `style={{ fontSize }}`. You do not need to write `text-base sm:text-sm` on a field. A field whose class is `text-base` or larger keeps its own size. A field that sets its size inline also sets `--lm-field-font-size` to the same value, for example `style={{ fontSize: "0.9em", ["--lm-field-font-size" as string]: "0.9em" }}`. The rule then uses whichever is larger, 16 px or that value, so a user-scaled popout field is never made smaller on a phone.

Never stop the zoom by capping the scale or turning off user scaling in a `viewport` export. That also blocks pinch-zoom, which people with low vision rely on. `shared/ui/__tests__/mobile-field-font-size.test.tsx` checks that the rule stays outside every `@layer` and that every field primitive matches it.

## Platform buttons

Every button that leads to a platform uses `PlatformButton` from `@lumio/ui`: sign-in, linking, step-up, reconnect, and channel or bot connect. This applies in the ID app and in the dashboard. The button is filled with the platform's brand colour and shows the logo in the text colour. `provider-button.ts` (`PLATFORM_BUTTON_SURFACES`) holds the colours:

| Platform | Surface | Text and logo |
|---|---|---|
| Twitch | `#9146FF` | white (4.64:1) |
| Kick | `#53FC18` | `#0B0E0F` |
| Discord | `#5865F2` | white (4.61:1) |
| YouTube | `#E6002E` | white (4.77:1). Brand red `#FF0033` reaches only 3.96:1. |
| Spotify | `#1DB954` | `#0B0E0F` |
| Google | `#FFFFFF`, border `#747775` | `#1F1F1F`, multicolour G |

The colours are literal values, not theme tokens, so they are the same in dark and light mode. Google's sign-in guidelines forbid recolouring its button, so Google uses its light variant in both themes and keeps the same shape and size as the others. An unknown platform falls back to the neutral outline surface.

- **Sizes:** `lg` is 44 px (sign-in and step-up, full width), `md` is 40 px (dialog footers, the default), `sm` is 36 px (inside rows).
- **Logo:** `pinLogo` (the default at `lg`) pins the logo 14 px from the left edge and centres the label, so stacked buttons line up. Otherwise logo and label sit together in the centre (e.g. the small `sm` buttons on dashboard cards). The sign-in page stacks its provider buttons in one column with the logo pinned.
- **Pending:** set `pending` and `pendingLabel` ("Continuing to Twitch …"). The ring takes the logo's place, the width stays the same, the button is disabled with `aria-busy`, and the label is announced.
- **Extras:** `badge` puts a label such as "Last used" on the top-right corner, outside the label area. `trailing` adds an icon after the label, e.g. the external-link arrow in the connect dialog. `asChild` renders an `<a href>` child with the button's look.

The YouTube channel card shows the YouTube logo: connecting a channel grants API access and is not a sign-in. The connect dialog behind the card continues with Google, because that is where the browser goes.

## The Lumio mark

Every Lumio logo in the apps is `LumioMark` from `@lumio/ui`. Never paste the SVG into a component.

- **Size** it with `className` (`h-8 w-8`); the smallest size is 24 px. It is decorative (`aria-hidden`) unless it gets a `title`, which makes it `role="img"` with that label. Next to the visible word "Lumio", leave it decorative.
- **Variants:** `brand` (default) draws the teal gradient from the tokens `--brand-gradient-start` and `--brand-gradient-end` in `shared/ui/src/globals.css`. They are the same in light and dark: the mark is never recoloured. `admin` is the grey operator-app mark and is never used outside the admin app.
- **Without CSS** (`next/og` share images, e-mail): `lumioMarkSvg()` returns the same mark as an SVG string with literal colours.
- **Files** for everything outside the apps (press, social profiles, video) are in `assets/brand/`: the mark as SVG and as 512 and 1024 px PNG, the outlined wordmark and the lockup. Next's `icon.svg` files, the docs-site logos and the e-mail logo are file copies; `shared/ui/__tests__/lumio-mark.test.tsx` fails when one of them drifts from the component's geometry or colours.
- **Seasonal looks:** in the dashboard, `SeasonalLogo` and `SeasonalBrand` show the season's logo at Subtle and Full. The regular mark they receive as `children` is `LumioMark`.

## Typeface

The UI typeface is Roboto, served by each app itself. Nothing is fetched from Google at build time or in the browser.

- **Source:** the npm package `@fontsource-variable/roboto` (pinned in `pnpm-lock.yaml`), a dependency of `apps/web`, `apps/admin`, `apps/id` and `apps/stats`. One variable WOFF2 per style (normal, italic) covers weights 100 to 900; the latin subset covers English and German. Characters outside it fall back to the next font in the stack.
- **Loading:** each app's `src/lib/fonts.ts` calls `next/font/local` with those files. Next.js copies them to `/_next/static/media/`, preloads them, and generates a size-adjusted fallback face from the font's metrics, so the swap from the fallback to Roboto does not shift the layout.
- **Wiring:** every root layout puts `roboto.variable` on `<html>`, which defines `--font-roboto`. In `shared/ui/src/globals.css`, the `@theme` tokens `--font-sans` (read by the `font-sans` utility on `<body>`), `--font-body` and `--font-heading` name `var(--font-roboto)` first. `--font-mono` is unchanged.
- **New root layout:** a new route group with its own `<html>` imports `roboto` from `@/lib/fonts` and adds `className={roboto.variable}` to `<html>`. `apps/web/__tests__/root-layout-font.test.ts` fails when a root layout misses it. The overlay root layout (`apps/web/src/app/(overlay)/layout.tsx`) is exempt: stream output keeps its own fonts through the API font proxy.

---

## Developer Guide / Seasonal Look — Code and Artwork

Source: https://docs.lumio.vision/developer-guide/seasonal-look

# Seasonal Look — Code and Artwork

The seasonal dashboard look (user-facing behaviour: [Preferences → Seasonal Look](/user-guide/preferences#seasonal-look)) lives in `apps/web`: the season calendar and looks in `src/lib/seasons/registry.ts`, the slots and artwork components in `src/components/seasons/`.

The dashboard banner's settings link targets `/dashboard/settings/appearance/seasonal-look`. The settings areas and their content fade work with seasonal look off, Full and Subtle; decorations stay behind controls and dialogs.

**Artwork source of truth: `assets/seasons/<season-id>/`** at the repository root (for example `assets/seasons/halloween/` and `assets/seasons/nicholas/`, with a `README.md` per season listing each file's use and colour). The files are plain SVG, drawn in-house, with no third-party licence. The React components copy each file's geometry verbatim — ids become `useId()`-unique, class and data hooks follow the app's CSS, colours may move to CSS — and `apps/web/__tests__/components/season-assets-parity.test.tsx` fails when a component drifts from its file or when a file in the folder is not registered there. To change a graphic, change the SVG file first, then the component.

## Scenery colours and motion

Scenery colours are season tokens, declared per theme in the registry entry (`look.tokens.light` / `look.tokens.dark`) and emitted only under `html[data-season=<id>]`. Halloween uses `--season-moon`, `--season-moon-halo`, `--season-bat` and `--season-spider`; unlike the base-theme tokens these may carry their own alpha (`H S% L% / a`), because light and dark need different strengths. Components read them as `hsl(var(--season-…))` — never a hard-coded colour.

St. Nicholas uses `--season-snow`, `--season-star`, `--season-glow`, `--season-frame`, `--season-pane`, `--season-frost`, `--season-window`, and `--season-string` for its snow, stars, arched window, lit roofs and compact garland cord. These season-only tokens may also carry alpha. The boot and robin artwork use a fixed palette where the drawing requires it.

Motion has two layers, both transform/opacity only:

- **CSS** (`src/lib/seasons/styles.ts`): slow drifts and floats (`.season-bat`, `.season-float`), defined only inside `@media (prefers-reduced-motion: no-preference)` and under `html[data-season-motion="auto"]`. The one exception is the loader's `.season-ghost`: a loading indicator must always signal activity, so its base rule (outside the media query) is an opacity-only pulse in sequence (0.3 → 1, 1.2 s, staggered 0.2 s); with motion allowed the same elements switch to a bob-and-sway (≈ 7 px, 1.2 s, staggered 0.15 s) — except inside a surface whose own *Animations* override (Chat, Events, Music) is Reduced or Off (`data-motion` on the surface root): an ungated rule with one more attribute keeps the pulse there.
- **Web Animations** for scheduled and random movement — the seasonal brands, Halloween wing-flap bursts and fly-by (`src/lib/seasons/scenery-motion.ts`), and St. Nicholas boot, shooting star and robin (`src/lib/seasons/nicholas-scenery-motion.ts`). Their timing logic is DOM-free and takes an injected RNG and clock. Scenery schedules only while `sceneryMayMove()` holds — the season is active at Full, **Animations: Automatic**, no reduced motion, tab visible — and a stop drops every pending timer, so nothing is caught up. Halloween's fly-by chain schedules its next wait only after the current flight has finished, so two fly-bys never overlap. The corner-web spider works the same way (`src/lib/seasons/spider-motion.ts`, `spiderMayMove()` = switched on and `sceneryMayMove()`): one wait → move → wait chain, 20–40 s waits, a crawl along one strand of the web (it stays where it stopped) or, about a quarter of the time, a drop on a thread and back. Each season's `Scenery` component receives `{ active, strength, motion, creatures }` from `SeasonDecorations`.

## Registry assets and St. Nicholas scenery

`SeasonAssets.Icon` is the Lucide icon used by `SeasonalSpinner`. The optional `BannerIcon` is a React component used by every banner variant; when omitted, the banner uses `Icon`. St. Nicholas keeps `Icon: Star` for the loader and uses the Nicholas head drawing as `BannerIcon` and `EmoteIcon`. Halloween uses its existing `Icon` for both loader and banner.

The St. Nicholas `Scenery` fills the page's header band with three depths of snow, gold stars, a warm glow and an arched window. A boot sits on the sill with a robin beside it. The window starts 12 px below the band's top edge, leaving the arch and frame clear of the edge; from tablet width it sits 128 px from the right edge, clear of the header buttons, and its sill ends above the first card row. At Full with motion allowed, a shooting star occasionally lands in the boot; the boot reacts, and the robin can fly and return. `NicholasScenery` gates those Web Animations through `sceneryMayMove()` and `useMotionAllowed()` and stops them when the tab is hidden or motion is disallowed. The boot's spring reactions start at rest with an impulse; interruption settles from the current pose. Snow and star motion use CSS under the same seasonal motion gate.

The compact `Scenery` used behind the dashboard Chat and Events headers and popout headers has a 96 px band with a star garland, hanging boot and robin. Its container query shifts the garland 120 px left when the band is at least 640 px wide, leaving room around header controls. The robin can fly across the whole header and pass behind the hanging boot, header buttons and tab text. The scenery layer stays behind the content, `pointer-events: none` and `aria-hidden`; its position does not block clicks or obscure controls. At Subtle or with animation disallowed, the appropriate still artwork remains.

The St. Nicholas `EdgeStrip` puts snowy roofs above the footer and in the reserved 16 px row of the Chat, Events and Music input or search bars. Each 240 × 28 tile has five complete houses, including a small house at x 222–238 near the tile's end; its four larger ridges are peek positions. Chimney bottoms follow the roof slopes. Filled snow caps lie on all five roofs, thicker at the ridge with scalloped lower edges and short overhangs with drips; three chimney caps use the same `--season-snow` colour. The strip renders an explicit SVG copy for each tile at whole-pixel offsets (`roofsTileOffset()` rounds x and rounds y up to keep the houses against the strip's bottom edge). An SVG `<pattern>` at a fractional y can make Chrome sample a tile's wrapped bottom row and paint a faint line above the houses.

Each tile has six lit windows (`data-window` 0–5 in `roofs-strip.svg`): one in each house and two in the tallest. The strip renders them as individual `--season-window` rectangles above the tile shapes, at the same offsets (`data-window="<tile>:<n>"`, `data-lit`). This lets the window-light scheduler control each window independently across tiles.

Each strip has its own window-light scheduler in `src/lib/seasons/window-lights.ts`, independent of the page-wide `PeekCoordinator`. Every 12–30 seconds it dims one visible window over 500 ms; that window stays dark for 8–25 seconds, then lights over 700 ms. About one in four returns includes a double flicker: 120 ms opacity fades with changes at least 340 ms apart. At most one third of visible windows are dark at once, and the same window is not selected twice in a row. This changes opacity only. The scheduler runs while the strip is in view and `mayMove` permits Full, Animations Automatic, no reduced motion, a visible tab and an idle bar. When that gate closes, every window is lit again, instantly when motion is off or the strip leaves view. Subtle has no strip. A small Nicholas figure also peeks from a roof through the existing page-wide `PeekCoordinator` while the same eligibility gate holds.

## Loading indicator

Content loading uses layout-matched `Skeleton` placeholders from `@lumio/ui`, inside a `SkeletonRegion` with a translated screen-reader label. Skeletons use `bg-muted` and keep their opacity pulse under Reduced and Off, whether the seasonal look is off, Full or Subtle. See [Loading states](/developer-guide/loading-states) for the content rule and exceptions.

At the Chat and Events default-preset gate, the loading frame reserves the whole dashboard or popout shell. The seasonal banner and compact scenery render in their normal positions while the feed and preset-dependent controls use placeholders. A layout hint runs before paint, so saved header, footer and viewer-list placement already match the loaded shell. Music also keeps its page or popout frame while Spotify status and player content load.

`SeasonalSpinner` (`src/components/seasons/seasonal-slots.tsx`) is for a standalone wait without a content shape, such as an action hand-off; its children are the regular spinner. In scope it renders a `role="status"` container with an `sr-only` loading label (`seasons.loading`), the regular spinner (`data-season-default="full"`) and per season three `aria-hidden` copies of the season's `Icon` (`size`: `sm` / `md` / `lg` = 16 / 20 / 24 px); outside the dashboard scope it renders only its children. Inline spinners inside buttons and inputs stay ordinary so the control width does not change.

History list and report route skeletons use `Skeleton` and `SkeletonRegion` from `@lumio/ui`, shaped like the finished desktop table, phone cards and report grid. They are in-layout loading primitives, not standalone spinners: use theme tokens only and keep their opacity pulse visible at every motion level. The public share skeleton lives inside `ShareShell`, outside seasonal scope.

`SeasonalEmptyState` supports `history` (no sessions) and `history-filtered` (no matches, with a reset action) alongside Events and Chat. Both kinds have strings for every active look in `SEASON_MESSAGE_KEYS`; add kinds through the shared slot, never season-specific feature branches.

## Creatures

Every animal a look depicts is declared in its registry entry, in settings order, with its default: `look.creatures: [{ id: "bat", default: true }, { id: "spider", default: false }]` for Halloween; St. Nicholas declares `{ id: "robin", default: true }`. Ids are shared across seasons (`CreatureId`) and labelled under `seasons.creatures.<id>` in `messages/{en,de}.json` — a test fails when one is missing. The same id has one profile setting even when it appears in multiple seasons.

The **Creatures** settings row (collapsed behind a summary with the on-count; it opens the switch tiles in place) calls `seasonCreatureGroups(state.inWindow, state.today)`. It lists every registry season with a nonempty `look.creatures`, even outside that season's window, so users can switch animals off in advance. Each season gets a labelled group with `seasons.<id>.name`, its window from `formatSeasonWindow(season, locale)`, and a **Running now** marker when its window is open. The open season comes first; the other groups follow their next window start, calculated with `seasonDayNumber()`. `SeasonState.today` is the resolved calendar day in the effective timezone (or the simulated preview day); in the server-rendered snapshot it is `null`, so groups use registry order until hydration. Fixed windows have locale-formatted dates; movable windows have no year-independent date and show only the season name.

A season with animals needs `look.creatures`, their artwork, the shared creature labels, and `seasons.<id>.name` in both languages. `SEASON_MESSAGE_KEYS` requires the season name. The settings groups then appear without a season-specific UI change. The switches remain visible but are disabled at Subtle strength or while the seasonal look is off.

- The profile stores only overrides (`me.seasonCreatures`, absent key = default); `seasonCreatures(list, overrides)` turns them into the effective on/off map.
- `Scenery` and `ToastAccent` receive that map as `creatures` and leave a switched-off animal out entirely — no element, no timers.
- Every element that draws an animal carries `data-season-creature="<id>"`. The pre-paint resolver gets each season's defaults through `seasonBootstrapConfig()` and writes the hidden ones of the open season to `<html data-season-hide="bat spider">`; the generated stylesheet hides matching elements, so a switched-off animal never flashes before hydration.

## Scope: dashboard and popouts

Two layouts mount the look: `(main)/(app)/layout.tsx` (the dashboard) and `(popout)/layout.tsx` (ZAF-1673: `/popout/{chat,events,music,obs}`, in a browser and inside OBS — there is deliberately no `window.obsstudio` exclusion). Each renders `SeasonHead` (stylesheet + pre-paint script) and `SeasonProvider` (season scope + client resolver); every slot renders only its regular variant outside that scope, so overlays, widgets, extensions, the `(fullscreen)` editors and the public/marketing routes get no seasonal markup. `apps/web/__tests__/components/seasons.test.tsx` fails when any other `src/app` file mounts them.

The popout layout passes `popout` to both. That switches the resolver to:

- **`isolated`** — it neither reads nor writes the shared `lumio-season` mirror cookie. A popout may run a delegated session of another user in the streamer's own browser, and a popout in OBS has a browser of its own, so the only preference source is the represented user's profile: SSR-embedded (`popoutSession` for a delegated session, `me` for a logged-in popout — both queries select `SEASON_PROFILE_GQL_FIELDS`), then re-read through `/api/users/me/season` with the popout-aware fetch. No profile → the defaults. Passive profile sync never migrates legacy values or writes preferences; the two banner actions below are the only writes. A broadcast from a dashboard tab makes the popout re-read its own profile, and a popout banner write broadcasts only a request to re-read, never another user's values.
- **`urlOverrides`** — `?season=off|on`, `?seasonStrength=subtle|full`, `?seasonMotion=off|auto` override the profile for that page, in the pre-paint script and in the client resolver alike. Unknown values are ignored; nothing is stored.

What a popout shows: colours, layout-matched loading skeletons, the events and chat empty states, the toast accent, and `SeasonDecorations compact` — a 96 px band behind the header with the season's `Scenery` in `compact` mode (Halloween: the corner web scaled to 0.6 with its spider, two bats and a small fly-by bat — `flyByKeyframes(…, 24, 0.4)` keeps the path inside the band and it runs on every width — no moon; St. Nicholas: star garland, hanging boot and robin). `ChatShell` and `EventsShell` render it with `seasonScenery` (popout clients) and with `seasonBanner` (the full-height dashboard chat/events pages, which the app shell's page `SeasonDecorations` skips like every fullscreen page); the shell root then becomes `isolate`, so the `-z-[1]` band paints above the shell's opaque `bg-card` but below its content. The music and OBS popouts mount it on their own `relative isolate` roots.

**Banner.** `SeasonBanner` is one component with three variants. The dashboard shell renders the default (`page`) variant above the content on every `(main)/(app)` page except the fullscreen ones. The fullscreen chat and events pages show the `bar` variant instead, full width directly under their own topbar (`ChatShell` / `EventsShell` prop `seasonBanner`), above their AlertDeck; the overlay editor shows none. Those pages fill the shell's `min-h-0 flex-1` slot with `h-full` and never size themselves to the viewport (`h-screen`, `100dvh`), so every in-flow row shrinks the feed instead of clipping its bottom bar (chat input, events search); `apps/web/__tests__/fullscreen-page-height.test.ts` guards both rules. `variant="compact"` is the popout strip: `ChatShell` / `EventsShell` render it under their header when `seasonScenery` is set (it wins over `seasonBanner`), the music popout at the top of its root; the OBS control popout has none. `bar` and `compact` carry the same short copy and differ only in size (`STRIP_SIZE`): `bar` uses `text-sm` with `h-8` controls and `py-2`, `compact` uses `text-xs` with `h-6` controls and `py-1.5`, so the controls never touch the row edges, also when the text wraps in a narrow popout. Both strips have a primary-tinted background and a primary bottom border, so they read as a row of their own above the AlertDeck or the preview strip. `SeasonPreviewMarker` uses the same spacing as `compact`. Like every slot it is `data-season-level="full"`, so Subtle, `?season=off`, off-season and a dismissed instance hide it (and its height) through the generated stylesheet. Compact copy lives in a per-season `bannerBodyCompact` key (`SEASON_MESSAGE_KEYS`). **×** calls `dismissSeasonBanner(instance)`; **Switch off** is a `Button` that calls `switchOffSeasonLook(instance)` — look off + dismissal in one write — and toasts the result: on the dashboard with a Settings link and **Undo** (`restoreSeasonLook(dismissedBefore)`), in a popout (`useSeasonInPopout()`) without Undo.

**Emote button.** The chat input bar's emote button (`multichat.tsx`) renders its icon through `SeasonBarEmoteIcon({ barRef, busy, libraryOpen })` (`season-bar-strip.tsx`), which reads the same bar-idle rule as `SeasonBarStrip` and renders the `SeasonalEmoteIcon` slot (`seasonal-slots.tsx`). Its children are the regular `Smile` (`data-season-default="subtle"`); per season the slot renders the optional registry asset `EmoteIcon` (`SeasonEmoteIconProps`: `active`, `strength`, `motion`, `idle`, `busy`, `libraryOpen`) without a level attribute, so it shows at Subtle and Full, and a season without the asset keeps `Smile`. Halloween's asset is `HalloweenEmoteIcon` (`halloween-emote-icon.tsx`): `GhostGlyph` at 1.15em in `currentColor`, `aria-hidden`; the button carries the label (`chat.emoteButton`) and `aria-expanded`. At Full with `sceneryMayMove()` and the library closed it plays `EMOTE_GLANCE_KEYFRAMES` (the look-left/right frames of `BAR_PEEK_KEYFRAMES` without rise and sink, transform only, `PEEK_MOTION.glanceMs`). It owns no timer: it registers with the page's peek coordinator as a `kind: "bar"` strip with one anchor and `weight: PEEK_MOTION.glanceWeight`, so idle glances join the strip ghosts' rotation (anchor weights default to 1). Pointer-enter and focus call `coordinator.request(strip, anchor)`, which starts a glance at once and replaces the pending wait, or refuses while any ghost is moving. The open emote library is passed on its own (`libraryOpen={showEmoteLibrary}`), apart from `busy` (`inputBarBusy`, e.g. the popout chat settings, which keeps the ghost still — no idle or hover glance). While the library is open and `sceneryMayMove()` allows motion, the ghost sways continuously: `EMOTE_SWAY_KEYFRAMES` (rest → the glance's left look → its right look → rest, pendulum easing, transform only) loop with `iterations: Infinity` over `PEEK_MOTION.swayMs`. The sway holds the coordinator's motion slot through `coordinator.hold(strip)`: a running peek is cancelled, no wait runs and `request()` is refused until it is released, so it stays the page's one moving ghost. On close it animates from its current computed `transform` back to rest over `PEEK_MOTION.swaySettleMs` (ease-out) before it releases the slot, and the rotation resumes with a fresh random wait. If motion stops being allowed while the library is open (Subtle, Animations Off, reduced motion, hidden tab), the sway stops at once and the slot is released. `apps/web/__tests__/components/halloween-emote-icon.test.tsx` covers the state matrix and the coordination.

## Building dashboard features that work with the seasonal look

Every feature in the signed-in dashboard (`(main)/(app)`) and the dashboard popouts (`/popout/*`, including inside OBS) must work with the look off and at Full and Subtle strength. Check Animations Off, `prefers-reduced-motion`, and both light and dark themes. Overlays, widgets, extensions and their UIs, the overlay/widget editors, marketing pages, the login app, and the admin app stay outside the seasonal scope.

Chat announcements keep their five Twitch colours, and pin and Moderator/VIP
event treatments keep their meaning, with the seasonal look off, Full or
Subtle. Their live arrival motion follows the Chat motion preference. A
reloaded row is already at rest; Reduced removes the streak, needle and role
stamp, while Off shows the final state immediately. The pin countdown remains
visible as time information at every motion level.

The separate [Motion guide](/developer-guide/motion) covers the global **Animations in Lumio** preference, the stricter Chat/Events/Music override, the CSS and React helpers, and the animation inventory. Global Reduced or Off makes seasonal decoration still even when its own **Animations** row is Automatic.

| Area | Use this pattern |
|---|---|
| Colours | Use theme tokens such as `primary`, `card`, `border`, `muted` and `foreground` so the season's light/dark overrides apply. Keep chart colours, platform colours, `--highlight-user`, the achievement colours (`--achievement` gold for records and follower marks, `--achievement-raid` blue for the biggest raid) and the `--success` status green (`stroke-success` / `text-success` for "ready / ok", paired with `warning` for "needs action") unchanged; the registry does not permit seasons to override them. Status colours use `success` / `warning`, never `primary`: a season recolours `primary` (Halloween orange sits next to its ember `warning`), so a ready/problem pair built on `primary` loses its meaning in season. Achievements use their own tokens, never a chart series colour, and `text-achievement*` on its 15 % tint stays ≥ 4.5:1 over `card` and `muted` in every season and theme. |
| Loading and empty states | Match loading content with `Skeleton` blocks inside `SkeletonRegion`, including the first read of a feed; skeletons pulse at every motion level. Use `SeasonalSpinner` only for a standalone wait without a content shape; inline button/input spinners stay ordinary. Halloween Full shows three ghosts and St. Nicholas Full shows three gold stars; with animations off or reduced motion their opacity pulses in sequence. Wrap a feed's actual empty line in `SeasonalEmptyState kind="events" \| "chat" \| "history" \| "history-filtered" \| "activity" \| "schedule"` (Events feed, Multichat feed, History list) with the plain line as its child: at Full it shows the season's `EmptyIllustration` (`season-float`, still with animations off or reduced motion) and the corresponding `seasons.<id>.empty*` title/body copy. The dashboard home uses `activity` and `schedule`; a new empty surface adds a `kind` (and its keys to `SEASON_MESSAGE_KEYS`) rather than copying the markup. |
| Shared accents | Use `SeasonToastAccent` for the success-toast accent, `SeasonalLogo` or `SeasonalBrand` for Lumio branding, and the shared scenery, banner and strip slots where appropriate. Extend a slot or the registry when a new season needs a variant; feature rendering does not branch on season ids. |
| Decoration | Keep artwork behind content and controls, with `pointer-events: none` and `aria-hidden`. Reserve layout space for banners and strips: the footer strip sits above the footer, and `SeasonBarStrip` occupies its own row at the top of the Events search bar, the Chat input bar and the music popout's search footer. `SeasonBarStrip` also renders the bar's separator line directly under the band, so the seasonal strip stands on the line at Full and the line is the bar's top edge when the band is hidden — a host bar must not add its own `border-t` and mounts the strip without side padding, so the decoration spans the full container width like the line. A peeking figure stays clipped inside the 16 px band so it cannot cover the last item or a control. Bars are idle when every field is empty, no picker or panel is open (`busy`) and no `input` event happened for 4 s (`src/lib/seasons/bar-idle.ts`); focus does not count. The page's peek coordinator (`src/lib/seasons/peek-coordinator.ts`) waits 15–30 s between peeks while a bar strip is eligible and 45–75 s when only the footer is, and shows one peeking figure per page. Use only `transform`/`opacity` for movement; gate decorative motion on Full, Animations Automatic, no reduced-motion request, and page visibility. The Halloween logo's blink schedule is capped at 2.5 per second. |
| Popouts | A delegated popout can represent another user and run inside OBS. It reads that user's profile independently of the dashboard mirror cookie. Its only profile writes are dismissing a banner and switching the look off while dismissing that banner; do not assume `updateMe`, general profile editing, or an Undo action. |

The report body under `apps/web/src/components/history/report/` and the public share components under `apps/web/src/components/history/share/` are season-banned. Dashboard wrappers own seasonal slots; shared report rendering contains no seasonal imports, so a public share cannot inherit dashboard decorations.

`apps/web/__tests__/seasons.test.ts` enforces that `SeasonProvider` and `SeasonHead` mount only in the `(main)/(app)` and `(popout)` layouts, and that overlay, fullscreen editor, marketing, legal and public route trees do not reference seasonal code. Keep that scope check current when moving a layout. For visual review, the Dev & Admin season preview is available to staff with `admin:access` and `devtools:read`; a popout URL accepts `?season=off|on&seasonStrength=subtle|full&seasonMotion=off|auto` without saving the override. Dashboard UI PRs carry screenshots with the season off and the active look at Full in both dark and light themes; also check Subtle and reduced motion directly. Also load every changed page, wizard step and dialog at **390 px** width: nothing may overflow horizontally (`document.documentElement.scrollWidth <= innerWidth`, no visible element ends right of the viewport). Desktop-only mock-ups do not exempt a page. Dashboard UI PRs include one 390 px screenshot per changed page and one at **1280 px with the sidebar expanded**; cards and grids must stay readable without squeezing or breaking words mid-word.

## Preferences storage

The preferences (on/off, strength, animations, creature toggles, dismissed banners) live on the user profile: `me.season*` / `GET /v1/users/me`, written via `updateMe` / `PATCH /v1/users/me`, and readable on `popoutSession` / `GET /v1/auth/popout/session` for popouts. A popout session has exactly two one-way writes: dismiss the banner (`popoutDismissSeasonBanner` / `POST /v1/auth/popout/season-banner/dismiss`) and switch the look off (`popoutSwitchOffSeasonLook` / `POST /v1/auth/popout/season-look/off`, which also dismisses the current instance). Both take one `<seasonId>:<year>` instance whose season id must be in `user_preferences::SEASON_IDS` in `apps/api` (`halloween`, `nicholas`, `christmas`, `new-year`, `easter`). The API list and the registry calendar contain these ids. A further season adds its id to both places so popout banner writes pass validation. A popout can never switch the look on or change anything else. The creature map and the dismissed-banner list are replaced on write, so clients always send the full value. There is no WebSocket push for them.

The web app reaches them through `/api/users/me/season` (GET + PATCH). A popout-window fetch (`usePopoutFetch`, `x-lumio-popout`) reads `popoutSession`; everything else reads `me`. The PATCH refuses popout-window fetches; a delegated popout's two writes go through `POST /api/users/me/season/popout` with `{ "action": "dismiss" | "off", "instance": "<seasonId>:<year>" }`, which in turn refuses every request without the popout header. A logged-in (cookie) popout has a first-party session and writes the same two actions through the normal PATCH. The mapping between the snake_case wire fields and the resolver's `SeasonPrefs` is in `src/lib/seasons/profile.ts`.

The look must be right before React runs, so the resolver in `src/lib/seasons/bootstrap.ts` also runs as an inline script during HTML parse. It reads the `lumio-season` mirror cookie (non-httpOnly, 1 year, the same approach as `lumio-tz`). On a full dashboard page load the `(main)/(app)` layout embeds the freshly SSR-loaded profile into that script (`SeasonHead profile=…`); the script prefers it over the cookie and rewrites the cookie, so a first visit on a new device never flashes the defaults. The script is rendered through `PrepaintScript`, so it exists only in the SSR HTML: a soft navigation into the dashboard (for example the marketing header's **Dashboard** link, which shares the `(main)` root layout) gets no `<script>` element — React would never run it and logs an error for it — and `SeasonProvider` resolves the attributes on its first read instead. After mount, `SeasonProvider` re-reads the profile, mirrors it into the cookie, and re-reads again when the tab returns to the foreground (at most every five minutes). Writes are optimistic: the cookie and the `<html>` attributes change first, the PATCH follows, and a failed write reverts to the server value (`setSeason*`, `switchOffSeasonLook` and `restoreSeasonLook` resolve `false` then, so the banner can show an error toast). The banner dismissal is the exception: it is never reverted — a failed one stays hidden for the page session and is retried silently on the next profile sync. Other tabs of the same browser are told through a `BroadcastChannel` (`lumio:season`): `"change"` means "re-apply the mirror cookie"; `"profile"`, posted by a popout after one of its writes, means "re-read your own profile". A popout never posts a value, so a delegated popout of another user cannot leak its preferences into the browser's dashboard tabs.

The earlier per-browser `localStorage` keys (`lumio:season:*`) are only read by a one-time migration. If the profile still holds every default, the browser's explicit values are written to the profile once, and the keys are then deleted. A popout never runs this migration.

## Dev & Admin season preview

The Dev & Admin menu (`src/components/dev-menu/dev-menu.tsx`, ZAF-1669) lets platform admins preview a season in their own browser. The gate is `canUseDevMenu(me.adminPermissions)` in `src/lib/devtools.ts` — `admin:access` **and** `devtools:read`, deliberately not the account-scoped `<Gate>`. The shell renders the footer button, the dialog and the badge, and registers the Ctrl/⌘ + Alt + Shift + D listener, only when it holds. New tools are entries in `DEV_TOOLS` in that file.

The preview is one `localStorage` value under `SEASON_PREVIEW_KEY` (`lumio:devtools:season-preview`, outside the legacy `lumio:season:*` keys the migration deletes): `{ "season": "<id>" | "none" }` or `{ "date": "YYYY-MM-DD" }` — one model at a time. The resolver honours it only when its config carries `preview: true`, which the `(main)/(app)` layout passes to both `SeasonHead` (so the preview paints without a flash) and `SeasonProvider` for allowed users only; for anyone else a stored value is ignored. A forced season bypasses the calendar, a simulated date replaces "today", and either one bypasses the user's **Seasonal look: Off**. A season without a `look` is not in the resolver's config, so forcing it (or a date inside it) renders nothing. `seasonOnDate()` runs the same resolver over the full calendar to name the season for a date in the menu and the badge. Nothing is sent to the server and there is no audit event.

The preview belongs to the browser, so it reaches the popouts opened in the same browser too (ZAF-1717). The `(popout)` layout passes `previewAllowed` to its `SeasonHead` and `SeasonProvider` exactly like the dashboard, computed by `popoutSeasonPreviewAllowed()` (`src/lib/seasons/popout-preview.ts`) from the **browser's own login**, never from the user a popout token represents: a logged-in popout (the normal case) reads `adminPermissions` on its own `me`; a delegated popout session makes one extra `me { adminPermissions }` read with the login cookie only (`serverGqlSSR`), and without a login cookie — OBS, a guest browser — there is no read and no preview. OBS also has its own browser storage, so a preview started on the dashboard never shows up there. While a preview is active a popout renders `SeasonPreviewMarker` (same `devMenu.seasonPreview` strings as the badge) as a compact, in-flow strip under the header next to the compact season banner — never over the feed or the input/search bar; its **End** ends the preview for the whole browser. Starting, changing or ending the preview anywhere updates every other open tab and popout of the browser through the `storage` event. The popout URL overrides apply on top: `?season=off` wins even over a preview, `?seasonStrength=` and `?seasonMotion=` apply as usual.

---

## Developer Guide / Motion

Source: https://docs.lumio.vision/developer-guide/motion

# Motion

The **Animations in Lumio** preference controls Lumio's dashboard and popout animations. The profile field `motion_preference` is `system` (default), `reduced`, or `off`. `system` follows the operating system's `prefers-reduced-motion`; the effective level is `full`, `reduced`, or `off`. Reduced removes movement, scaling and loops but permits short fades up to 150 ms. Off makes transitions and animations instant. Loading remains visibly in progress. Animated chat emotes are viewer content. Stream History report GIF tiles stay still under Reduced and Off until hover or focus.

## Scope and resolution

`apps/web/src/lib/motion/bootstrap.ts` runs before paint in the same `SeasonHead` script as the seasonal resolver. It combines the SSR profile value, the `lumio-motion` mirror cookie (dashboard only), the OS preference, and an optional stricter `?motion=reduced|off` on popout URLs. It writes `data-motion="full|reduced|off"` to `<html>`. Popouts use their represented user's profile through `popoutSession`, never the dashboard cookie; they can read but cannot write the global preference. Unknown URL values are ignored. There is no always-on option that overrides the OS.

Chat, Events and Music carry a separate `PopoutSettingsState.motion` of `inherit`, `reduced`, or `off`, stored per view, browser, user and account. `MotionSurface` places a stricter `data-motion` value on the view root and gives React the matching `MotionScope` and `LumioMotionConfig`. The effective value is always the strictest of the OS, global preference and view override. The settings row disables a looser choice, such as Reduced when global motion is Off. The seasonal **Animations: Automatic / Off** row remains separate: `data-season-motion` governs decoration only, and global Reduced or Off keeps that decoration still.

The Chat and Events default-preset loading frames read the saved surface override through the [pre-paint layout hint](/developer-guide/loading-states#full-height-chat-events-and-music-surfaces) and carry the same `data-motion` as their loaded shells. The Music popout starts with its saved override as well. Their skeleton blocks retain an opacity pulse at Reduced and Off.

## Animation helpers

- `useMotionPreference()` in `apps/web/src/hooks/use-motion-preference.ts` returns the effective `full | reduced | off` level for JavaScript animations. `useMotionAllowed()` is true only at Full; `useDocumentMotionLevel()` reads the global level for settings controls. The server and hydration snapshot is Reduced, so animation waits until the browser resolves the actual level.
- `LumioMotionConfig` uses `motion/react`: Reduced sets `reducedMotion="always"`, and Off also sets `skipAnimations`. Mounts exist in the dashboard shell and popout layout; each surface has its scoped config.
- The `motion-ok:` variant in `shared/ui/src/globals.css` gates movement and scaling on Full. Put a static rest pose in the unprefixed rule. The CSS baseline keeps colour and opacity transitions under Reduced, removes motion and smooth scrolling under Off, and keeps loading perceptible. Its exact `.animate-pulse` exemption preserves the opacity pulse on `Skeleton` blocks at Reduced and Off.
- A translate inside a scroll container counts toward its scrollable overflow. `overflow-x-auto` alone also makes the y axis `auto`, so a row that rises into place can flash a vertical scrollbar until it lands. A container that scrolls on one axis only sets the other axis to `hidden` (`overflow-x-auto overflow-y-hidden`), and hover nudges stay inside the cell padding.
- `--motion-duration-fast`, `--motion-duration-base` and `--motion-duration-slow` are 150/200/300 ms at Full, 100/150/150 ms at Reduced, and 0 at Off. Use them for permitted fades and transitions; duration tokens alone do not remove movement. `shared/ui/src/motion.ts` exposes `motionLevelAt(el)` for shared components outside the React context.

Every new dashboard or popout animation must use the hook or the CSS variant and duration tokens. Avoid direct `prefers-reduced-motion` checks in feature code.

## Widget and overlay boundary

Widgets and overlays are stream content and never follow this preference, including their previews, editors and designers inside the dashboard and their `/overlay/…` and `/widget/…` embeds. Inline previews use `MotionExempt` with `data-motion="exempt"`: the CSS gate stops at that boundary and the React hook reports Full beneath it. Iframes have their own document. The `(overlay)` routes have no motion bootstrap or `?motion=` handling. `apps/web/__tests__/motion-import-ban.test.ts` rejects motion-hook and CSS-helper imports in widget, overlay, editor and designer code, and forbids motion bootstrap code in `(overlay)` routes.

## Animation inventory

The following inventory is the behaviour implemented for dashboard and popout motion. Mechanisms: **B** CSS baseline, **V** `motion-ok:`, **T** duration tokens, **MC** `LumioMotionConfig`, **H** React hook, **S** seasonal resolver, **D** `motionLevelAt(el)`. Loading indicators and status pulses retain a visible signal at Off. Directly dragged elements still follow the pointer.

### Global chrome

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| G1 | Mobile sidebar panel enter/exit | `(app)/shell.tsx` | slide 12 px + fade, 220 ms | fade only | instant | MC |
| G2 | Mobile sidebar item stagger | `shell.tsx` | slide 16 px + fade, staggered | fade only | instant | MC |
| G3 | Hamburger ↔ X icon swap | `shell.tsx` | rotate ±90° + fade | fade only | instant | MC |
| G4 | Desktop sidebar collapse | `shell.tsx` (`transition-[width]`) | width glides 200 ms | jumps | jumps | B |
| G5 | Nav section expand/collapse | `shell.tsx` (`transition-all`) | height glides | jumps, opacity fades | instant | B |
| G6 | Nav section chevron | `shell.tsx` | rotates | jumps | jumps | B |
| G7 | Account switcher chevron | `components/account-switcher.tsx` | rotates | jumps | jumps | B |
| G8 | Tooltips | `shared/ui/src/tooltip-provider.tsx` + keyframes in `app/globals.css` | 2 px rise + fade, 150 ms | fade 150 ms (2 px rise kept — below the movement threshold) | instant | B |
| G9 | Toasts | `contexts/toast-context.tsx` (`.lm-toast-enter` / `.lm-toast-exit`) | rise 8 px + fade in, 200 ms; automatic and ✕ click dismissal fade out 150 ms | fade ≤150 ms on either dismissal | instant on either dismissal | B |
| G10 | AlertDeck slide switch + height | `shared/ui/src/alert-deck.tsx` | slide + blur + fade, height glides | 120 ms fade | instant | D + B |
| G11 | AlertDeck swipe drag | `alert-deck.tsx` | follows the finger (direct manipulation) | follows the finger | follows the finger |
| G12 | AlertDeck button press | `alert-deck.tsx` (`active:scale-[0.97]`) | scales | colour only | instant | B |
| G13 | `.btn-primary` hover lift | `shared/ui/src/globals.css` (10 uses) | lifts 1 px | colour only | instant | B |
| G14 | Select chevron | `shared/ui/src/select.tsx` | rotates | jumps | jumps | B |
| G15 | Colour picker swatch hover | `shared/ui/src/color-picker.tsx` | scales 110 % | jumps | jumps | B |
| G16 | Wizard progress bar | `shared/ui/src/wizard-steps.tsx` | width glides | jumps (information kept) | jumps | B |
| G17 | Switch thumb | `shared/ui/src/switch.tsx` | colour fades, thumb jumps | same | instant | B |
| G18 | Colour/opacity-only transitions (dialog close, menus, tabs, theme toggle, badges, inputs, nav items, bell) | various | fade | fade | instant | B |
| G19 | Aurora background (ribbons, floor, accent, particles, grain) | `shared/ui/src/aurora-background.tsx`, `(app)/layout.tsx`; also behind the ID app's sign-in card (`apps/id` `login/card.tsx`), which has no Lumio motion setting: there `still` (standing ribbons, no particles) follows the OS reduced-motion choice and is always on in the compact popout / OBS dock card and app sign-ins | infinite drift | still | still | B |
| G20 | Dashboard error page | `(app)/error.tsx` | breathe/pulse-ring/float loops, fade-up, retry spin | one pass, no loop; retry spin kept | instant; retry spinner pulses | B |

### Settings

The route tabs of Settings, Security, Channel settings, Connections, Billing and developer teams use the shared `RouteTabs` component: the active marker glides for 220 ms under `motion-ok`, and jumps under Reduced or Off (inventory G21). When the row is wider than its space, the chevron buttons a mouse gets scroll it smoothly under System and jump under Reduced or Off; the component reads the level with `motionLevelAt()` (G21b). Mouse-wheel and drag scrolling follow the pointer directly and have no animation of their own. Tab content fades for 120 ms without moving under System and Reduced, and changes instantly under Off (G22). Centered dialogs fade and scale under System while retaining their blurred backdrop in every mode (G23). Multi-step 2FA and email dialogs slide and resize under System, fade under Reduced, and jump under Off (G24). Code boxes and error shakes stop moving under Reduced (G25). The two-second hold progress (deleting the profile, dissolving a channel, and cancelling either) remains visible under Reduced; under Off the user types the name instead to delete or dissolve, and cancelling is a plain button (G26). Busy buttons keep their label and a visible, still ring when motion is reduced or off (L4).

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| S1 | Settings page controls | `dashboard/settings/*`, `Switch` | colour only | colour only | instant | B |
| S2 | Popout-settings toggles | `components/popout-settings.tsx` | colour fades, thumb jumps | same | instant | B |
| S3 | Popout-settings group chevron | `popout-settings.tsx` | rotates | jumps | jumps | B |
| S4 | Popout-settings group collapse | `popout-settings.tsx` | height glides | jumps, opacity fades | instant | B |
| S5 | Popout-settings trigger | `popout-settings.tsx` | colour | colour | instant | B |

### Chat (dashboard page and popout share `ChatShell`)

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| C1 | "Jump to newest" | `dashboard/chat/multichat.tsx` | smooth scroll | instant | instant | H |
| C2 | Auto-pin to bottom / entry restore | `multichat.tsx` | instant (by design) | instant | instant |
| C3 | Keyword tab strip arrows | `components/chat-shell.tsx` | smooth scroll | instant | instant | H |
| C4 | Keyword tab drag-reorder | `chat-shell.tsx` (dnd-kit) | neighbours glide aside | neighbours jump; dragged tab follows the pointer | same as Reduced | B |
| C5 | YouTube broadcast dropdown chevron | `chat-shell.tsx` | rotates | jumps | jumps | B |
| C6 | Emote library section scroll | `dashboard/chat/emote-library.tsx` | smooth scroll | instant | instant | H |
| C7 | Spotlight card arrival | `chat-spotlight-card.tsx`, `app/globals.css` | rise + glow + pill pop + sparks | fade ≤150 ms | instant | V + T |
| C7a | Announcement accent | `chat-spotlight-card.tsx`, `app/globals.css` | one light streak and megaphone wiggle on live arrival | none | none | V |
| C8 | Watch-streak count-up | `chat-spotlight-card.tsx` | counts up 900 ms | final number | final number | V |
| C9 | Watch-streak flame | `watch-streak-card.tsx`, `app/globals.css` | lives | still (rest pose) | still | V + H |
| C10 | Spotlight action bar reveal | `chat-spotlight-card.tsx` | opacity fade | fade | instant | B |
| C10a | Pin card arrival | `chat-pin-card.tsx`, `app/globals.css` | slides and fades; needle sticks once | fade ≤150 ms, no needle | instant | V + T |
| C10b | Pin card collapse / expand | `chat-pin-card.tsx` | height glides | instant | instant | B |
| C10c | Pin card exit | `chat-pin-card.tsx`, `app/globals.css` | fades out | fade ≤150 ms | instant | B |
| C10d | Pin countdown | `chat-pin-card.tsx` | advances as time information | advances | advances | — |
| C10e | Mod / VIP role event arrival | `chat-role-event-row.tsx`, `app/globals.css` | rises and fades; grant stamps once, revoke draws a strike | fade ≤150 ms | instant | V + T |
| C11 | Alert progress bars (hype train, ad break, poll, prediction, raid) | `dashboard/chat/chat-alerts.tsx` | width glides | jumps (information kept) | jumps | B |
| C12 | Raid icon pulse | `chat-alerts.tsx` (`animate-pulse`) | pulses | pulses (status signal) | pulses |
| C13 | Reconnecting dot | `multichat.tsx` (`animate-pulse`) | pulses | pulses (status signal) | pulses |
| C14 | Copy-confirm icon | `chat-message-row.tsx`, `chat-event-row.tsx`, `watch-streak-card.tsx` | icon swap | icon swap | icon swap |
| C15 | Expand chevrons in messages | `expandable-text.tsx`, `emote-text.tsx` | rotates | jumps | jumps | B |
| C16 | Platform chips / mod buttons | `multichat.tsx` | colour | colour | instant | B |
| C17 | Scroll-to-edge bar | `components/scroll-to-edge-bar.tsx` | rises 8 px + fades | fades | instant | B |
| C18 | Graveyard strip + input ghost | `halloween-graveyard.tsx`, `season-bar-strip.tsx` | normal decoration | strip still, no ghost | strip still, no ghost | S + H |
| C19 | Animated emotes / GIFs | `message-content.tsx`, `emote-text.tsx` | play | play (viewer content) | play |
| C20 | Viewer-list panel show / hide (ZAF-1701, ZAF-1766) | `components/chatter-list/chatter-list-panel.tsx` | docked: the panel's slot width runs 0 ↔ W (200 ms in, 150 ms out, ease-out, retargets when toggled mid-flight), so the feed narrows / widens with it while the panel slides in from its edge; overlay: slides 16 px + fades. Only after a user action; the panel stays mounted while hidden (`inert`) | instant | instant | H |
| C21 | Viewer-list rows join / leave | `chatter-list-panel.tsx` | fade + 4 px rise 150 ms / fade 120 ms (≤ 20 changes) | instant | instant | H |
| C22 | Viewer-list width change (auto growth, keyboard, settings) | `chatter-list-panel.tsx` | width glides 150 ms; a drag follows the pointer 1:1 | jumps | jumps | V |
| C23 | Live 7TV emote-change line | `chat-event-row.tsx`, `seventv-event-detail.tsx`, `app/globals.css` | brief accent tint; an added image pops in, a removed image dims and strikes through, a renamed name fades in | fades only, at most 150 ms | instant | V + T |
| C26 | Emote library bottom sheet up to 480 px (ZAF-2600) | `emote-library.tsx` via `@lumio/ui` `BottomSheet` | slides up from the input bar 300 ms, backdrop fades; close slides down 200 ms; grip drag follows the pointer | fades only | instant | D |

The 7TV line only animates when the live WebSocket arrival claims its motion
within one second. History, reconnect gap-fill, tab switches and remounts show
the rest state. The Chat override can reduce or turn off this motion.

### Events (dashboard page and popout share `EventsShell`)

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| E1 | New-event row enter | `components/events-shell.tsx`, `.animate-fade-in` in `app/globals.css` | slides down + grows + fades, 400 ms | fade ≤150 ms | instant | V + T |
| E2 | Scroll to newest | `events-shell.tsx` | smooth scroll | instant | instant | H |
| E3 | Reconnecting dot | `events-shell.tsx` (`animate-pulse`) | pulses | pulses (status) | pulses |
| E4 | Event progress bars | `components/event-row.tsx` | width glides | jumps (information kept) | jumps | B |
| E5 | Copy-confirm scale | `event-row.tsx` | scales | jumps | instant | B |
| E6 | Highlighted events | `event-row.tsx` | static highlight | static | static |

### Music (dashboard page and popout)

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| M1 | Track progress bar | `dashboard/music/music-player.tsx`, `popout/music/music-popout-client.tsx`, `hooks/use-spotify-player.ts` (`nextDisplayProgress`) | runs, rAF-smoothed | runs (information, not decoration) | runs, steps once per second | H |
| M2 | Section chevrons | `music-player.tsx`, `music-popout-client.tsx` | rotates | jumps | jumps | B |
| M3 | Popout content loading | `music-popout-client.tsx` (`MusicPopoutSkeleton`) | skeletons pulse | skeletons pulse | skeletons pulse | B |
| M4 | Connection-lost dot | `music-popout-client.tsx` | pulses | pulses (status) | pulses |
| M5 | Action buttons hover lift | `.btn-primary` (G13) | lifts | colour only | instant | B |

There is no marquee, visualizer or cover cross-fade in the music surfaces today. When one is built it
follows the same rules: Reduced keeps the title standing with "…" and fades the cover in ≤150 ms; Off is instant.

### Other dashboard pages

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| O1 | Onboarding plan cards hover lift | `dashboard/onboarding.tsx` | lifts 4 px | colour only | instant | B |
| O2 | Dashboard home block entrance (`.lm-home-enter`) | `components/dashboard-home/`, `app/globals.css` | 8 px rise + fade, 220 ms, 40 ms stagger | fade ≤150 ms | instant | V + T |
| O3 | Dashboard home live switch and sampled numbers | `home-strip.tsx`, `home-main.tsx`, `AnimatedNumber` | 280 ms crossfade; numbers count to their values in 900 ms | fade; final number | instant | V + H + T |
| O3a | Dashboard home weekly-review bars (`.lm-week-bar`) and "Up next" countdown | `home-week.tsx`, `app/globals.css` | bars grow from the baseline in 700 ms, 30 ms stagger; countdown digits change in place (no digit animation) | fade ≤150 ms | instant | V + T |
| O4 | Dashboard activity and test rows | `home-activity.tsx`, `test-event-catalog.tsx` | enter from above in 240 ms | fade ≤150 ms | instant | V + T |
| O4a | Test Event side sheet and expanded form | `DialogContent variant="sheet"`, `.lm-te-expand` | right slide (phone: bottom) 220 ms; form rise 180 ms | fades ≤150 ms | instant | V + T |
| O5 | Subscription plan card hover lift | `account/subscription/plan-selector.tsx` | lifts 4 px | colour only | instant | B |
| O6 | History report charts and crosshair | `components/history/report/charts.tsx` | no entry tween; tooltip appears at the crosshair with no position glide, crosshair, dots and box only in the hovered chart (no sync) | no entry tween; no tooltip glide | no entry tween; no tooltip glide | H |
| O6a | History list row entrance, live dot and progress | `dashboard/history/`, `.lm-row-enter`, `.lm-live-dot`, `.lm-progress` | short row stagger; status and loading pulse | no row movement; status/loading pulse | instant rows; status/loading pulse | V + T |
| O6b | History report GIF tiles | `components/history/report/top-lists.tsx` | animated GIF | still placeholder until hover/focus | still placeholder until hover/focus | H |
| O7 | Idea card chevron nudge | `hub/ideas/idea-card.tsx` | nudges 2 px | jumps | jumps | B |
| O8 | Toggle thumbs (bot modules, store installed, OBS config) | `module-list.tsx`, `store/installed/page.tsx`, `connections/obs-config.tsx` | thumb glides | thumb jumps | instant | B |
| O9 | Progress bars (developer wizard, extension limits/analytics) | `application-wizard.tsx`, `extensions/limits/page.tsx`, `extensions/[slug]/analytics/page.tsx` | width glides | jumps (information kept) | jumps | B |
| O10 | OBS scene buttons / `.btn-primary` | `obs/obs-dashboard.tsx` | colour + lift | colour only | instant | B |
| O11 | Automations canvas | `shared/automation/src/canvas/AutomationCanvas.tsx` | no animation configured | — | — |

### Loading indicators

| # | Animation | Where | Full | Reduced | Off | Mech. |
|---|---|---|---|---|---|---|
| L1 | Action and hand-off spinners (`animate-spin`, about 50 sites) | buttons, refresh icons, OAuth and redirect waits in dashboard, popouts and `shared/ui` | spins | spins | opacity pulse (still loading) | B |
| L2 | Content skeletons (`Skeleton`, `SkeletonText`, `SkeletonRegion` from `@lumio/ui`; blocks carry `animate-pulse`) | dashboard, popouts, feeds, cards, user details, history list/report/share loading layouts | pulse | pulse | pulse | B (`animate-pulse` exemption) |
| L3 | `SeasonalSpinner`, for a standalone wait without a content shape | `components/seasons/seasonal-slots.tsx` | Halloween ghosts bob or St. Nicholas stars hop (season) / regular spinner | seasonal icons pulse (also under a surface's Reduced override) | seasonal icons pulse; regular spinner pulses (also under a surface's Off override) | S + B |

### Seasonal decoration

All rows: **Full** = normal decoration; **Reduced** and **Off** = standing still, because a global Reduced/Off sets
`data-season-motion="off"` (S) and every JS-driven piece asks `useMotionAllowed()` (H, through the shared motion hook).

| # | Animation | Where | Reduced / Off | Mech. |
|---|---|---|---|---|
| SD1 | Seasonal loader icons | `lib/seasons/styles.ts`, `seasonal-slots.tsx` | opacity pulse so loading remains visible | S |
| SD2 | Bat drift | `styles.ts`, `halloween-scenery.tsx` | still | S |
| SD3 | Empty-state illustration float | `styles.ts`, `seasonal-slots.tsx` | still | S |
| SD4 | Toast bats | `styles.ts`, `halloween-assets.tsx` | still | S |
| SD5 | Brand pumpkin blink + tip | `halloween-brand.tsx`, `logo-motion.ts` | no bursts | H |
| SD6 | Pumpkin hover wobble | `halloween-brand.tsx` | brighter only, no wobble | H |
| SD7 | Witch flight from the i-dot | `halloween-brand.tsx` | no flight | H |
| SD8 | Halo hover | `lib/seasons/halloween-brand-css.ts` | colour only | S |
| SD9 | Bat wing-flap bursts | `halloween-scenery.tsx`, `scenery-motion.ts` | none | H |
| SD10 | Bat fly-by | `halloween-scenery.tsx` | none | H |
| SD11 | Corner spider crawl/drop | `halloween-scenery.tsx`, `spider-motion.ts` | none | H |
| SD12 | Graveyard ghost peek | `halloween-graveyard.tsx`, `peek-coordinator.ts` | none | H |
| SD13 | Bar ghost peek/glide | `halloween-graveyard.tsx`, `season-bar-strip.tsx` | none | H |
| SD14 | Emote-button ghost glance | `halloween-emote-icon.tsx` | none | H |
| SD15 | St. Nicholas star-loader hop | `nicholas-css.ts`, `seasonal-slots.tsx` | opacity pulse remains | S |
| SD16 | Snowfall, star twinkle and compact garland | `nicholas-css.ts`, `nicholas-scenery.tsx` | still | S |
| SD17 | Boot, shooting star and robin flight | `nicholas-scenery.tsx`, `nicholas-scenery-motion.ts` | no flight; settle to rest | H |
| SD18 | Snowy-roof Nicholas peek | `nicholas-edge-strip.tsx`, `peek-coordinator.ts` | none | H |
| SD19 | Boot-L brand and Nicholas emote icon | `nicholas-brand.tsx`, `nicholas-emote-icon.tsx` | still, with permitted colour/opacity response | H |
| SD20 | Snowy-roof window lights (opacity only) | `nicholas-edge-strip.tsx`, `window-lights.ts` | all windows lit; scheduler stopped | H |

---

## Developer Guide / Loading states

Source: https://docs.lumio.vision/developer-guide/loading-states

# Loading states

## Content placeholders

When a page, panel, list, card or dialog body is waiting for content, render a placeholder that matches the final layout. Use `Skeleton` from `@lumio/ui` for blocks, circles and lines, and `SkeletonText` for a stack of text lines. Keep the same grid, row count, spacing and approximate dimensions as the loaded content so the page does not jump when the request finishes. A pending content read must not appear as an empty state, a blank region, a spinner or visible “Loading…” text.

Wrap a content placeholder in `SkeletonRegion`. It sets `role="status"` and `aria-busy="true"` and announces the translated `label` through screen-reader-only text. `Skeleton` blocks are `aria-hidden`, so assistive technology encounters one loading announcement rather than a list of empty shapes. Use the surface's existing loading translation; the dashboard commonly uses `t("common.loading")`.

```tsx
import { Skeleton, SkeletonRegion, SkeletonText } from "@lumio/ui";

<SkeletonRegion label={t("common.loading")} className="grid gap-4 sm:grid-cols-2">
  {Array.from({ length: 4 }, (_, index) => (
    <div key={index} className="rounded-lg border p-4">
      <Skeleton className="mb-4 h-32 w-full" />
      <SkeletonText lines={2} lineClassName="h-4" />
    </div>
  ))}
</SkeletonRegion>
```

For a single control placeholder, such as the theme toggle before mount, use a control-sized `Skeleton`; a content region is not needed. Feed placeholders should resemble the rows and respect the view's active display options. For pagination or load more, keep already loaded content visible and place the skeletons where incoming rows will appear.

### Full-height Chat, Events and Music surfaces

When `DefaultPresetGate` waits for a view's stored default preset, its fallback occupies the **whole surface frame**, not just the feed. `ChatSurfaceSkeleton` and `EventsSurfaceSkeleton` in `apps/web/src/components/surface-skeleton.tsx` keep the loaded shell's geometry on the dashboard and in popouts. The caller's header actions, seasonal banner and compact scenery are real elements because they do not depend on the preset. Tabs, settings and viewer-list controls, the Chat input or Events search bar, and feed rows use placeholders in their final positions. Chat also shows the viewer-list panel and its loading rows immediately when the saved layout allows it; quick-hide and missing `chat:read` leave the panel out. A saved hidden header or footer has no placeholder row.

The frame needs its saved layout **before the first paint**. `SurfaceSkeletonRoot` puts `surfaceLayoutScript()` (`apps/web/src/lib/surface-layout.ts`) as its first child, following the pre-paint `SeasonHead` pattern. The self-contained, read-only script reads the scoped settings blob and Chat viewer-list quick-hide state, then writes `data-sk-*` attributes and `--sk-*` CSS variables on the frame. These determine header/footer visibility, font size, viewer-list side, width and docked or overlay mode, and the surface motion override. `useSurfaceLayout()` applies the same calculation through `useSyncExternalStore` and a layout measurement during client navigation. Keep the script and hook on the same layout calculation so hydration and the first client frame match the loaded shell. The `<script>` element exists only in the SSR HTML: `PrepaintScript` (`apps/web/src/components/prepaint-script.tsx`) renders it for the server render and the hydration render and drops it for every client render, because a script React creates in the browser never runs and React 19 reports it as a console error. Render every inline pre-paint script through it — `SeasonHead` does too, since a server component's markup also reaches the browser in the RSC payload of a soft navigation — and make sure the client path applies the same effect on its own.

Music uses one frame for every Spotify state. Its page keeps the heading and popout action in place; the connect bar appears only when the worker is idle or manually active. While the player starts, a player-sized skeleton occupies its slot. An unreachable-worker message appears only after a failed player read, in the player's footprint, rather than during the read. The Music popout keeps its seasonal banner and bottom bar in place; the settings cog and wake-lock indicator are present after the preset gate resolves in every authenticated Spotify state. The initial gate uses a cog-sized placeholder, and the search field's slot keeps its height when no player is shown. Its saved font size and motion override apply from the first frame.

## Waits without a content shape

Keep a spinner for a pending button or action, a refresh icon, or an OAuth or redirect hand-off. These waits do not replace a shaped content area. In the seasonal dashboard, `SeasonalSpinner` is available for a standalone wait of this kind; inline button and input spinners stay ordinary so controls do not change width.

Stream-rendered overlay and widget output may render nothing until its data arrives. A dashboard preview of an overlay or widget is a dashboard loading surface and uses a placeholder matching the preview frame. Widget and overlay motion remains outside the dashboard motion preference even when previewed inside it.

## Motion and seasonal look

`Skeleton` carries `animate-pulse bg-muted`. The `animate-pulse` class is part of the motion contract: the baseline in `shared/ui/src/globals.css` exempts it under Reduced and Off, preserving an opacity pulse so loading remains perceptible. Do not replace that class with a custom animation without updating the motion rule. The placeholder uses theme tokens, so it works with the seasonal look off, Full or Subtle and in both light and dark themes. Seasonal decoration stays behind the skeleton and its controls.

The [Motion guide](/developer-guide/motion) records the motion behaviour; the [Seasonal look guide](/developer-guide/seasonal-look) covers dashboard and popout scope.

---

## Developer Guide / User Roles

Source: https://docs.lumio.vision/developer-guide/user-roles

# User Roles

## Overview

User Roles form the third RBAC layer in Lumio, sitting alongside the existing account-scope RBAC (controlling what a team member can do inside a streaming account) and the admin-scope RBAC (controlling what Lumio staff can do in the admin panel).

The User Role system governs what **authenticated users** - specifically users with direct access to the platform - can do. It controls actions like submitting ideas, commenting, and other user-facing community features that are not account-scoped. The system supports:

- **Default roles** - three globally seeded roles (`member`, `restricted`, `moderator`), created once by migration, not per user.
- **Custom roles** created by admins for specific access patterns.
- **Per-user role assignments** - `user_role_assignments` is keyed `(user_id, role_id)`; a user with no row at all falls back to the role marked `is_default`.
- **Per-user permission overrides** - grant or deny specific permissions for an individual user, regardless of their role.
- **Per-account permission overrides** - admins can expand or restrict what all members of a given streaming account can do. These apply to the *account*-scope permission list, not to the user-scope one.

All resolution is cached in Redis for performance.

## Tables

| Table | Description |
|-------|-------------|
| `user_roles` | Role definitions - `id`, `slug`, `name`, `description`, `is_default`, `is_system`, `created_at` |
| `user_role_permissions` | `PRIMARY KEY (role_id, permission)` - permissions granted by a role |
| `user_role_assignments` | `PRIMARY KEY (user_id, role_id)` - role assignments; no row means "use default role" |
| `user_permission_overrides` | `PRIMARY KEY (user_id, permission)` - explicit per-user allow/deny overrides |
| `account_permission_overrides` | `PRIMARY KEY (account_id, permission)` - per-account allow/deny overrides applied to all members of that account |

Schema: `apps/api/migrations/20260506000001_create_user_roles.up.sql` and `20260506000010_create_account_permission_overrides.up.sql`.

### Table: `user_roles`

| Column | Type | Notes |
|--------|------|-------|
| `id` | UUID PK | `gen_random_uuid()` |
| `slug` | TEXT UNIQUE | Machine identifier |
| `name` | TEXT | Display name, editable on custom roles |
| `description` | TEXT | Optional description |
| `is_default` | BOOL | The fallback role for users with no assignment |
| `is_system` | BOOL | System roles cannot be deleted |
| `created_at` | TIMESTAMPTZ | |

### Table: `user_role_assignments`

| Column | Type | Notes |
|--------|------|-------|
| `user_id` | UUID FK | References `users.id`, part of the composite PK |
| `role_id` | UUID FK | References `user_roles.id`, part of the composite PK |
| `assigned_by` | UUID FK? | Admin who made the assignment; `SET NULL` on user delete |
| `created_at` | TIMESTAMPTZ | |

### Table: `user_permission_overrides`

| Column | Type | Notes |
|--------|------|-------|
| `user_id` | UUID FK | References `users.id`, part of the composite PK |
| `permission` | TEXT | `resource:action` string, part of the composite PK |
| `granted` | BOOL | `true` = explicitly grant, `false` = explicitly deny |
| `reason` | TEXT | Optional free-text note recorded with the override |
| `set_by` | UUID FK? | Admin who set the override |
| `created_at` | TIMESTAMPTZ | |

### Table: `account_permission_overrides`

Same shape, keyed on `(account_id, permission)`:

| Column | Type | Notes |
|--------|------|-------|
| `account_id` | UUID FK | References `accounts.id`, part of the composite PK |
| `permission` | TEXT | `resource:action` string, part of the composite PK |
| `granted` | BOOL | `true` = explicitly grant for all account members, `false` = explicitly deny |
| `reason` | TEXT | Optional free-text note |
| `set_by` | UUID FK? | Admin who set the override |
| `created_at` | TIMESTAMPTZ | |

## Default Roles

Three roles are seeded by migration `20260506000002_seed_default_user_roles.up.sql`. All three have `is_system = true` and cannot be deleted.

| Role | Slug | `is_default` | Permissions |
|------|------|:------------:|-------------|
| **Member** | `member` | true | All ten user-scope permissions: `ideas:read`, `ideas:create`, `ideas:edit`, `ideas:delete`, `ideas:vote`, `ideas:comment_read`, `ideas:comment_create`, `ideas:comment_edit`, `ideas:comment_delete`, `ideas:comment_vote` |
| **Restricted** | `restricted` | false | `ideas:read`, `ideas:comment_read` - can browse but not submit, vote, or comment |
| **Moderator** | `moderator` | false | The ten member permissions plus the admin-scope moderation strings `ideas:moderate_status`, `ideas:moderate_edit`, `ideas:moderate_delete`, `ideas:moderate_comment` |

`ideas:edit` / `ideas:delete` / `ideas:comment_edit` / `ideas:comment_delete` cover the user's **own** content; editing or deleting someone else's requires the corresponding `ideas:moderate_*` grant.

The `member` role is the fallback for every user who does not have an explicit `user_role_assignments` row.

## Permission Resolution

The auth middleware (`crates/lo-api/src/middleware/auth.rs`) resolves the user-scope layer independently of the account layer, because it is account-independent:

1. **Check the Redis cache** - `lumio:user_perms:v2:{user_id}`, read in the same `MGET` as the combined entry and the generation keys. If present and stamped with the current generation, use the cached set and skip steps 2–4.
2. **Load role permissions** - `SELECT DISTINCT permission FROM user_role_permissions JOIN user_role_assignments`. If the user has **no** assignment row at all, fall back to the permissions of the role with `is_default = true`. The fallback keys off the *absence of an assignment*, not off an empty result - a deliberately restricted user assigned an empty role must not silently inherit the defaults (fail-closed).
3. **Apply per-user overrides** - for each row in `user_permission_overrides` for the user:
   - `granted = true`: add the permission to the set (grant even if not in role).
   - `granted = false`: remove the permission from the set (deny even if in role).
4. **Write to Redis** - cache the final permission set with a 5-minute TTL, stamped with the generation read in step 1.

The resolved set is stored in `AuthContext::User::user_permissions`. Use `auth.require_user_permission("resource:action")` (from `crates/lo-auth/src/context.rs`) to enforce it in REST handlers, and `resolvedUserPermissions` / `GET /v1/users/{user_id}/permissions/resolved` to inspect it from the admin panel.

### Account Permission Overrides

Account overrides apply to the **account-scope** list, not the user-scope one. In `load_permissions_from_db`, `account_permission_overrides` rows for the request's active `account_id` are folded onto the role-derived `account_permissions` set - `granted = true` inserts, `granted = false` removes - so they let a platform admin lift or clamp what every member of one streaming account can do. When the auth context has no active account the override pass is skipped entirely.

Because they land on a different list, an account override cannot grant or revoke a `ideas:*` user-scope permission, and the user-scope cache key (`lumio:user_perms:v2:{user_id}`) is unaffected by an account-override change; the account cache (`lumio:perms:v2:{user_id}:{account_id}`) is.

## AuthContext Changes

The `AuthContext::User` variant has a `user_permissions: Vec<String>` field populated by the auth middleware:

```rust
AuthContext::User {
    user_id: Uuid,
    account_id: Uuid,
    /// References the `sessions` table row for this request.
    session_id: Option<Uuid>,
    /// Permissions from `admin_roles` (admin panel access, support, etc.).
    admin_permissions: Permissions,
    /// Permissions from `account_roles` (per-account).
    account_permissions: Permissions,
    /// Permissions scoped to the user themselves (cross-account, non-admin).
    user_permissions: Permissions,
}
```

`Permissions` is `Vec<String>` (`crates/lo-auth/src/rbac.rs`).

**Enforcement helpers:**

```rust
// crates/lo-auth/src/context.rs
impl AuthContext {
    /// Checked against `user_permissions` ONLY — admin and account grants do not satisfy it.
    pub fn require_user_permission(&self, permission: &str) -> Result<(), AuthError> { ... }
    /// The resolved user-scope list; empty slice for non-`User` variants.
    pub fn user_permissions(&self) -> &[String] { ... }
}
```

`require_user_permission` returns `AuthError::Forbidden` for any non-`User` auth context (API key, popout/overlay/widget token, anonymous) and `AuthError::MissingPermission` → HTTP 403 when the grant is absent.

Use these in REST handlers exactly like `require_permission()` but targeting the user layer:

```rust
use lo_auth::rbac::user;

pub async fn create_idea(auth: Auth, ...) -> Result<HttpResponse, ApiError> {
    auth.require_user_permission(user::IDEAS_CREATE)
        .map_err(from_auth_error)?;
    // ...
}
```

Moderation paths in `apps/api/src/{graphql,routes}/ideas.rs` use the local helper `has_moderate_permission(auth, permission)`, which passes when **either** the user-scope or the admin-scope check succeeds - so a staff member with `ideas:moderate_*` on an admin role does not also need a user role carrying it.

## Cache

| Property | Value |
|----------|-------|
| Redis key | `lumio:user_perms:v2:{user_id}` |
| TTL | 300 seconds (5 minutes) |
| Type | JSON `{ epoch, ver, perms }` — the permission set plus the generation it was loaded under |

The user-scope set is also embedded in every combined `lumio:perms:v2:{user_id}:{account_id}` entry, so a user-scope change must invalidate both. Both are stamped with the generation keys `lumio:perms:ver:{user_id}` and `lumio:perms:epoch` (see [RBAC & Permissions → Redis Cache](./rbac-permissions.md#redis-cache)).

**Invalidation** - after the DB write, on both GraphQL and REST:
- A user's role assignment or permission overrides change → `invalidate_user_permission_cache(redis, user_id)` (bumps `lumio:perms:ver:{user_id}`).
- A user role's permission set changes or the role is deleted → `invalidate_all_permission_caches(redis)` (bumps `lumio:perms:epoch`). The holders of the default role are every user without an assignment, so they cannot be enumerated.

An account permission override change invalidates the **account** cache (`lumio:perms:v2:{user_id}:{account_id}`) via `RedisClient::invalidate_permissions()` instead - it never touches the user-scope entry.

Both helpers are defined in `crates/lo-api/src/middleware/auth.rs`.

## User Role Permission Constants

User-scope permission constants live in `crates/lo-auth/src/rbac.rs` inside `pub mod user {}`:

```rust
pub mod user {
    pub const IDEAS_READ: &str = "ideas:read";
    pub const IDEAS_CREATE: &str = "ideas:create";
    pub const IDEAS_EDIT: &str = "ideas:edit";
    pub const IDEAS_DELETE: &str = "ideas:delete";
    pub const IDEAS_VOTE: &str = "ideas:vote";
    pub const IDEAS_COMMENT_READ: &str = "ideas:comment_read";
    pub const IDEAS_COMMENT_CREATE: &str = "ideas:comment_create";
    pub const IDEAS_COMMENT_EDIT: &str = "ideas:comment_edit";
    pub const IDEAS_COMMENT_DELETE: &str = "ideas:comment_delete";
    pub const IDEAS_COMMENT_VOTE: &str = "ideas:comment_vote";

    /// Returns all user-scoped permission strings.
    pub fn get_all_user_permissions() -> Vec<&'static str> { /* ... */ }
}
```

`get_all_user_permissions()` is the registry for this scope - the nine strings above and nothing else. It is also exactly the set a **custom** user role may be assigned (`get_all_assignable_user_role_permissions()`): the `ideas:moderate_*` strings are **admin**-scope, live in `pub mod global {}`, and are **not** assignable to a user role. The seeded `moderator` role still grants them (it is `is_system` and immutable), but a `user-roles:edit` holder cannot mint or edit a custom role carrying `ideas:moderate_*` - that would let them self-assign platform-wide idea moderation without holding the admin permission. If a per-account idea-moderation need arises it must be a distinct account-scoped `ideas:*` permission, never the global operator string.

Always use the constants in code rather than string literals to prevent typos.

## API

### User Role CRUD (Admin)

The user role management API is admin-scoped. Reads are gated on `user-roles:read`; **creating** a role requires `user-roles:create`, **deleting** one requires `user-roles:delete`, and updating/assigning/overriding require `user-roles:edit`. The three write actions are distinct permissions - holding `user-roles:edit` alone does not let you create or delete roles.

#### GraphQL

The user-role resolvers are **not** prefixed with `admin` - they are guarded by `AdminPermissionGuard`, which is what makes them admin-only.

| Query / Mutation | Permission | Description |
|------------------|-----------|-------------|
| `userRoles` | `user-roles:read` | List all user roles with their permissions |
| `userRoleAssignments(userId: UUID!)` | `user-roles:read` | List a user's role assignments |
| `userRoleMembers(roleId: UUID!)` | `user-roles:read` | List the users holding a given role (role → members) |
| `userPermissionOverrides(userId: UUID!)` | `user-roles:read` | List a user's permission overrides |
| `resolvedUserPermissions(userId: UUID!)` | `user-roles:read` | Effective user-scope permission set after role + overrides |
| `createUserRole(input: CreateUserRoleInput!)` | `user-roles:create` | Create a custom user role |
| `updateUserRole(id: UUID!, input: UpdateUserRoleInput!)` | `user-roles:edit` | Update role name, description, permissions |
| `deleteUserRole(id: UUID!)` | `user-roles:delete` | Delete a custom role (system roles are rejected) |
| `assignUserRole(userId: UUID!, roleId: UUID!)` | `user-roles:edit` | Assign a user role |
| `removeUserRole(userId: UUID!, roleId: UUID!)` | `user-roles:edit` | Remove a role assignment |
| `setUserPermissionOverride(userId: UUID!, permission: String!, granted: Boolean!, reason: String)` | `user-roles:edit` | Set a per-user override |
| `removeUserPermissionOverride(userId: UUID!, permission: String!)` | `user-roles:edit` | Remove a per-user override |

#### REST

The REST twins are **not** under an `/admin` path prefix - they are gated by `require_admin_permission()` in the handler:

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/user-roles` | `user-roles:read` | List user roles |
| `POST` | `/v1/user-roles` | `user-roles:create` | Create a role |
| `PATCH` | `/v1/user-roles/{id}` | `user-roles:edit` | Update a role |
| `DELETE` | `/v1/user-roles/{id}` | `user-roles:delete` | Delete a role |
| `GET` | `/v1/user-roles/{id}/members` | `user-roles:read` | List the users holding a given role (role → members) |
| `GET` | `/v1/users/{user_id}/roles` | `user-roles:read` | List a user's role assignments |
| `POST` | `/v1/users/{user_id}/roles` | `user-roles:edit` | Assign a role |
| `DELETE` | `/v1/users/{user_id}/roles/{role_id}` | `user-roles:edit` | Remove a role assignment |
| `GET` | `/v1/users/{user_id}/permission-overrides` | `user-roles:read` | List a user's overrides |
| `PUT` | `/v1/users/{user_id}/permission-overrides` | `user-roles:edit` | Set an override (permission in the body) |
| `DELETE` | `/v1/users/{user_id}/permission-overrides/{permission}` | `user-roles:edit` | Remove an override |
| `GET` | `/v1/users/{user_id}/permissions/resolved` | `user-roles:read` | Effective permission set after role + user overrides + account overrides, computed without writing to cache |

Per-user role assignments and per-user overrides are gated on `user-roles:read` / `user-roles:edit` - **not** on the per-account override permissions (`accounts:overrides-read` / `accounts:overrides-edit`).

### Per-Account Permission Overrides (Admin)

These live on the admin surface (`apps/api/src/{routes,graphql}/admin.rs`) and are gated on the per-account override permissions - `accounts:overrides-read` (list) and `accounts:overrides-edit` (set / remove).

| GraphQL | REST | Description |
|---------|------|-------------|
| `adminAccountPermissionOverrides(accountId: UUID!)` | `GET /v1/admin/accounts/{id}/permission-overrides` | List overrides for an account |
| `adminSetAccountPermissionOverride(accountId: UUID!, permission: String!, granted: Boolean!, reason: String)` | `PUT /v1/admin/accounts/{id}/permission-overrides` | Set an override (permission in the body) |
| `adminRemoveAccountPermissionOverride(accountId: UUID!, permission: String!)` | `DELETE /v1/admin/accounts/{id}/permission-overrides/{permission}` | Remove an override |

The permission string on the set path is validated against `lo_auth::rbac::account::get_all_account_permissions()`, so an unknown key is rejected rather than silently stored.

## Admin Permissions

| Permission | Description |
|-----------|-------------|
| `user-roles:read` | View user roles, their permissions, and user assignments in the admin panel |
| `user-roles:create` | Create custom user roles |
| `user-roles:edit` | Update custom user roles; assign or remove role assignments; set and remove **per-user** permission overrides |
| `user-roles:delete` | Delete custom user roles |
| `accounts:overrides-read` | Read **per-account** permission overrides (`GET /v1/admin/accounts/{id}/permission-overrides`) |
| `accounts:overrides-edit` | Set and remove **per-account** permission overrides (`PUT` / `DELETE /v1/admin/accounts/{id}/permission-overrides`) |

These are admin-scope permissions, defined in `crates/lo-auth/src/rbac.rs::global` and enforced via `AdminPermissionGuard` / `require_admin_permission()`.

`global` also declares `user-roles:create` and `user-roles:delete`, and a migration seeds them onto admin roles, but **no handler currently checks them** - role creation and deletion both gate on `user-roles:edit` on REST and GraphQL alike. Do not rely on the finer pair as an access boundary.

## Key Files

| File | Purpose |
|------|---------|
| `crates/lo-auth/src/rbac.rs` | User-scope permission constants (`pub mod user {}`) + `get_all_user_permissions()` |
| `crates/lo-auth/src/context.rs` | `require_user_permission()` and `user_permissions()` on `AuthContext` |
| `crates/lo-api/src/middleware/auth.rs` | Resolves + caches all three permission scopes per request |
| `crates/lo-cache/src/client.rs` | `read_permission_cache()` / `cache_user_permissions()` / `bump_user_permission_generation()` / `bump_permission_epoch()` Redis helpers |
| `apps/api/src/db/account_overrides.rs` | CRUD for `account_permission_overrides` |
| `apps/api/src/graphql/user_roles.rs` | GraphQL queries and mutations for user roles, assignments, overrides |
| `apps/api/src/routes/user_roles.rs` | REST handlers for user roles, assignments, overrides |
| `apps/api/src/db/user_roles.rs` | DB operations: CRUD, assignment, override management, permission resolution |
| `apps/api/migrations/20260506000001_create_user_roles.up.sql` | Tables for roles, permissions, assignments, and per-user overrides |
| `apps/api/migrations/20260506000002_seed_default_user_roles.up.sql` | Seeds `member` / `restricted` / `moderator` and their permission sets |
| `apps/api/migrations/20260506000010_create_account_permission_overrides.up.sql` | `account_permission_overrides` table |
| `apps/admin/src/app/(admin)/user-roles/` | Admin panel pages for user role management |

---

## Developer Guide / Audit Events (Developer Guide)

Source: https://docs.lumio.vision/developer-guide/audit-events

# Audit Events (Developer Guide)

This guide covers the **write** side of the audit log: when a change must emit an
audit event, and how to emit it correctly. For the **read** side - scopes, read
surfaces, permissions and the `AuditEvent` field list - see
[Audit Log](../features/audit-log.md); for the operator view see
[Admin · Audit Log](../admin/audit-log.md).

For audit data retention, TimescaleDB design, and deletion paths, see the
[data design standard](./data-design.md).

## The rule

### Sign-in, privacy and support events

The current catalog in `apps/api/src/db/audit.rs` contains these event types. Their protocol twins call the same security service and emit with the same scope. Event metadata contains identifiers and outcomes where useful, never passwords, codes, Turnstile tokens or sign-in links.

| Scope | Event types |
|---|---|
| User: email and password | `user:email_login_added`, `user:email_verified`, `user:email_login_requested`, `user:email_login_changed`, `user:email_login_cancelled`, `user:password_changed`, `user:password_reset_requested`, `user:password_reset_completed`, `user:login_method_removed` |
| User: 2FA and confirmation | `user:mfa_enabled`, `user:mfa_disabled`, `user:mfa_factor_added`, `user:mfa_factor_removed`, `user:mfa_recovery_codes_regenerated`, `user:mfa_recovery_code_used`, `user:mfa_challenge_failed`, `user:mfa_trusted_device_revoked`, `user:step_up_verified` |
| User: profile identity | `user:profile_identity_changed` (metadata `changed` = list of `source` / `display_name` / `avatar`, plus `source` = `own` / `connection` for a source switch; never a name or picture URL) |
| User: privacy | `user:data_export_requested`, `user:data_export_cancelled`, `user:data_export_downloaded`, `user:deletion_scheduled`, `user:deletion_cancelled` |
| Account | `account:member_left`, `account:subscription_cancel_requested`, `account:dissolution_scheduled` (metadata `grace_days`, `scheduled_for`), `account:dissolution_cancelled` (metadata `scheduled_for`, the cancelled date), `account:identity_changed` (metadata `changed` = list of `source` / `name` / `avatar`, `source_kind`, `source_platform`), `account:dissolved` (metadata `via` = `immediate` / `scheduled`, `deleted_history_row_count`, `deleted_object_count`, `pending_object_count`) |
| System | `system:user_mfa_reset`, `system:support_code_viewed`, `system:support_code_checked`, and `system:user_deleted` for the completed self-service deletion |

`user:deletion_scheduled` carries `grace_days` (0, 7 or 30) and `scheduled_for`. The three dissolution events are account-scoped with the owner as actor and are emitted identically by GraphQL and REST. `account:dissolved` with `via: "immediate"` comes from `dissolveAccount` / `DELETE /v1/accounts/{id}` or a `graceDays: 0` schedule; `via: "scheduled"` comes from the account security worker when the grace period ends, with the owner who scheduled it as actor. `user:login` and `user:login_failed` include the sign-in `method`; a login that needs 2FA is recorded only after the challenge succeeds. Support-code reveal and check include the target user and result, without the code. `system:user_mfa_reset` carries the required operator reason. The current code's event catalog, emitter calls and REST/GraphQL guards should be checked together before modifying this list.

**Security- and lifecycle-relevant actions emit an audit event in the same change
that ships them.** An audit trail that the documentation promises but the code
never writes is a compliance defect, not a missing nice-to-have.

Treat "does this need an audit event?" as a standing review question, alongside
RBAC gating and GraphQL ↔ REST parity.

## When to emit

Emit when an action is security-relevant, tenant-visible, or irreversible:

| Category | Examples |
|----------|----------|
| Authentication & identity | Login, failed login, MFA enable/disable, OAuth grant |
| Credentials | API-key create/revoke, channel connection added/removed |
| Permission structure | Role create/update/delete, member role assignment |
| Destructive / GDPR | Data erasure, retention purges, account deletion |
| Platform operations | Admin actions, feature-flag flips, plan changes |

Do **not** emit for:

- Reads and list queries - the audit log records changes, not access.
- High-volume telemetry (chat messages, stream events, metrics). The audit log is
  a security record with a compression policy, not an analytics stream.
- Purely internal bookkeeping with no security or tenant-visible consequence.

## How to emit

The canonical API lives in `apps/api/src/db/audit.rs`:

```rust
crate::db::audit::emit(&tsdb.0, crate::db::audit::AuditEventFields {
    account_id: Some(account_id),
    user_id: actor_user_id,
    event_type: crate::db::audit::event_types::ACCOUNT_ROLE_CREATED,
    scope: crate::db::audit::AuditScope::Account,
    ip_address: origin.ip_address.as_deref(),
    user_agent: origin.user_agent.as_deref(),
    country: origin.country.as_deref(),
    city: origin.city.as_deref(),
    metadata: serde_json::json!({ "role_id": role_id, "slug": slug }),
})
.await;
```

**Use `db::audit::emit`, never `insert_audit_event`, in new code.** `emit` is
best-effort by design: it logs a `tracing::warn!` and swallows the error, because
a failed audit insert must never fail - or roll back - the user-facing mutation
that triggered it.

### Catalog first, call site second

Every emit references a constant from `db::audit::event_types`. Add the constant
to the catalog **before** the call site; never inline a string literal. The
catalog is the single source of truth that the docs and the admin event-type
filter are checked against.

Naming is `domain:action` (`account:role_created`, `user:login`,
`system:feature_flag_updated`), where `domain` matches the row's scope. The two
legacy GDPR types (`youtube_member_erasure`, `chat_pii_erasure`) stay
un-namespaced on purpose - the admin filter pins those exact strings, so renaming
them is a coordinated change, not a drive-by.

### Scope is explicit, never inferred

`scope` is set by the writer on every row and is `NOT NULL` with no default, so a
writer that forgets fails closed. Never infer scope at read time from which of
`account_id` / `user_id` happens to be populated - that inference leaks
authorization boundaries between tenants.

| Scope | Use for |
|-------|---------|
| `AuditScope::User` | Personal security events, readable self-only |
| `AuditScope::Account` | Tenant actions, gated on account `audit-log:read` |
| `AuditScope::System` | Platform-operator / cross-account actions |

**One event, one scope.** An account-context action with an actor lives only in
the account log (the actor is shown via `user_id`); it is never additionally
mirrored into that user's personal log.

### Actor, target, metadata

`user_id` is always the **actor**, never the target. The target and any context
go in `metadata` (`role_id`, `target_user_id`, `platform`, …). Never put secrets,
tokens, credentials, or raw PII in `metadata` - audit rows are readable by every
account member holding `audit-log:read`.

Some of those id keys (`target_user_id`, `member_id`, `from_account_id`,
`to_account_id`, `target_account_id`, `role_id`) are resolved to display names at
read time - see [Read-time UUID → name resolution](#read-time-uuid--name-resolution-zaf-1233).

### Origin enrichment

Resolve the request origin instead of hand-building it:

- GraphQL - `crate::graphql::audit_origin_from_ctx(ctx)`
- REST - `AuditOrigin::resolve(state.geoip.as_ref(), crate::routes::auth::extract_client_ip(req), crate::routes::auth::extract_user_agent(req))`

The resolved `AuditOrigin` carries the client IP, the request **user agent**, and
the GeoIP `country` / `city`. Read all four off the origin at
the call site (`origin.user_agent.as_deref()`, not `None`) so **every**
request-originated audit row records the user agent, not just `user:login*` - the
admin and per-user Account-Activity views derive device / browser / OS from that
string at render time (ZAF-1412, closing the ZAF-1023 backfill deferral). GeoIP
is fail-open: `country` / `city` stay `None` when GeoIP is disabled or the IP is
private, and `user_agent` stays `None` when the header is absent. Never block or
fail a mutation on origin resolution.

**Background emitters have no request**, so their origin - and therefore
`user_agent` - is `None`: the token-refresh worker (`services/reconnect.rs`) and
the Stripe webhook plan-change emitter (`routes/billing.rs`) build the fields with
every origin column `None`. That is correct, not a gap - there is no client to
attribute. The GDPR-erasure services (`services/chat_privacy.rs`,
`services/youtube_memberships.rs`) are the opposite case: they *receive* a
request-derived origin from their admin REST/GraphQL callers, so they **do**
record the user agent.

**Shopify embedded actions record the user agent and no IP.** The three events
the embedded app writes (`POST /v1/shopify/embedded/link/complete`, `PUT
/v1/shopify/embedded/settings`, `POST /v1/shopify/embedded/disconnect`) build
their origin with `routes::shopify_embedded::audit_origin`, which keeps
`ip_address`, `country` and `city` `None` and records only the request's own
`User-Agent` (the merchant browser's, forwarded by `apps/shopify`). The actor is
identified by `shopify_user_id` + `shop_host` in the metadata instead. See
[How the client IP is resolved](#how-the-client-ip-is-resolved) for why.

#### How the client IP is resolved

Both helpers end up in `lo_api::client_ip::resolve`, which reads the headers in
one of two orders depending on **who** is calling:

| Caller | Precedence |
|---|---|
| First-party server hop (a valid `X-Internal-Token`) | `X-Lumio-Client-IP` → `X-Forwarded-For` (first hop) → `X-Real-IP` → `CF-Connecting-IP` → peer address |
| Everything else (a direct browser/client request) | `CF-Connecting-IP` → `X-Forwarded-For` (first hop) → `X-Real-IP` → peer address |

Almost no audit event is emitted for a request the end user made *directly*
against the API. The browser talks to a Next.js route handler or server
component, which then calls the API server-to-server - so from the API's point of
view the request peer is the web/admin/id service. Those services resolve the
user's origin (`cf-connecting-ip` → `x-real-ip` → first hop of
`x-forwarded-for`, in `apps/{web,admin,id}/src/lib/client-ip.ts`) and forward it
on that internal hop.

The Shopify embedded scope (`/v1/shopify/embedded/*`) is the exception: it
records no IP and no geo, only the user agent. The scope is mounted outside the
`/v1` middleware stack, so `TrustedInternalCaller` is never set on it, and
`apps/shopify` holds no `X-Internal-Token`. The only IP the API could read there
is the `apps/shopify` server's egress address or a header the client chose
(`CF-Connecting-IP`, `X-Forwarded-For`, `X-Lumio-Client-IP`). Giving
`apps/shopify` the shared internal token would also unlock IP/UA trust and the
choice of the `proxied:{ip}` rate-limit bucket on every `/v1` route, so it does
not get one (AppSec ZAF-2996 S2). `apps/shopify` forwards `User-Agent` only. The
actor of those rows is identified by `shopify_user_id` + `shop_host` in the
metadata.

The forwarded value has to **outrank** `CF-Connecting-IP` on that hop. When the
internal call itself travels through Cloudflare - a public `LUMIO_API_URL` - the
edge stamps `CF-Connecting-IP` with the *web server's own* egress IPv4/IPv6, and
preferring it wrote the web server's address into every `audit_events.ip_address`
and every personal Account-Activity row instead of the user's (ZAF-1208).

##### Why a private header and not just `X-Forwarded-For`

`X-Forwarded-For` is the header every reverse proxy in the chain feels entitled
to rewrite, so it cannot be relied on to carry a value end to end. The staging
Caddy rewrites it explicitly:

```caddyfile
reverse_proxy lumio-api:3000 {
    header_up X-Forwarded-For {http.request.header.CF-Connecting-IP}
}
```

`header_up <field> <value>` **replaces** the field - `+field` would append - so
whatever `apps/web` forwarded is discarded and overwritten with
`CF-Connecting-IP`, which on the web→API hop is the web container's own egress
address. Forwarding `X-Forwarded-For` alone is therefore not enough: the value
never survives to the API.

So the first-party services send the origin under a private name as well,
`X-Lumio-Client-IP` (`lo_api::client_ip::CLIENT_IP_HEADER`, mirrored as
`CLIENT_IP_HEADER` in each app's `lib/client-ip.ts`). No proxy or CDN rewrites a
non-standard header, so it arrives intact - the fix holds with no infrastructure
change, and keeps holding if the proxy in front of the API is swapped.
`X-Forwarded-For` is still sent next to it, for rate-limit bucketing, request
logging, and hops that reach the API with no rewriting proxy in between (local
dev, direct container-to-container networking). Use `clientOriginHeaders(ip, ua)`
rather than setting either header by hand — it carries both the IP and the
User-Agent (below) as one first-party origin.

For a direct request the order is reversed on purpose: `CF-Connecting-IP` is set
by the edge and a client cannot forge it, while `X-Forwarded-For` is
client-settable. `X-Lumio-Client-IP` is **ignored entirely** outside the
trusted-internal branch, so an outside client cannot use it to forge its own
audit origin. That branch does not widen the trust boundary either —
`TrustedInternalCaller` is only inserted on a constant-time match against the
configured `X-Internal-Token` secret. **Rate-limit bucketing does not use this
helper**, because its `X-Forwarded-For` / `X-Real-IP` fallbacks are
client-settable on a direct request. It uses `lo_api::client_ip::throttle_key`,
which reads only `X-Lumio-Client-IP` on a trusted-internal hop and only
`CF-Connecting-IP`, else the peer address, otherwise. A forged header therefore
never mints rate-limit buckets (see [Authentication → Rate
Limits](../api-reference/authentication.md#rate-limits)).

#### How the client User-Agent is resolved

The User-Agent has the **same** first-party-hop blind spot as the IP, and the
same fix (ZAF-1414, the twin of ZAF-1208). Node's global `fetch` sends
`User-Agent: node`, so a request that reaches the API through a Next.js service
carries `node` as its own `User-Agent` — and without a forwarding channel
`sessions.user_agent` and every audit `user_agent` would record the web
container, not the browser. `crate::routes::auth::extract_user_agent` (used by
the REST session handlers and the audit emitters) and the GraphQL `UserAgent`
context datum both resolve through `lo_api::client_ua::resolve`, which reads the
headers in one of two orders depending on **who** is calling:

| Caller | Precedence |
|---|---|
| First-party server hop (a valid `X-Internal-Token`) | `X-Lumio-Client-UA` → request `User-Agent` |
| Everything else (a direct browser/client request) | request `User-Agent` |

The first-party services forward the browser UA under the private
`X-Lumio-Client-UA` (`lo_api::client_ua::CLIENT_UA_HEADER`, mirrored as
`CLIENT_UA_HEADER` in each app's `lib/client-ip.ts`) for the same reason the IP
uses a private name: the standard `User-Agent` header on that hop is Node's
`node`, so it cannot carry the browser UA. Like `X-Lumio-Client-IP`, it is
honoured **only** inside the trusted-internal branch — `TrustedInternalCaller`,
gated on the same constant-time `X-Internal-Token` match — so an outside client
cannot use it to forge the UA recorded against an audit event or a session. A
blank value on either source resolves to `None` (the `user_agent` column stays
`NULL`).

> **`INTERNAL_TOKEN` gates **both** the IP and the UA:**
> The trusted-internal branch is entered only when the caller presents a valid
> `X-Internal-Token`. If `INTERNAL_TOKEN` is **not set** in an environment, the
> first-party hop is not recognised as trusted: `X-Lumio-Client-IP` /
> `X-Lumio-Client-UA` are both ignored, and the IP **and** the UA fall back to the
> edge/server values (`CF-Connecting-IP` and the request's own `node`). Provision
> `INTERNAL_TOKEN` on the API and the matching secret on web/admin/id, or every
> web-proxied audit row and session records the web container's origin.

### Where the rows live

Audit events are written to the **TimescaleDB** pool (`state.tsdb` /
`lo_graphql::health::TsdbPool`), not the primary Postgres pool. The `audit_events`
hypertable and its migrations live in `apps/api/tsdb_migrations/`, not
`apps/api/migrations/`.

Retention is two native TimescaleDB scheduled jobs, both daily and always on:

- `anonymise_old_audit_events`
  (`tsdb_migrations/20260823000002_anonymise_audit_events_retention.up.sql`) nulls
  `ip_address` / `user_agent` / `country` / `city` on rows older than 12 months.
- `purge_old_audit_events`
  (`tsdb_migrations/20261011130000_purge_old_audit_events.up.sql`) deletes rows
  older than 24 months. The erasure-proof types are kept until 36 months; whole
  chunks past 36 months are dropped with `drop_chunks`.

So `metadata` lives for 24 months (36 for an erasure proof) and is never
anonymised before that - do **not** put anything in it that must disappear
sooner, and never secrets or raw PII.

The erasure-proof list has one source of truth:
`db::audit::event_types::ERASURE_PROOF`. The purge job reads the same list from
its `config -> 'erasure_proof_types'`, and `tests/tsdb_audit_purge.rs` asserts
the two are equal. A new erasure-proof type therefore needs the constant **and**
a TSDB migration that runs
`alter_job(<job_id>, config => '{"erasure_proof_types": [...]}')`. The job fails
closed: if that config key is missing or empty, it raises before deleting
anything, so an `alter_job` mistake cannot delete erasure proofs at 24 months. See
[Audit Log → Retention](../features/audit-log.md#retention).

### Events that originate outside the API (apps/id ingest)

Some user-scope security events happen in **apps/id** (NextAuth, TypeScript), not
in the Rust API. Today apps/id emits **web login** and **OAuth grant** rows; the
ingest endpoint also whitelists 2FA lifecycle rows, but no current product flow
calls it for MFA. The Rust API is the single audit writer, so apps/id does
**not** write `audit_events` itself - it posts each event server-to-server to
[`POST /v1/internal/audit-ingest`](../api-reference/rest-api.md#post-v1internalaudit-ingest)
after the auth event, and the endpoint writes the row via `insert_audit_event`.

The user-scope login events apps/id **cannot** ingest are emitted in-process from
the Rust `/auth` handlers instead, because they need a subject apps/id does not
have at the NextAuth callback:

- **`user:login` for the native (PKCE) flow** - `POST /v1/auth/authorize` returns
  only an auth `code`; the subject/JWT is minted later when the native app redeems
  the code against `POST /v1/auth/token/exchange`, directly against the API. That
  redemption handler is the single authoritative `user:login` emit point for the
  native flow (the web flow stays on apps/id ingest); `metadata.method = "pkce"`.
- **`user:login` for the GraphQL `exchangeToken` mutation** (ZAF-1023) —
  `graphql/auth.rs` `exchange_token` emits `user:login` inline on success with
  `metadata.method = "graphql_exchange"`. This is the GraphQL path's *only*
  login-success writer and must not be removed: `exchangeToken` has no first-party
  caller (apps/id, web, and admin all use REST `/auth/token`), so the apps/id
  audit-ingest that covers the REST twin's success (see below) never observes it.
- **`user:login_failed`** - a rejected OAuth credential has no resolved user at the
  NextAuth callback (bad credentials are rejected upstream by the provider). The
  Rust REST `exchange_token` / `authorize` handlers **and the GraphQL
  `exchangeToken` mutation** (ZAF-1023, at parity) emit it on a failed
  provider-token validation, and `token_exchange` emits it on a PKCE mismatch. The
  subject is resolved from the existing login connection for the (unverified)
  provider identity when one exists - so a failed attempt against a known user
  lands in that user's personal-security log - otherwise the row is unattributed
  (`user_id = NULL`), never leaked into an arbitrary user's log. These emit via
  the in-process best-effort `emit`, not the ingest endpoint. Both paths capture
  the request User-Agent (the GraphQL context grows a `UserAgent` datum for this).

This is the one sanctioned use of the internal ingest endpoint, and the reasons
it deviates from the in-process `emit` pattern:

- **Auth is a System key with the narrow `audit:ingest` grant.** Every non-System
  principal is rejected `403` (anonymous `401`) so no public/user route can forge
  audit rows; a System key without the grant is `403` too. Provision apps/id's key
  with `audit:ingest` (or `audit:*` - a bare `*:*` does **not** grant it).
- **The endpoint forces the shape.** It whitelists the five user-scope catalog
  types above and forces `scope = user`, `user_id = <subject>`,
  `account_id = NULL`; a caller cannot widen scope, attach a tenant, or write an
  `account:*` / `system:*` type.
- **It uses `insert_audit_event`, not `emit`, on purpose.** Here the audit write
  *is* the request's whole purpose (there is no user-facing mutation to protect),
  so the endpoint propagates a failed insert to apps/id as a real error rather
  than silently swallowing it. This is the deliberate exception to the
  "`emit`, never `insert_audit_event`" rule above - do not copy it into an
  in-process emitter.

The apps/id call sites live in `apps/id/src/auth.ts` (NextAuth `signIn`
callback) via the best-effort helper `emitUserAuditEvent` in
`apps/id/src/lib/audit.ts`. The helper posts to the ingest endpoint with apps/id's
System key (env `LUMIO_AUDIT_INGEST_KEY`, an `lm_sys_*` key with `audit:ingest`),
forwards the **end-user's** IP and user-agent (the request peer is the id
service, not the acting user), and never blocks or fails the auth flow - a
timeout or non-2xx response is logged and swallowed.

`LUMIO_AUDIT_INGEST_KEY` is carried by `apps/id/.env.example` and
`dev-stack/staging/.env.id.example`, and read through
`getAuditIngestKey()` in `apps/id/src/lib/config.ts`.

> **Provisioning the ingest key:**
> `LUMIO_AUDIT_INGEST_KEY` must hold an `lm_sys_*` System key that carries the
> `audit:ingest` grant. Mint one from the admin app under **System → System-API-Schlüssel**:
> `audit:ingest` is part of the System-key assignable-scope registry
> (`lo_auth::rbac::system_key::get_assignable_permission_infos()`), so the admin
> create dialog offers it and both create paths accept it. Set the resulting secret
> as `LUMIO_AUDIT_INGEST_KEY` in apps/id's environment. Until it is set the apps/id
> trail below is **not** written - the fail-loud signals in the next paragraph are
> what make that state visible.

**Fail-loud when the ingest key is unset.** A missing/misconfigured
`LUMIO_AUDIT_INGEST_KEY` disables the whole apps/id audit trail - every
user-scope security event is silently dropped while the app still looks healthy,
a DSGVO Art. 5(2)/32 accountability defect. To make that state observable without
ever blocking login, apps/id surfaces it two ways:

- **Log once per process.** When the key is unset **and** `NODE_ENV ===
  "production"`, `emitUserAuditEvent` emits exactly one `console.error`
  (`[audit] LUMIO_AUDIT_INGEST_KEY is unset in production - user-scope security
  events are being dropped.`) for the process lifetime, then returns. Local dev
  with no key stays silent, and a per-call skip for a missing subject `user_id`
  stays silent (it is a normal skip, not an operator condition).
- **Health field.** [`GET /api/health`](../getting-started/installation.md) on
  apps/id returns `audit_ingest_configured` (a boolean —
  `Boolean(process.env.LUMIO_AUDIT_INGEST_KEY)`, the key value is never printed),
  so the disabled state is pollable/alertable, not just log-greppable.

Wired today (both carry a resolved Lumio `user_id`):

- **`user:login`** - successful web login, after the provider token is exchanged
  for a Lumio JWT; the subject is decoded from the issued JWT's `sub` claim.
- **`user:oauth_granted`** - an already-authenticated user links/reconnects a
  provider connection (OAuth consent); the subject is decoded from the session
  JWT.

The Rust security service emits **`user:mfa_enabled` / `user:mfa_disabled`** when a
user enables or disables two-factor authentication. The first app or passkey emits `user:mfa_enabled`; further methods emit `user:mfa_factor_added`. Removing one while another remains emits `user:mfa_factor_removed`; removing the last emits `user:mfa_disabled`. Metadata includes `method` (`totp` or `passkey`) and a non-secret `factor_id`; further additions/removals include the resulting `factor_count`, additions may include `aaguid`, and removals include `trusted_devices_revoked`. The user-chosen label is never logged. These user-scoped events do not rely on apps/id audit ingest.

## Profile email-change event (in-process, ZAF-913)

A change of the profile email is the classic account-takeover vector (email
change → password-reset link → takeover), so it is a personal-security event
worth recording. The profile email is not typed in (`updateMe` /
`PATCH /v1/users/me` refuse `email`); it changes only through the email sign-in
and the platform-address "Remove":

- **`user:email_changed`** (`AuditScope::User`) - emitted in-process by the
  security service (`services/security/email_login.rs`), which REST and GraphQL
  share: when the email sign-in is set up and its address becomes the profile
  email (`source: "email_login"`), when the email sign-in is removed and the
  profile email falls back to the remembered platform address or to none
  (`source: "platform:<provider>"` / `"none"`), and when a platform address is
  removed (`cleared: true`). A changed sign-in address is recorded as
  `user:email_login_changed`. Actor = the acting user (`user_id`), no tenant
  `account_id`. The address is PII and is **never** written to `metadata` - the
  row carries only a `had_previous_email` boolean and the source / `cleared`
  flag. Best-effort, so a failed audit insert never rolls back the change.

## Token-refresh reconnect events (in-process, ZAF-754)

The **Token Refresh Worker** (`apps/api/src/workers/token_refresh.rs`) is the
automatic producer of the reconnect signal. When a refresh fails **terminally**
(`invalid_grant` / `unauthorized_client` / HTTP 400/401) it flips
`reconnect_required` false→true and, on that single transition
(`services::reconnect::notify_reconnect_required`), emits:

- **`account:connection_reconnect_required`** (`AuditScope::Account`) for a
  channel or bot connection - actor is the account, `metadata` carries `platform`
  + `connection_type` + `reason`.
- **`user:login_reconnect_required`** (`AuditScope::User`) for a login connection - subject is the owning user.

`reason` is `token_refresh_terminal` for this path. The Twitch EventSub and Kick
subscription workers are a second producer for channel connections: after a
provider HTTP 401 they force one refresh
(`oauth::refresh_rejected_connection_token`), and when that is rejected or the
new token gets a second 401 they flag the row and emit the same event through
`services::reconnect::ReconnectNotifier` with `reason = provider_rejected_token`.

There is no HTTP request behind the worker, so no IP/GeoIP origin is attached.
The same transition also sends the `lo_email` reconnect email. These have **no
GraphQL/REST counterpart** (the worker is the only trigger), so protocol parity
does not apply.

## Extension chat moderation

- **`account:extension_moderation`** (`AuditScope::Account`) - an installed
  extension ran `chat:delete`, `chat:ban`, `chat:unban` or `chat:timeout`
  through the action dispatcher, and the platform applied it. Emitted by
  `services::extension_chat::emit_moderation_audit`
  (`apps/api/src/services/extension_chat.rs`) at the end of
  `extension_chat::moderate`, which every caller reaches through
  `services::extension_actions::execute_action`:
  - **widgets and apps** (`useLumioAction`) - REST
    `POST /v1/extension-installs/{install_id}/actions/{action}` and GraphQL
    `executeExtensionAction` write the same row; the origin is the extension
    host's call;
  - **bot modules** - the `actions` of a handler result or a `defineModerate`
    decision, run through the internal
    `POST /v1/internal/bot-modules/{install_id}/actions`
    (`services::bot_module_actions`). The origin is empty: the call is
    service-to-service, and the worker's address is not the actor's.

  `user_id` is `NULL`: the actor is the extension, and the account's bot
  carried the action out. `metadata` = `source` (`extension` for widgets and
  apps, `bot_module` for bot modules), `extension_id`, `install_id`, `action`
  (`delete` | `ban` | `unban` | `timeout`), `platform`, `target_user_id`
  (`null` for delete), `duration_secs` (timeout only). The reason text is
  never written.
- A **bot module's `chat:delete` is not audited**
  (`extension_chat::is_audited`): a moderation module deleting a spam raid
  would flood the 12-month security log. It is recorded in the install's log
  (`extension_install_logs`) only. Bot-module bans, unbans and timeouts, and
  every widget/app `chat:delete`, are audited.
- A refused action (`bot_not_connected`, `bot_scope_missing`,
  `moderation_forbidden`, `platform_not_supported`, …) writes nothing.
- Human moderation (`moderateChat` / `POST /v1/chat/moderate`) emits no audit
  event; it is recorded in `platform_moderation_log`. An extension acting on the
  tenant is a third party, so its moderation is a security record as well.
  Extension `chat:send` emits nothing (high-volume telemetry class).
- Coverage: `apps/api/tests/audit_emitters.rs`
  (`extension_moderation_emitter_is_account_scoped_without_actor_or_reason`),
  the no-row-on-refusal checks in `apps/api/tests/zaf2391_extension_actions.rs`
  and the bot-module path in `apps/api/tests/zaf2398_bot_module_actions.rs`.

## Automation webhook target refused

- **`account:webhook_target_blocked`** (`AuditScope::Account`) - a manual run
  of an automation reached a `webhook_call` node whose target
  `apps/api/src/webhook_target.rs` refused (`invalid_url`, `scheme_not_allowed`
  or `private_target`). Emitted by `RedisActionDispatcher::call_webhook`
  (`apps/api/src/dispatch.rs`) when the dispatcher carries a `WebhookAudit`
  context. Both protocols build that context in one place,
  `services::automation_execute::execute_manual`, so GraphQL `executeAutomation`
  and REST `POST /v1/automations/{id}/execute` write the same row: the member as
  `user_id`, the request origin, and `metadata` = `automation_id`, `reason`,
  `scheme`. The host, path and query are tenant-templated and can carry secrets,
  so they are never written.
- Event- and timer-triggered runs (`workers/automation.rs`,
  `workers/automation_timer.rs`) carry no audit context: a misconfigured target
  would repeat the refusal on every trigger. They log it server-side only.
- Covered by `apps/api/tests/automation_webhook_target.rs`.

## Active-account switch (ZAF-908)

- **`user:active_account_switched`** (`AuditScope::User`) - the acting user
  switched (or cleared) their session's `active_account_id`. This is
  identity-relevant: it changes the RBAC scope every subsequent request on that
  session runs under, and re-mints the session cookie (with the **same**
  `session_id`, so revocation still reaches it - see `features/sessions.md`).
  The actor is the user; the **from/to** account ids, a `cleared` flag, and the
  `session_id` of the device that switched ride in `metadata` (account selection
  is per-session since ZAF-1416, so the log records which device changed; the
  session id is an opaque uuid - no secret/PII). `account_id` is
  **NULL**: a personal switch is *not* a tenant action, so it stays out of the
  switched-to account's `audit-log:read` log (an account admin must not be able
  to enumerate who is switching into their account).
- **Emit sites** - GraphQL `updateMe` (`apps/api/src/graphql/auth.rs`) and its
  REST twin `PATCH /v1/users/me` (`apps/api/src/routes/users.rs`), on the same
  condition that re-mints the cookie (`active_account_id` set, or
  `clear_active_account`). Same event type, scope and metadata on both protocols
  (parity). Both use the standard best-effort in-process `emit`.

## Session-lifecycle events (ZAF-911)

Ending or revoking a session is a personal security action on the user's own
credential - "log out everywhere" is exactly what the audit log exists to record.
Both events are `AuditScope::User`, keyed to the acting user with **no** tenant
`account_id`, and go through the shared user-scope helpers so REST and GraphQL
write the same shape:

- REST - `crate::routes::audit::emit_user_audit(state, req, actor_user_id, event_type, metadata)`
- GraphQL - `crate::graphql::emit_user_audit(ctx, actor_user_id, event_type, metadata)`

Catalog constants (`db::audit::event_types`):

- **`user:logout`** - the user ended one of their own sessions via a logout flow:
  GraphQL `logout(refreshToken)` / `logoutSession`, REST `POST /v1/auth/logout`.
  `metadata` carries the ended `session_id` (when the deleted row is known) and
  the `method` (`refresh_token` | `session`). For the refresh-token flow the
  actor and session id come from the deleted session row (`delete_session` now
  `RETURNING id, user_id`), so an expired-but-authentic logout still records the
  row; `logoutSession` takes them from the JWT claims.
- **`user:session_revoked`** - the user revoked session(s) from session
  management: GraphQL `deleteSession(id)` / `deleteAllOtherSessions`, REST
  `DELETE /v1/users/me/sessions/{id}` / `DELETE /v1/users/me/sessions`. `metadata`
  distinguishes a **single** revoke (`session_id`, `revoked_all: false`) from a
  **bulk** revoke (`count`, `revoked_all: true`).

**Emit is gated on an actual change.** A logout that matched no session, a
single revoke of a not-found id, and a bulk revoke that removed zero rows all
write **nothing** - a no-op is not a security event.

**No-secret rule.** `metadata` carries only the non-secret `session_id` /
`count` / `method` / `revoked_all` - never the refresh token, the session
`token_hash`, or any PII (every reader of the user log is the user themselves,
but the discipline is the same as every other emitter).

**Parity.** The refresh-token `logout` / `POST /v1/auth/logout` pair and the
`deleteSession` / `deleteAllOtherSessions` GraphQL mutations and their
`DELETE /v1/users/me/sessions[...]` REST twins emit identical event type, scope
and metadata on both protocols. `logoutSession` is a GraphQL-only convenience
(the REST logout is refresh-token driven); it emits the same `user:logout` event
tagged `method: "session"`, documented at the call site.

## Credential & access lifecycle events (ZAF-772)

The token / overlay / widget credential lifecycle and the per-resource access
grant/revoke are emit-worthy **credential** and **permission-structure** changes
(AGENTS.md §Audit Logging). All are `AuditScope::Account`, keyed to the acting
account with the actor recorded, and go through the shared account-scope helpers
so REST and GraphQL stay byte-for-byte in parity:

- REST - `crate::routes::audit::emit_account_audit(state, req, account_id, actor, event_type, metadata)`
- GraphQL - `crate::graphql::emit_account_audit(ctx, account_id, actor, event_type, metadata)`

Catalog constants (`db::audit::event_types`):

- **Popout tokens** - `account:popout_token_created` / `_updated` / `_deleted`
  (a soft-revoke via update carries `"revoked":true`; no separate revoke type).
  An update that sets or changes the token's user binding - including an unassign,
  which binds the editor - carries `"bound_user_id"` (opaque uuid), identically on
  GraphQL `updatePopoutToken` and REST `PATCH /v1/tokens/{id}` (ZAF-1922).
- **Account service keys** (`lm_svc_*`) - `account:service_key_created` /
  `_updated` (label rename) / `_revoked` / `_rotated`. Emitted by GraphQL
  `createAccountServiceKey` / `updateAccountServiceKey` /
  `deleteAccountServiceKey` / `rotateAccountServiceKey` and REST `POST` / `PATCH`
  / `DELETE /v1/service-keys` / `POST /v1/service-keys/{id}/rotate` (protocol
  parity). Account-scoped (the key is a tenant credential, unlike the personal
  `user:api_key_*` events); the actor is the member who performed the action.
  Metadata carries only `service_key_id` and the short, non-secret `lm_svc_*`
  prefix - `key_prefix`, or `old_key_prefix` + `new_key_prefix` on `_rotated`
  (which regenerates the secret in place and returns the new full key once) —
  never the full key or its hash.
- **Overlay access tokens** - `account:overlay_token_rotated` / `_revoked`.
- **Shared-overlay links** (`lm_share_*`) - `account:shared_link_created` /
  `_revoked` / `_extended` (extending credential validity is a security-relevant
  lifecycle change).
- **Widget access tokens** - `account:widget_token_created` (create + duplicate)
  / `_rotated` / `_revoked`.
- **Per-resource access** - `account:overlay_access_granted` / `_revoked` and
  `account:widget_access_granted` / `_revoked`. Grant is an upsert: the resulting
  `role` in metadata covers both first-grant and role-change (no pre-read, no
  separate `*_changed` type).
- **History report share links** (`lm_share_*`, ZAF-780) —
  `account:history_shared_link_created` / `_extended` / `_revoked`. The same
  `lm_share_*` credential lifecycle as the overlay share link, keyed to a history
  session/report instead of an overlay (create/revoke carry the `lm_share_*`
  `token_prefix`, extend carries the new expiry). Metadata is the non-secret
  `session_id` / `link_id` (+ `expires_at` / `token_prefix`) and the effective
  non-secret `options` (legacy links use `{legacy: true, include_revenue: false}`) - never the token
  string/hash or the argon2 `password_hash`.
- **History revenue assumptions** - `account:history_revenue_settings_updated`, emitted only for a real change by GraphQL `updateChannelHistoryRevenueSettings` or REST `PUT /v1/history/revenue-settings`. Scope is `account`, actor is the writing user, and metadata is `{"changed_fields": ["field", ...]}` (sorted). Scalar settings, including the three YouTube creator shares and Kick/YouTube ad assumptions, are listed by name; any added, removed or repriced YouTube membership level adds `youtube_member_levels` (level names are matched ignoring case; reordering alone is no change). The values, level names and prices are left out because the assumptions are gated behind `history:revenue-read` while the audit log is readable with `audit-log:read`. A read or unchanged write emits nothing. Fixed USD platform values are not editable and do not appear in the event.
- **History session erasure** (ZAF-780) - `account:history_session_deleted`, a
  destructive **GDPR Art. 17** deletion of a stored stream session and its data
  (`history:delete`). Metadata is the `session_id` only. Kept distinct from the
  chat-PII (`chat_pii_erasure`) and YouTube-member (`youtube_member_erasure`)
  erasure events, which erase different subject data on different surfaces.
  Those two carry a count per erased table in `metadata`
  (`deleted_message_count`, `deleted_event_count`,
  `deleted_platform_user_count`, `deleted_user_note_count`,
  `deleted_moderation_log_count` — whichever tables the path reaches; ZAF-2181;
  on the subject path `deleted_moderation_log_count` counts the non-AutoMod
  rows next to `deleted_automod_moderation_log_count`, so no row is counted
  twice, ZAF-2566),
  so an erasure is provable after the fact. The instructed subject erasures
  (`erase_chat_subject`, the YouTube member erasure) act in one instructing
  account only and write exactly **one** `AuditScope::System` row per request
  (`account_id` column null; `metadata.target = "account"`,
  `metadata.account_id` = target account, plus `case_id`,
  `instruction_reference`, `initiated_by` (`channel` | `subject`), `subject_kind`,
  `platform` and the counts; the instructed subject erasure also `reason`) -
  never the subject's platform user
  id, member channel id, Lumio user id, login or name, and no per-account rows.
  The Lumio-only erasure (`erase_chat_subject_at_lumio`) writes one
  `chat_pii_erasure` System row with `metadata.target = "lumio"`,
  `instruction_reference` and `reason`, and no account.
  The record erasure (`record_erasure::erase_record`) writes one System row per
  erased record with `metadata.target = "record"`, `record_kind`, `record_id`,
  the target `account_id`, `case_id`, `instruction_reference`, `reason` and its
  counts, and none for a record that was not found;
  see [Audit Log › Event types](../admin/audit-log.md#chat_pii_erasure).
- **Setting-preset account sharing** (ZAF-1287 / ZAF-622 §19) -
  `account:setting_preset_shared` / `account:setting_preset_unshared`. Sharing a
  personal preset with an account makes the owner's saved *view* (whose payload
  can hold viewer names) visible to every member, so it is a tenant-visible
  disclosure gated `presets:share`. Both are `account`-scoped: shared is keyed to
  the account it is shared **into**; un-shared is keyed to the account it **was**
  shared into (fires only when a share was actually removed). Reachable on both
  GraphQL (`shareSettingPreset` / `unshareSettingPreset`) and REST
  (`POST` / `DELETE /v1/setting-presets/{id}/share`) → identical type/scope/metadata.
  Metadata is the non-secret `preset_id`, `kind` (`chat` | `events` | `music`) and
  `name` - **never** the preset payload.

**No-secret rule (compliance-critical).** Metadata carries only non-secret
identifiers - `token_id`, resource ids (`overlay_id` / `widget_id` / `link_id` /
`session_id`), `target_user_id`, `role`, `expires_at`, flags - plus the short,
non-secret `lm_*` **`token_prefix`** where the row exposes one. It **never**
carries a full token string, `token_hash`, AES material, an argon2
`password_hash` (history share links carry one), or raw PII. The widget
rotate/revoke DB helpers surface only the token string (never logged), so those
rows carry `widget_id` only - the helper signatures are deliberately not widened.
The `apps/api/tests/audit_emitters.rs::zaf749_token_metadata_excludes_secrets`
and `::zaf780_history_metadata_excludes_secrets` regression guards fail if any
`lm_…` value leaks outside `token_prefix` (or a `password`/secret key appears).

The **platform-operator account delete** (`DELETE /v1/admin/accounts/{id}` /
`adminDeleteAccount`) emits `system:account_deleted` (`AuditScope::System`, no
tenant `account_id`, operator as actor, deleted account id,
`deleted_history_row_count`, `deleted_object_count` and `pending_object_count`
in metadata, identical on both twins) - the
CASCADE leaves no account member to read an account-scoped row, and audit rows
live in a separate TimescaleDB the CASCADE does not erase. Owner self-service
dissolve stays `account:dissolved` (Account scope) - the two are distinct events
so exactly one emitter fires per path.

The **orphaned extension upload sweep** (`POST /v1/admin/storage/orphaned-extension-uploads/sweep` /
`adminSweepOrphanedExtensionUploads`, gated by `admin:privacy-erase`) emits
`system:orphaned_storage_swept` (`AuditScope::System`, operator as actor) only
when `apply` is set - the dry run is a read and records nothing. Metadata carries
`kind` (`extension_uploads`), `orphaned_object_count` and `queued_object_count`.

The **automatic refund of an undeliverable checkout** (`services::purchase_refund::refund_undeliverable`,
called from the Stripe `checkout.session.completed` webhook for `CheckoutInstall::Detached` and
`CheckoutInstall::NotInstallable`) emits `extension:purchase_auto_refunded` (`AuditScope::System`,
no actor, `account_id = null`) once Stripe accepted the refund. A refused or failed refund writes
nothing and is logged with `error!`. Metadata: `purchase_id`, `cause` (`detached` |
`not_installable`), `amount`, `currency` and `stripe_refund_id`, never buyer data. The domain is
`extension:` (subject domain, like `privacy:`), not `system:`. The webhook is the only path: no
GraphQL or REST mutation refunds a purchase. The emitter calls Stripe, so it has no DB test; the
ledger side (`charge.refunded` on a detached row) is covered by
`apps/api/tests/zaf2717_checkout_after_extension_delete.rs`.

The **chatter objection path** (GDPR Art. 21, `services::chat_privacy::add_chatter_objection`
/ `remove_chatter_objection`, shared by `POST` / `DELETE /v1/admin/privacy/chat/objections…`
and GraphQL `addChatterObjection` / `removeChatterObjection`) emits
`privacy:chatter_objection_added` / `privacy:chatter_objection_removed`
(`AuditScope::System`, operator as actor) through `db::audit::emit`. The emit
lives in the service, so both protocols write the same type, scope and metadata:
`platform`, `reason` (`objection`) and `already_erased` - never the platform
user id or login, which are personal data. The domain is `privacy:` (subject
domain, like `crawler:*`), not `system:`. The objection writes the global
`chatter_suppressions` list, which acts on Lumio Stats only. Adding a chatter to
the account's `account_chatter_suppressions` list as part of an instructed
erasure emits no second event: the `chat_pii_erasure` /
`youtube_member_erasure` row carries `suppressed: true`. Covered by
`apps/api/tests/audit_emitters.rs::chatter_objection_emitters_are_system_scoped_without_identifiers`.

The **withdrawal of a channel erasure** (`services::chat_privacy::withdraw_channel_suppression`,
shared by `POST /v1/admin/privacy/chat/erase/withdraw` and GraphQL
`withdrawChannelChatterSuppression`) emits `privacy:channel_suppression_withdrawn`
(`AuditScope::System`, operator as actor, `account_id = null`) through the same
service-level emit, only after the row is deleted: a refused withdrawal (404, or
409 for an erasure the person asked for) writes nothing. Metadata: `target` (`account`),
`account_id`, `instruction_reference` and `platform` - like the
`chat_pii_erasure` row it undoes in part, never the platform user id or login.
Covered by `apps/api/tests/chatter_suppressions.rs::withdrawal_lifts_only_that_channels_suppression`
and `::withdrawal_refuses_a_subject_initiated_erasure`.

The **account permission-override** set/remove (`PUT` /
`DELETE /v1/admin/accounts/{id}/permission-overrides` /
`adminSetAccountPermissionOverride` / `adminRemoveAccountPermissionOverride`,
gated by `accounts:overrides-edit`) emit
`system:account_permission_override_set` / `_removed` (`AuditScope::System`,
operator as actor, no tenant `account_id`) via the same `emit_system_audit`
helper the feature-override path uses. A platform operator granting/revoking an
account-scoped permission override is a cross-account operator action on the
escalation surface hardened in ZAF-748 (only registry-known, non-wildcard
permissions are accepted), so it belongs on the operator log. The target
`account_id` and `permission` ride in metadata - the `set` path also records
`granted` and the operator's optional `reason`; never a secret. Remove emits only
when a row was actually removed. This is the account-level sibling of the
per-user `system:user_permission_override_set` / `_removed` events.

## Discord server events (ZAF-2152)

The global Lumio Discord bot joins servers through a verified invite (see
[Bot control](../features/bot-control.md)). All four events are
`AuditScope::Account`, keyed to the server's account, and written by the shared
service `services::discord_guild_install`, so every path records the same shape.
Metadata: `guild_id`, `guild_name`, and `reason: "taken_over"` on a takeover -
**never** the user token of the invite (it is revoked right after the exchange).

- `account:discord_guild_connected` - verified invite of a new server; actor =
  the inviting member. Written on the unified OAuth exchange
  (`POST /v1/connections/oauth/discord/exchange`), which is **REST-only** like
  every bot exchange (the browser callback calls it; there is no GraphQL twin).
- `account:discord_guild_reconnected` - the same account invites a server it
  already has (after the bot was removed, or to grant missing permissions);
  settings stay. Same REST-only exchange.
- `account:discord_guild_disconnected` - `disconnectDiscordGuild` (GraphQL) and
  `DELETE /v1/discord-guilds/{guild_id}` (REST), gate `bot-connections:delete`,
  full parity; only on a real removal. On a takeover the **previous** account
  gets this event too, with no actor - the new tenant's user is never written
  into another tenant's log.
- `account:discord_guild_bot_removed` - the bot was removed from the server on
  Discord's side. Written by the bot's system-key mutation
  `removeDiscordGuildByBot` (bot-fleet path, no REST twin), no actor. The row is
  marked, not deleted.

An operator deleting a server connection (`adminDeleteDiscordGuild` /
`DELETE /v1/admin/discord-guilds/{guild_id}`) writes the existing
`system:account_bot_connection_deleted` (System scope, metadata
`target_account_id`, `platform: "discord"`, `guild_id`) on both protocols.

## Credential & operator-RBAC events (ZAF-886)

These close the ZAF-880 finding #1 gap: credential- and permission-structure
tables that lived next to already-audited ones but emitted nothing. Each fires
on **both** protocols through the scope-appropriate shared helper.

- **Per-account app credentials** - `account:connection_credentials_upserted`
  (`AuditScope::Account`, gate `connections:create`). `save_credentials` /
  `saveAppCredentials` write AES-256-GCM `client_id`/`client_secret` into
  `app_credentials`; this is the **credential** level, distinct from the
  **token** level `account:connection_added`. Metadata: `platform`,
  `credentials_id` (row id), `updated` (insert vs update) - **never** the
  `client_id`/`client_secret` (plain or ciphertext). The DELETE counterpart is
  `account:connection_credentials_deleted` (ZAF-981, gate `connections:delete`):
  `delete_credentials` / `deleteAppCredentials` remove the row and, on the same
  path, tear down the associated channel connection - so that path emits **both**
  `account:connection_removed` (when a connection row was removed) and
  `account:connection_credentials_deleted` (when a credential row was removed),
  each fail-closed on a real removal, with full REST↔GraphQL parity. The deleted
  row leaves no id, so its metadata is `platform` only.
- **Integrations (Shopify)** - `account:integration_connected` /
  `account:integration_disconnected` / `account:shopify_settings_updated`
  (`AuditScope::Account`, ZAF-2932, ZAF-2988). All three are written in
  `services::shopify`, which the GraphQL and REST twins and the embedded
  routes (`/v1/shopify/embedded/*`) call, so every surface emits the same
  shape. Connected: when a link completes (`POST
  /v1/shopify/embedded/link/complete`); actor = the Lumio user who confirmed
  it (`shopifyLinkConfirm` / `POST /v1/connections/shopify/link/confirm`);
  metadata `platform`, `shop_host`, `scopes`, `source` (`shopify_admin`),
  `shopify_user_id` (the Shopify staff member's `sub`). A token re-exchange of
  an existing link emits nothing. Disconnected: actor = the member
  (`disconnectShopify` / `DELETE /v1/connections/shopify`), or none from the
  embedded app (`POST /v1/shopify/embedded/disconnect`, + `shopify_user_id`) or
  for Shopify's `app/uninstalled` webhook; metadata `platform`, `shop_host`,
  `reason` (`user` / `shopify_admin` / `app_uninstalled`). Emitted only when a
  row was really removed. Settings updated: one event per changed value
  (`customer_display`, `show_items`, `show_price`; ZAF-2989), none when
  nothing changed; actor = the Lumio user (`updateShopifySettings` / `PUT
  /v1/connections/shopify/settings`, `source: lumio`) or none from the
  embedded app (`PUT /v1/shopify/embedded/settings`, `source: shopify_admin`
  + `shopify_user_id`); metadata `platform`, `shop_host`, `setting`, `from`,
  `to`, `source`. Never a token or a buyer name.
- **Shopify buyer name hidden** - `account:shopify_order_name_hidden`
  (`AuditScope::Account`, ZAF-2989). Written by
  `services::shopify::hide_order_name`, which `hideShopifyOrderName` and
  `POST /v1/connections/shopify/events/{event_id}/hide-name` both call; actor =
  the member (`events:edit`). Emitted only when a stored label was removed (a
  repeat hide emits nothing). Metadata `platform`, `event_id`; never the name.
- **Shopify compliance webhooks** - `account:shopify_data_request`,
  `account:shopify_customer_redacted`, `account:shopify_shop_redacted`
  (`AuditScope::Account`, ZAF-2933). Written by the compliance worker
  (`services::shopify_compliance`), once per account that holds or held the
  store, with no actor: Shopify sent the request. REST-only by nature (Shopify
  calls `POST /v1/webhooks/shopify/compliance`; no client surface, so no
  GraphQL twin). Data request: on its single pass, metadata `platform`,
  `shop_host`, `orders_requested`, `orders_found`, `orders_with_label`.
  Redactions: only on the completing pass after the 72 h dead-letter window,
  metadata `platform`, `shop_host` (+ `orders`, a count, for
  `customers/redact`). Counts only: never a customer label, order id or
  customer contact.
- **Developer OAuth clients** - `oauth_client:created` / `_updated` / `_deleted`
  (`AuditScope::System`, gate `oauth-clients:{create,edit,delete}`). Metadata:
  `client_id_ref` (the DB row id, **not** the OAuth `client_id` string), `name`,
  `redirect_uris`, `scopes`, and (update) `changed_fields` - never the OAuth
  `client_id` string or `client_secret`.
- **Operator admin roles** - `admin_role:created` / `_updated` / `_deleted` /
  `_assigned` / `_unassigned` (`AuditScope::System`, gate
  `admin-roles:{create,edit,delete}`). The `admin_roles` table is **separate**
  from `user_roles` (whose `system:user_role_*` events already emit). Metadata:
  `role_id`, `role_name`, `permissions` (the granted `resource:action` list —
  auditing the grant is the point), `changed_fields` (update); assign/unassign
  add `target_user_id`. Assign emits only on a real (non-idempotent) assignment;
  unassign/delete only when a row was actually removed.
- **Global bot connections** - `system:global_bot_connection_upserted` / `_deleted`
  (`AuditScope::System`, gate `bot-connections:{create,delete}`). The nil-UUID
  global bot token, written by `exchange_global_bot_oauth` and the unified
  `GlobalBot` exchange. Metadata: `platform`, `connection_id`, `bot_username`
  (public handle), `source` (`oauth_exchange`) - **never** the access/refresh
  token. The upsert emit is a documented single-protocol (REST) emit. Discord
  has no global bot connection: its bot token is bot configuration
  (`DISCORD_BOT__BOT__TOKEN`).
- **Operator identity destruction** - `system:user_deleted` (gate `users:delete`)
  and `system:user_login_connection_deleted` (`AuditScope::System`). The
  login-identity removal has full REST↔GraphQL parity —
  `admin_delete_user_login_connection` (GraphQL) and
  `DELETE /v1/admin/users/{id}/login-connections/{provider}`
  (`routes::admin::admin_delete_login_connection`, gate `users:edit`) emit the
  same event. Both emit only on a real deletion. Metadata: `target_user_id`, plus
  `provider` for the login-connection case - never email/handle/tokens.
- **Login-identity routing** - `account:login_connection_assigned`
  (`AuditScope::Account`, `assign_login_connection` on both protocols, gate
  `login-assignments:create` on the cross-user path; metadata `provider` +
  `target_user_id` + `connection_id`). Assigning a login decides which identity
  the account acts as on that platform, so it is exactly as security-relevant as
  taking it away - the two are a pair, and an audit log that only recorded the
  removal told half the story.
- **Login-identity removal** - `account:login_connection_removed`
  (`AuditScope::Account`, `remove_login_assignment`, gate
  `login-assignments:delete`; metadata `provider` + `target_user_id`) and
  `user:login_connection_removed` (`AuditScope::User`, self-service
  `delete_login_connection` / `disconnectLoginConnection`, first-party-gated
  ZAF-469; metadata `provider` + `connection_id`). The self-service removal is a
  **personal** security event (User scope, self-only read); the account-member
  removal belongs to the **tenant** log. Both emit only on a real removal.

`user:oauth_granted` is **not** emitted by the in-API `link_provider` route - it
is emitted by **apps/id** on provider link/consent via the server-to-server
ingest endpoint (see [Events that originate outside the API](#events-that-originate-outside-the-api-appsid-ingest)).
Wiring a second emit in-API would double-count the same grant.

**No-secret rule.** As everywhere else, metadata carries only non-secret ids and
public handles. The credential/token writers (`account:connection_credentials_upserted`,
`oauth_client:*`, `system:global_bot_connection_upserted`) are guarded by
`apps/api/tests/audit_emitters.rs::zaf886_credential_metadata_excludes_secrets`,
which fails if a `client_id`/`client_secret`/token key or a secret-shaped value
(`lms_…`, `cli_…`) appears in any stored metadata row.

## YouTube Analytics connection and deletion audit

The channel OAuth exchange writes the existing account-scoped `account:connection_added` event on every first connect and reconnect. For YouTube, `db::audit::connection_event_metadata` includes `platform`, `credential_source` and `optional_scopes_granted`: the optional scope names in the actual Google grant. `[]` means no optional scope was granted; platforms without optional channel scopes omit the key. Never put the token, the full grant or a revenue amount in this metadata.

`account:youtube_revenue_data_deleted` is account-scoped and emitted through `db::audit::emit` only when at least one stored YouTube Analytics revenue row is deleted. `user_id` is the initiating user when known and absent for worker cleanup. Metadata is `{ "platform": "youtube", "reason": "scope_removed", "rows": 12 }`, where `rows` counts deleted records, not money. The reason is one of `disconnected`, `scope_removed`, `revoked`, `auth_unconfirmed_30d`, `video_deleted`, `account_deleted`, or `report_deleted`. Connection deletion paths on both GraphQL and REST call the same YouTube revenue cleanup service before deleting the connection; the worker also uses that service for scope, authorization and video checks. `deleteChannelHistory` and `DELETE /v1/history/reports/{id}` share `services::history::service::delete_session`, which deletes the revenue rows of the report's videos (`report_deleted`, actor = the deleting user) unless another report of the account still shows the same video. See [Audit Log](../features/audit-log.md).

## Personal API-key lifecycle events (ZAF-498)

A **user API key** (`lm_usr_*`) is a personal, self-only programmatic credential
a member creates in the dashboard (rows in `api_keys` with `is_system = false`,
bound to one `user_id` + `account_id`). Its create/revoke are therefore
**`AuditScope::User`** personal-security events, not account-scoped - they land in
the owner's self-only log with `account_id = NULL`, exactly like the login events.
They go through dedicated user-scope helpers that mirror the account-scope ones:

- REST - `crate::routes::audit::emit_user_audit(state, req, user_id, event_type, metadata)`
- GraphQL - `crate::graphql::emit_user_audit(ctx, user_id, event_type, metadata)`

Catalog constants (`db::audit::event_types`):

- **`user:api_key_created`** - a new key is minted. Emitted by GraphQL
  `createUserApiKey` and REST `POST /v1/api-keys` (protocol parity).
- **`user:api_key_updated`** - a key is renamed (label only). Emitted by GraphQL
  `updateUserApiKey` and REST `PATCH /v1/api-keys/{id}` (protocol parity).
- **`user:api_key_revoked`** - a key is deleted. Emitted by GraphQL
  `deleteUserApiKey` and REST `DELETE /v1/api-keys/{id}`; the revoke paths
  pre-read the key so the row can carry its prefix, and a missing/foreign key
  collapses to the same not-found before any row is written.
- **`user:api_key_rotated`** - the owner regenerated a key's secret in place
  (id, label and scopes unchanged; old secret invalidated immediately, new full
  key returned once). Emitted by GraphQL `rotateUserApiKey` and REST
  `POST /v1/api-keys/{id}/rotate` (protocol parity); the rotate paths pre-read the
  key so the row can carry the old prefix. Metadata adds `old_key_prefix` +
  `new_key_prefix` alongside `api_key_id`.

Per the **no-secret rule**, metadata carries only `api_key_id` and the short,
non-secret `lm_usr_*` prefixes (`key_prefix`, or `old_key_prefix` /
`new_key_prefix` on rotate) - never the full key or its `key_hash`. Both
emit sites are best-effort side-channels that never fail the mutation.

## Developer verification submission (ZAF-943)

`developer:verification_submitted` (`AuditScope::User`) fires when an approved
developer submits (or resubmits) their **own** KYC identity/company verification
via `submitDeveloperVerification` (GraphQL) or `POST /v1/developer/verification`
(REST). This is a personal identity/credential action on the developer's own
identity, so it is **User**-scoped (self-only read via `myAuditLog`) with the
acting developer as `user_id` and no tenant `account_id`. The event name follows
the subject-domain precedent (`oauth_client:*`, `admin_role:*`). Both protocols
emit the same event type, scope and metadata (parity).

- **Metadata:** `verification_id`, `developer_id`, `developer_type`
  (`individual` | `company`, inferred from whether a company name was given),
  `status`, and `resubmission` (whether a prior record existed) - **never** the
  submitted legal name, company name, address, tax id, trade-register id, or
  document key (all raw PII/KYC material).
- **Reads do not emit.** `developerVerificationStatus` / `GET /v1/developer/verification`
  are reads and write no audit row.

## Developer balance released on deletion (ZAF-2831)

- `developer:funds_deletion_released` (`AuditScope::System`, `user_id` = the
  operator) fires when an operator releases an unpayable developer balance as a
  liability and deletes (`adminReleaseFundsAndDeleteUser` /
  `adminReleaseFundsAndDeleteDeveloper` + `POST /v1/admin/{users,developers}/{id}/release-funds-delete`).
  Metadata `released_balance_id`, `amount`, `currency`, `release_case`, built by
  `services::developer_funds_release::audit_metadata` for both protocols — never
  the claim code, the reason, the request reference, or the deleted person's id
  or e-mail. Emitted after the commit, only when a balance was released; the
  delete itself still writes `system:user_deleted` / `system:developer_deleted`.

## Released developer balance settled (ZAF-2836)

- `developer:funds_released_claim_started` (`AuditScope::System`, `user_id` =
  the operator) fires when an operator records that a person presented the
  claim code (`adminStartReleasedBalanceClaim` +
  `POST /v1/admin/released-balances/claim`), only for the call that sets
  `claim_started_at`; a repeat writes nothing. Metadata `released_balance_id`,
  `amount`, `currency`, built by
  `services::developer_funds_settlement::claim_audit_metadata`.
- `developer:funds_released_settled` (`AuditScope::System`, `user_id` = the
  operator) fires when an operator credits the released balance to the
  person's new, verified developer profile (`adminSettleReleasedBalance` +
  `POST /v1/admin/released-balances/settle`). Metadata `released_balance_id`,
  `developer_id` (the new profile), `amount`, `currency`, built by
  `services::developer_funds_settlement::settlement_audit_metadata`.
- Neither carries the claim code. Both are emitted after the commit, on both
  protocols, by the same helpers.

## Developer tax details and credit notes (ZAF-2807)

- `developer:tax_details_updated` (`AuditScope::User`) fires when a developer sets
  the tax details of their own verification (`updateDeveloperTaxDetails` /
  `PUT /v1/developer/verification/tax-details`). Metadata `verification_id`,
  `developer_id`, `has_tax_number`, `has_vat_id`, `small_business_declared` -
  never the Steuernummer or USt-IdNr. themselves. Both protocols share
  `routes::developer_verifications::tax_details_audit_metadata`.
- `system:developer_credit_note_cancelled` (`AuditScope::System`) fires when an
  operator records a developer's objection to a self-billed credit note or
  corrects it (`cancelCreditNote` / `POST /v1/admin/credit-notes/{id}/cancel`,
  gate `billing:edit`). Metadata `credit_note_id`, `cancellation_id`,
  `cancellation_number`, `reason`, `developer_id`, `reissued_id`,
  `reissued_number`, built by `routes::developer_credit_notes::cancel_audit_metadata`
  for both protocols. The automatic cancellation of a failed payout is
  bookkeeping inside the payout failure (recorded by
  `system:developer_payout_failed`); the issue of a note is part of the payout
  and emits nothing either.

## Developer payouts (ZAF-1257)

Every money movement of a developer payout is recorded. All share
`services::developer_payouts::payout_audit_metadata` (`payout_id`,
`developer_id`, `method`, `amount`, `currency`, `status`, the masked
`payout_reference`, `stripe_transfer_id`, `paypal_batch_id`, `source`) and, on
failure, `failed_audit_metadata` (adds `refunded`, `cancellation_number`) -
never the payee snapshot, the full PayPal e-mail or the IBAN.

- `developer:payout_requested` (`AuditScope::User`, actor = the developer):
  `requestPayout` / `POST /v1/developer/payouts/request` (`source` `request` or
  `closing`) and the closing payout of `scheduleProfileDeletion` (`closing`).
- `system:developer_payout_scheduled` (`AuditScope::System`, no actor): the
  monthly step of the payout cycle (`workers::payout::schedule_monthly_payouts`).
- `system:developer_payout_sent` (`AuditScope::System`, no actor): the cycle
  handed the payout to Stripe (`completed`) or PayPal (`processing`).
- `system:developer_payout_completed` (`AuditScope::System`): an operator
  (`completeDeveloperPayout` / `POST /v1/admin/developer-payouts/{id}/complete`,
  `billing:edit`, actor = operator, `source` `operator`) or the PayPal payouts
  webhook (no actor, `source` `webhook`).
- `system:developer_payout_failed` (`AuditScope::System`): the provider refused
  the payout (`source` `cycle`, adds `provider_error`), an operator marked it
  failed (`failDeveloperPayout` / `…/fail`), or the PayPal webhook reported it.

The cycle and the webhook emit through `services::developer_payouts::emit_system`
(no request origin); the operator twins through `emit_system_audit` on each
protocol.

## Developer-team, extension-access, SE-token & admin single-site events (ZAF-1022)

Five modules with RBAC-gated mutations on both protocols shipped with **zero**
audit emitters (baseline sweep ZAF-1005 Befund 2); ZAF-1022 wires them, plus a
handful of admin single-sites. Scope is set **explicitly** per surface and never
inferred.

**Developer self-service team** (`developer:team_*`, `AuditScope::User`) - a
developer managing their **own** team. Consistent with the existing
`developer:verification_submitted`, these are personal-security events on the
acting developer's identity: `user_id` = the acting developer, **no** tenant
`account_id`, self-only read via `myAuditLog`. GraphQL (`graphql/developer_teams.rs`)
and REST (`routes/developer_teams.rs`) emit the same event/scope/metadata via the
shared `emit_user_audit` helpers. Types: `developer:team_created`,
`developer:team_deleted`, `developer:team_role_created` / `_updated` / `_deleted`,
`developer:team_member_role_changed`, `developer:team_member_removed`,
`developer:team_invite_created` / `_revoked` / `_accepted` / `_declined`. Metadata carries only
row/entity ids (`team_id`, `role_id`, `member_id`, `invite_id`, `target_user_id`),
`role_slug`, `permissions` (permission strings), and `changed_fields` (field
**names**) - **never** the invite `email` or `invite_code`/`code` (log the invite
**row id** instead), and never the team member's PII. The low-security team
**rename** is intentionally not audited (audit log ≠ analytics stream).

**Bell invite actions** share the same REST and GraphQL dispatcher. Accepting an account invite emits `account:invite_accepted` with the joining user as actor and the joined account as scope; its metadata includes `membership_id`, `invite_id`, `role_id`, and `source: "notification"`. Declining an existing account invite emits `account:invite_declined` with `invite_id`, `role_id`, and that source. An already-gone account invite produces no decline event.

Accepting a developer-team invite from the bell emits `developer:team_invite_accepted` with `team_id`, `invite_id`, `role_id`, `member_id`, and `source: "notification"` in User scope. Accepting by code emits the same type without that source. Declining an existing team invite emits `developer:team_invite_declined` in User scope with `team_id`, `invite_id`, `invite_deleted`, and `source: "notification"`; a missing invite produces no event. `invite_deleted` is true only when an unused single-use invite is removed. No invite event records an invite code or email.

**Developer extension visibility** (`developer:extension_visibility_changed`,
`AuditScope::User`) - a developer moving their extension between `private`,
`unlisted`, `public` and `paid`. Both protocols call the shared
`services::developer_extensions::emit_visibility_changed` after the update, so
event, scope and metadata (`extension_id`, `from`, `to`) are identical; nothing
is written when the value did not change. A developer key has no member identity:
its row has no `user_id` and names the key in `developer_key_id`.

**Developer extension secrets** (`developer:extension_secret_set`,
`developer:extension_secret_deleted`, `AuditScope::User`) - a developer setting or
deleting one of their extension's owner-scope secrets (credential surface). Both
protocols call `services::developer_extensions::emit_secret_changed`; metadata is
`extension_id` and the secret's **key name** (plus `developer_key_id` for a
developer key) - **never** the value or its ciphertext. A delete that removed no
row writes nothing. Reads (`ctx.secrets.get`, listing key names) are not audited.

> **Transparency tradeoff (§A.1, CTO-accepted).** Under User scope a member
> removal or role change done by a *non-owner* team admin lands in **that actor's**
> self-only log; it does not surface in a team-shared or operator log (no
> team-audit read surface exists in the product). This satisfies DSGVO Art. 5(2)
> accountability. A team-visible audit read would be a scope extension (a one-way
> door) - deferred until such a UI is scheduled.

**Extension access** (`account:extension_access_*`, `AuditScope::Account`) —
mirrors the `account:{overlay,widget}_access_*` families. GraphQL
(`graphql/extension_access.rs`) and REST (`routes/extension_access.rs`) emit via
`emit_account_audit` with the row `account_id` = the acting (extension-owner)
account and the target account in `metadata`. Types:
`account:extension_access_granted` / `_revoked` and
`account:extension_access_invite_created` / `_revoked` / `_accepted`. Metadata:
`extension_id`, `target_account_id`, `grant_type`, `grant_id`, `invite_id`,
`max_uses`, `expires_at` - **never** the invite `invite_code`/`code`.

**StreamElements tokens** (`account:se_token_*`, `AuditScope::Account`) - an
account-owned SE credential. GraphQL (`graphql/se_tokens.rs`) and REST
(`routes/se_tokens.rs`) emit `account:se_token_created` (upsert) and
`account:se_token_deleted`. Metadata: `token_id`, `platform`, `label` - **never**
the StreamElements JWT, its `encrypted_token` ciphertext, or the masked
`token_hint` (which still leaks 8 chars).

**OBS integration config** (`account:obs_config_*`, `AuditScope::Account`) -
the account's OBS WebSocket connection settings. GraphQL (`graphql/obs.rs`
`saveObsConfig` / `deleteObsConfig`) and REST (`routes/obs_integration.rs`
`PUT` / `DELETE /v1/integrations/obs`) emit `account:obs_config_saved` (upsert)
and `account:obs_config_deleted` (only when a stored config was removed; the
metadata then describes the removed config). Both build the metadata with
`services::obs_remote::obs_config_audit_metadata`: `mode` (`local` / `remote`),
`remote_host` (trimmed, `null` when empty), `port`, `has_password` - **never**
the OBS WebSocket password or its ciphertext.

**Operator developer-team administration** (`system:developer*`,
`AuditScope::System`) - platform-operator actions gated on `developer-*:edit`.
GraphQL (`graphql/admin_developer_teams.rs`) and REST
(`routes/admin_developer_teams.rs`) emit via a local `emit_system_audit`: the
acting operator is `user_id`, **no** tenant `account_id`, the target rides in
`metadata`. Types: `system:developer_deleted`, `system:developer_team_deleted`,
`system:developer_team_member_added` / `_removed` / `_role_changed`,
`system:developer_revenue_split_set`, `system:developer_limits_updated`, and
`system:developer_limit_request_reviewed`. `system:developer_limits_updated` is a
**single, merged** event for developer **and** extension limits, discriminated by
`limit_scope: "developer" | "extension"` in metadata. The limit-request review
metadata carries a `has_review_notes` presence flag only - **never** the free-text
`review_notes`.

**Admin single-sites** (`system:*`, `AuditScope::System`) - platform-operator
actions on user/account rows, distinct from the user-self events. GraphQL
(`graphql/admin.rs`) and REST (`routes/admin.rs`) emit:

- `system:user_email_changed` - operator changed a user's email via
  `admin_update_user` / `PATCH /v1/admin/users/{id}` (`patch_user`). Emitted
  **only when the stored email actually changed** (a display-name-only edit or a
  no-op re-submit writes nothing); metadata `target_user_id` + a
  `had_previous_email` flag - **never** the old/new address.
- `system:user_account_creation_override_set` - metadata `target_user_id` +
  `override` (`allow` | `deny` | `default`).
- `system:user_max_accounts_override_set` - **GraphQL-only**
  (`admin_update_user_max_accounts_override`); `patch_user` REST does not accept
  `max_accounts`, so a GraphQL-only emitter is correct parity. Metadata
  `target_user_id` + `max_accounts` (int | null).
- `system:account_connection_deleted` / `system:account_bot_connection_deleted` —
  operator deleted an account's channel / bot connection
  (`admin_delete_account_channel_connection` / `_bot_connection` +
  `DELETE /v1/admin/accounts/{id}/connections/{platform}` / `.../bot-connections/{platform}`).
  Metadata `target_account_id` + `platform`; emitted only on a real deletion.
- `system:account_login_connection_deleted` - **GraphQL-only**
  (`admin_delete_account_login_connection`, gate `accounts:edit`); no REST twin
  exists for the account-level login-connection delete (the REST
  `admin_delete_login_connection` targets a single user via the already-audited
  `system:user_login_connection_deleted`). Metadata `target_account_id` +
  `provider`; emitted only on a real deletion.
- `system:account_member_added` / `system:account_member_removed` - operator
  added a user to / removed a member from an account (`admin_add_account_member` /
  `admin_remove_account_member` + `POST /v1/admin/accounts/{id}/members` /
  `DELETE .../members/{user_id}`, gate `accounts:edit`). Metadata
  `target_account_id`, `target_user_id` (+ the effective `role_id` on add);
  add is emitted only on a real insert (re-adding an existing member is a
  no-op) and remove only on a real removal.
- `system:coupon_created` / `system:coupon_updated` / `system:coupon_deactivated` -
  operator coupon CRUD (`admin_{create,update,deactivate}_coupon` +
  `POST`/`PUT`/`DELETE /v1/admin/coupons[/{id}]`). Metadata `coupon_id` plus
  `discount_type` (create) or `changed_fields` (update; field names only, built by
  the shared `db::audit::coupon_changed_fields`) - **never** the redeemable `code`.
  Deactivate is emitted only on a real deactivation.
- `system:account_se_token_deleted` - operator deleted an account's
  StreamElements token (`admin_delete_se_token` +
  `DELETE /v1/admin/accounts/{id}/se-tokens/{token_id}`, gate `se-tokens:delete`).
  Metadata `target_account_id` + `token_id` - never the JWT, ciphertext or
  `token_hint`. The tenant self-service twin stays `account:se_token_deleted`.
- `system:developer_verification_approved` /
  `system:developer_verification_rejected` - operator KYC review
  (`graphql/developer_verifications.rs` + `routes/developer_verifications.rs`,
  gate `developer-verification:edit`). Metadata `verification_id`
  (+ `target_account_id` on approve) - never the free-text rejection `reason`.
- `system:extension_version_approved` / `system:extension_version_rejected` -
  operator extension review (`graphql/extension_reviews.rs` +
  `routes/extension_reviews.rs`, gate `extension-review:edit`). Metadata
  `version_id`, `extension_id` (+ `new_status` on approve) - never the review
  `notes` or `reason`.
- `system:user_extension_dev_mode_set` - operator toggled a user's extension dev
  mode (`set_extension_dev_mode` + `POST /v1/admin/users/{id}/extension-dev-mode`,
  gate `developer-limits:edit`). Metadata `target_user_id` + `enabled`.
- `system:account_limits_updated` - operator changed an account's numeric limit
  overrides (`account_limits`), including the setting-preset quota, via either
  write path: the full upsert (`adminUpsertAccountLimits` /
  `PUT /v1/admin/accounts/{id}/limits`) or the partial resolved-limits update
  (`adminSetAccountLimits` / `PUT /v1/admin/accounts/{id}/resolved-limits`), both
  gated `accounts:edit`. Metadata `account_id`, a `path` discriminator
  (`upsert` | `resolved`), and the numeric limit fields that were submitted
  (`max_setting_presets`, `max_overlays`, …) - **never** the free-text `notes`.
- `system:user_setting_preset_deleted` - operator deleted one of a user's setting
  presets (`adminDeleteUserSettingPreset` / `DELETE /v1/admin/setting-presets/{id}`,
  gate `users:edit`); emitted only on a real deletion. Metadata `target_user_id`,
  `preset_id`, and `kind` (`chat` | `events` | `music`) - **never** the preset
  payload (it can hold viewer names the user typed).

Per the **no-secret rule**, none of these payloads may carry a token, ciphertext,
`token_hint`, `invite_code`/`code`, OAuth `client_id`/`client_secret`, user email,
display name, or free-text `review_notes`. This is enforced by
`apps/api/tests/audit_emitters.rs::zaf1022_metadata_excludes_secrets_and_pii`, and
the User-scope isolation by
`audit_scoped_reads.rs::developer_team_events_are_user_scoped_and_isolated`.

## Copyright Manager moderation

Global safe and blocked song lists have no tenant `account_id`. REST
`approve_vote_candidate` / `dismiss_vote_candidate` and GraphQL `approveReport` /
`dismissReport` require the admin-scope `copyright:moderate` permission and emit
`copyright:moderation_approved` or `copyright:moderation_dismissed` after a
successful decision. Dismissal emits only when a report was actually dismissed.
Submitting or confirming a community report does not write a global list entry
or a moderation audit event.

Both protocol paths use `db::audit::copyright_moderation_metadata`. The event is
`AuditScope::System`, with the operator as `user_id` and a null tenant
`account_id`. Metadata contains `spotify_track_id`, `list` (`blocked`, `safe`, or
null), `source` (the list row's source, or null on dismissal), and `decision`
(`approved` or `dismissed`). It excludes song title, artist, and reporter
identity. The emit is best-effort and cannot fail the moderation action.

## Operator API-key management (ZAF-1174)

Platform operators can manage **any** account's or user's API keys from the admin
app - personal `lm_usr_*` keys (in `api_keys`) and account service `lm_svc_*` keys
(in `account_service_keys`) - gated on the admin-scope `account-apikeys:*` family
(`AdminPermissionGuard` / `require_admin_permission`). Each operator write is a
platform-operator action on someone else's credential, so it is **`AuditScope::System`**
with the **operator** as `user_id` (the actor) and **no** tenant `account_id`
column - the target ids ride in `metadata`. These rows never surface in the target
account's or the target user's own audit log. GraphQL (`graphql/admin.rs`) and REST
(`routes/admin.rs`) emit the same event/scope/metadata via the shared
`emit_system_audit` helper.

- **`system:api_key_updated`** - an operator edited a key's label + scopes
  (`adminUpdateApiKey` / `PATCH /v1/admin/api-keys/{kind}/{id}`). Metadata: `kind`
  (`personal` | `service`), `api_key_id`, target `account_id`, target `user_id`
  (personal only; `null` for service), and the resulting `permissions`.
- **`system:api_key_rotated`** - an operator regenerated a key's secret
  (`adminRotateApiKey` / `POST /v1/admin/api-keys/{kind}/{id}/rotate`). The new full
  key is returned to the operator exactly once and never stored/logged; metadata
  adds `old_key_prefix` + `new_key_prefix` to the same `kind` / `api_key_id` /
  `account_id` / `user_id` ids.
- **`system:api_key_revoked`** - an operator revoked (hard-deleted) a key
  (`adminDeleteApiKey` / `DELETE /v1/admin/api-keys/{kind}/{id}`). Idempotent - a
  missing key resolves to not-found. Metadata: `kind`, `api_key_id`, `account_id`,
  `user_id` (personal only).

Per the **no-secret rule**, metadata carries only ids and the short, non-secret
`lm_*` prefixes - never the full key, its hash, or PII. These are the operator
siblings of the owner-self `user:api_key_*` (personal) and `account:service_key_*`
(service) events: exactly one emitter fires per path, and an operator action is
never mirrored into the target's personal/account log.

## Extension kill switch (ZAF-1919)

`account:extension_kill_switch_set` (`AuditScope::Account`) is written by
`services::extension_kill_switch::set_kill_switch`, the one path behind REST
`POST /v1/bot-modules/kill` and GraphQL `setBotModuleKillSwitch` (both
`bot-modules:edit`, own account only). The actor is `user_id`; metadata is
`{ "killed": bool }`. The state is persisted in `account_extension_kill_switch`
and the row is written **before** the live pub/sub push, so a failed publish
still leaves the change audited. Covered by
`audit_emitters.rs::extension_kill_switch_emits_account_scoped_row`.

## Extension uninstall (ZAF-2407)

`account:extension_uninstalled` (`AuditScope::Account`) is written by
`db::extension_uninstall::emit_uninstalled`, which REST
`DELETE /v1/extension-installs/{id}` and GraphQL `uninstallExtension` (both
`extension-store:uninstall`) call after `execute_uninstall_cascade` succeeded.
The actor is `user_id`; metadata is
`{ "extension_id", "install_id", "delete_data_immediately": bool }`. Deleting
the data immediately is irreversible and removes only the account's rows from
the extension's shared `ext_{extension_id}` schema (the schema goes with the
last install). Covered by
`zaf2407_extension_data_per_account_purge.rs::graphql_immediate_uninstall_purges_per_account_and_audits`.

## Contract declarations

`services::contract_declarations` emits on a newly stored declaration, before Stripe work. A repeated `client_request_id` for the same declaration returns the existing row and emits no second declaration event; one reused for a different declaration is refused (`IDEMPOTENCY_KEY_REUSED`) and emits nothing. Public `billing:withdrawal_declared` and `billing:cancellation_declared` have `AuditScope::System` and no user actor. A signed-in withdrawal uses `AuditScope::Account` when an active account exists, or `AuditScope::User` otherwise. Plan and extension subscription cancellations emit `account:subscription_cancel_requested` and `extension:subscription_cancel_requested` in account scope; metadata includes the declaration ID and non-secret contract identifiers and terms, not the free-text reason.

The admin close path emits `billing:withdrawal_processed` or `billing:cancellation_processed` with `AuditScope::System`, operator actor, case ID and result (`processed` or `rejected`). Matching and legal-hold extension emit `billing:declaration_matched` and `billing:declaration_retention_extended`, also in system scope. GraphQL and REST call the same service and therefore emit the same event and metadata. Receipt sending and list reads do not emit audit rows.

## Withdrawal-waiver declaration (ZAF-2690)

`billing:withdrawal_waiver_accepted` (`AuditScope::Account`) is written by
`services::withdrawal_waiver::record`, which both Stripe checkout webhooks call
once the account is known: `routes/billing.rs::handle_checkout_completed`
(plans) and `routes/webhooks_payments.rs::handle_checkout_completed` (extension
purchases). It fires only when the proof row in `withdrawal_waiver_consents`
was inserted, so a webhook redelivery of the same session emits nothing. The
actor `user_id` is the buyer from the session metadata; there is no client
request, so IP, user agent and GeoIP are empty. Metadata:
`{ "kind", "text_version", "accepted_at", "checkout_session_id", "plan_id" | "extension_id" }`.
The plan checkout exists on REST and GraphQL, the extension purchase on REST
only; the event comes from the shared webhook path either way. Covered by
`audit_emitters.rs::withdrawal_waiver_emits_account_scoped_row_once`.

## Account bot and keyword list events

`account:bot_list_updated` and `account:history_keywords_updated` are account-scoped list-change events. GraphQL and REST use the same service outcomes and account audit helpers, so both protocols emit the same metadata only when a row actually changes. Reads, keyword pattern tests, duplicate bot/keyword adds and no-op removals emit nothing.

| Event | Writers | Metadata |
|-------|---------|----------|
| `account:bot_list_updated` | `addAccountBot` / `removeAccountBot`; `POST` / `DELETE /v1/account-bots` | `action` (`added`/`removed`), `platform`, `platform_user_id`, `display_name`, `source` |
| `account:history_keywords_updated` | `addHistoryKeyword` / `updateHistoryKeyword` / `removeHistoryKeyword`; `POST` / `PUT` / `DELETE /v1/history/keywords` | `action` (`added`/`changed`/`removed`), `keyword_id`, `keyword`, `match`, `case_insensitive` |

The actor is the calling user when one exists. The keyword text and bot display name are visible to members with `audit-log:read`; neither event records a chat message, token or credential.

## Read-time UUID → name resolution (ZAF-1233)

Audit rows store **ids**, never names - denormalizing a display name into
`metadata` at write time is forbidden (every account member with `audit-log:read`
can read `metadata`, and the name would go stale). Instead the read surfaces
resolve the ids to display names **at read time, once per page**, so the UI can
show "name (uuid)" for every entity a page references - not just the actor.

- **Resolver:** `db::audit::resolve_referenced_names(primary_pool, &rows)`. It
  scans the page's rows for the actor (`user_id`) plus a fixed metadata **key
  allowlist**, collects the distinct ids per entity kind, and runs **one**
  `WHERE id = ANY($1)` query per kind - never N+1. `audit_events` lives in
  TimescaleDB, but the named entities live in **primary Postgres**, so the
  resolver takes the primary pool (`state.db` / `ctx.data::<PgPool>()`), not
  `state.tsdb`.
- **Kinds & columns:** `user` → `users.display_name`, `account` → `accounts.name`
  (the human-facing account name the admin surfaces already render), `role` →
  `account_roles.name`.
- **Allowlist:** actor `user_id`, plus metadata keys `target_user_id` / `member_id`
  (user), `from_account_id` / `to_account_id` / `target_account_id` (account), and
  `role_id` (account role). Other metadata ids are **not** resolved. `role_id`
  also appears on the `system:user_role_*`, `admin_role:*` and developer-team
  events, which reference *other* role tables; those simply miss here and fall
  back to the raw UUID.
- **Misses are omitted.** There is no FK from the retained audit row to these
  tables - a user/account can be CASCADE-deleted while the audit row is
  deliberately kept - so a lookup that finds nothing means "deleted/unknown"; the
  id stays on the wire and the client renders the raw UUID (plus a "deleted"
  label). Resolution is also **fail-open**: a resolver query error logs and yields
  an empty map (via `resolve_referenced_names_lenient`) rather than blanking the
  audit page.
- **Wire shape (all three surfaces, GraphQL + REST):** each event carries a
  `resolved_names` list of `{ id, kind, display_name }` (`resolvedNames` in
  GraphQL) for exactly the entities that event references, de-duplicated. Present
  and identical on GraphQL `AuditEvent` + `AdminAuditEvent` and REST
  `AuditEventResponse`. The raw UUIDs are **never** removed - `resolved_names` is
  additive enrichment.

Consequently, when you add an emit site whose `metadata` should render a name,
use one of the allowlisted keys above so the read surfaces resolve it for free.

## Parity and tests

- **Protocol parity applies.** An action reachable on both GraphQL and REST emits
  the same event type, scope and metadata shape on both. A one-sided emitter is a
  bug. Where a path exists on only one protocol (for example the OAuth
  browser-redirect callback, which is REST-only), document why at the call site.
- **Cover the emitter** in `apps/api/tests/audit_emitters.rs`: the row lands with
  the expected scope, account, actor and metadata.
- **Cover the isolation** in `apps/api/tests/audit_scoped_reads.rs`: a new scope
  or reader needs a fail-closed negative test proving foreign rows stay invisible.

## Adding a new event type - checklist

1. Add the `event_types::*` constant with a `domain:action` name matching its scope.
2. Emit it via `db::audit::emit` at every protocol that can trigger the action.
3. Set `scope` explicitly; put the target in `metadata`; keep secrets out.
4. Add an emitter test and, for a new scope or reader, an isolation test.
5. Document the event in [Audit Log](../features/audit-log.md) (and
   [Admin · Audit Log](../admin/audit-log.md) if operators see it).
6. Add the type to the admin catalog mirror in
   `apps/admin/src/app/(admin)/audit-log/event-types.ts` and its
   `auditLog.eventTypes` labels in `apps/admin/messages/en.json` and
   `apps/admin/messages/de.json`. The catalog parity test
   (`apps/admin/__tests__/audit/event-types-catalog.test.ts`) fails if the
   mirror omits a backend type. A filter option with no emitter is also a
   documented lie.

---

## Developer Guide / OAuth & Credentials Architecture

Source: https://docs.lumio.vision/developer-guide/oauth-credentials-architecture

# OAuth & Credentials Architecture

Platform email claims do not establish ownership of a Lumio email sign-in credential. A platform can populate an empty profile email, but it does not overwrite an existing address and cannot auto-link a profile by email equality. Email sign-in uses its own confirmed credential record. The ID app completes any required 2FA challenge with an authenticator app, passkey or recovery code before creating the session or returning a PKCE authorization code. A passkey sign-in is already 2FA-verified.

Lumio uses separate credential stores for login, channel, bot, and operator-managed integrations. Understanding which store minted a token is critical for anyone working on authentication, connections, or platform integrations: an OAuth refresh token can only be refreshed by the same OAuth app that issued it.

## Credential Stores

### 1. Config credentials

Stored in `config/local.toml` under `[auth]` and overridable with `LUMIO__AUTH__*` environment variables:

```toml
[auth]
twitch_client_id = "..."
twitch_client_secret = "..."
google_client_id = "..."
google_client_secret = "..."
discord_client_id = "..."
discord_client_secret = "..." # same login app as AUTH_DISCORD_SECRET in apps/id
kick_client_id = "..."
kick_client_secret = "..."
twitch_channel_client_id = "..."
twitch_channel_client_secret = "..."
kick_channel_client_id = "..."
kick_channel_client_secret = "..."
twitch_bot_client_id = "..."
twitch_bot_client_secret = "..."
kick_bot_client_id = "..."
kick_bot_client_secret = "..."
youtube_bot_client_id = "..."
youtube_bot_client_secret = "..."
discord_bot_client_id = "..."
discord_bot_client_secret = "..."
```

The plain provider pairs (`twitch_client_id`, `google_client_id`, `discord_client_id`, `kick_client_id`, and their secrets) are login credentials for the ID App (NextAuth) and for login-token refresh. The channel-specific pairs (`twitch_channel_client_id`, `kick_channel_client_id`, and their secrets) are the global Lumio OAuth apps used by `system` channel connections. The bot-specific pairs (`twitch_bot_client_id`, `kick_bot_client_id`, `youtube_bot_client_id`, `discord_bot_client_id`, and their secrets) are the global Lumio OAuth apps used by `system` bot connections or, for Discord, the verified server invite.

`CredentialResolver` resolves credentials per `(platform, kind)`, where `kind` is `channel` or `bot`. `system_pair(platform, kind)` returns the app pair actually used to mint or refresh a token; `system_configured(platform, kind)` reports whether a dedicated app for that exact kind is configured. For bot rows, `system_configured` is `false` when only the channel keys exist, even though the runtime can still use the channel fallback.

Both Twitch and Kick channel credentials fall back to their login pair when the dedicated channel pair is unset. For Kick this fallback (ZAF-1493) logs a one-time warning so the operator registers a dedicated channel app — quota and suspension are scoped to the `client_id`. It is not a redirect-URI limit: Kick accepts up to 10 redirect URIs per OAuth app (verified in the Kick developer dashboard, 2026-09-23; Kick's public documentation does not state the limit), so the login app can also register the channel callback `{web.public_url}/api/connections/oauth/kick/callback`.

Bot credentials prefer the dedicated bot pair. If a bot pair is unset, the bot flow falls back to the platform's channel pair and logs a one-time warning. If neither bot nor channel keys are available, `source_for(platform, bot)` degrades to `account`, matching the local/operator-managed path. YouTube bot has no channel fallback because YouTube channel connections are BYO/account; it needs `youtube_bot_client_id` / `youtube_bot_client_secret` to stay on `system`.

The split exists because provider limits attach to the OAuth `client_id`: Twitch app-access tokens allow 800 requests per minute per `client_id`, and Kick EventSub subscription caps are 10,000 subscriptions per event type per app. Keeping bot and channel apps separate gives chat bots their own quota and suspension surface.

YouTube and Spotify channel connections remain `account` / BYO, so there is no global channel system pair for them. YouTube bot has a bot OAuth mode and reads `youtube_bot_client_id` / `youtube_bot_client_secret` when configured; without those keys it degrades to the `account` path because there is no YouTube channel pair to fall back to.

Every provider field is `Option<String>` and defaulted, so a deployment can configure only the login providers it actually offers. The **login scopes** requested with them live in `apps/id/src/lib/providers.ts` and are user-level - they are not the channel scopes and must not be trimmed on the assumption that they belong to the channel side.

**Audience validation (ZAF-1015).** When the API exchanges a provider access token for a Lumio session (`POST /v1/auth/token`, `POST /v1/auth/authorize`, GraphQL `exchangeToken`, `POST /v1/auth/link`), `services::provider_validation::validate_provider_token` checks **two** things, not one: the token's **subject** (the claimed provider user id) *and* its **audience** - the OAuth client the token was minted for. The audience is read straight from the provider's own response, so it needs no extra request:

| Provider | Endpoint | Audience field | Configured value it must match |
|----------|----------|----------------|--------------------------------|
| Twitch | `GET id.twitch.tv/oauth2/validate` | `client_id` | `auth.twitch_client_id` |
| Google | `GET oauth2.googleapis.com/tokeninfo` | `aud` | `auth.google_client_id` |
| Discord | `GET discord.com/api/v10/oauth2/@me` | `application.id` | `auth.discord_client_id` |

The check is **fail-closed**: if a provider's client id is unset/empty, that provider's token exchange returns an error (mapped to `INTERNAL_SERVER_ERROR`) instead of silently skipping the audience check. A foreign-audience token (an app other than ours) is rejected as an invalid credential (`Unauthorized`, audited `user:login_failed`), identically to a subject mismatch. This closes an OAuth confused-deputy / audience-confusion path to account impersonation. `discord_client_id` is also paired with `discord_client_secret` for rotating Discord login-token refresh through `services::login_token::get_provider_credentials`.

**Defined in:** `apps/api/src/config.rs` (`AuthConfig` struct - which also holds `jwt_secret`, `jwt_expiration`, `refresh_token_expiration`, `ws_token_expiration` (WebSocket-token TTL, default 900s / 15 min; env `LUMIO__AUTH__WS_TOKEN_EXPIRATION`), and `token_encryption_key`)

### 2. Account app credentials

Stored in PostgreSQL and encrypted at rest with AES-256-GCM:

#### `app_credentials` table

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID | Primary key |
| `account_id` | UUID | Owning account |
| `platform` | String | Platform identifier (twitch, youtube, etc.) |
| `client_id` | String | Encrypted platform client ID |
| `client_secret` | String | Encrypted platform client secret |
| `created_at` | Timestamp | Creation time |
| `updated_at` | Timestamp | Last update time |

Used for: `account`-pinned channel connections, legacy/fail-safe `account` bot connections, and provider API calls whose client ID must match a per-account OAuth app.

#### `channel_connections` table

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID | Primary key |
| `account_id` | UUID | Owning account |
| `platform` | String | Platform identifier |
| `platform_channel_id` | String? | Platform-specific channel/broadcaster ID |
| `channel_name` | String? | Human-readable channel name |
| `access_token` | String | Encrypted OAuth access token |
| `refresh_token` | String? | Encrypted OAuth refresh token |
| `scopes` | String[]? | Granted OAuth scopes |
| `expires_at` | Timestamp? | Token expiration time |
| `credential_source` | String | Pinned OAuth app source: `system` or `account` |
| `created_at` | Timestamp | Creation time |
| `updated_at` | Timestamp | Last update time |

Used for: platform API calls made on behalf of the connected channel (EventSub, chat, profile enrichment, Spotify playback, etc.). The `credential_source` value is pinned at connect time and wins during refresh even if `[platform_credentials]` later changes.

**Constraint:** One connection per platform per account (`UNIQUE (account_id, platform)`) - the same constraint holds on `app_credentials`.

#### `bot_connections` table

The bot identity is a **third** row set, not a reuse of the channel connection. It has the same `UNIQUE (account_id, platform)` constraint and holds `bot_type` (`global` by default), `bot_username`, its own encrypted `access_token` / `refresh_token` / `scopes` / `expires_at`, and a pinned `credential_source`.

Global bot rows use the nil UUID account and are pinned to `system` for OAuth platforms. Account bot rows also carry their own pin. The compiled bot default is `system` for Twitch, Kick, YouTube, and Discord; Spotify has no bot connection. Discord's global bot token is static, but server invites use the separate global `[auth].discord_bot_client_*` app pair and store server-to-account mappings without per-account bot tokens. `system` OAuth bot rows use the dedicated bot app for their platform when configured; otherwise they use the channel fallback described above.

#### System-level credentials (`integration_configs`)

`integration_configs` is the operator-managed store for system connection records and integration configuration. It is not the source for global bot OAuth client credentials; those come from `[auth]` through `CredentialResolver`. The admin **System Connections** upsert - REST `PUT /v1/admin/system-connections/{platform}` and its GraphQL twin `adminUpsertSystemConnection` - stores `config.client_id` plus the AES-256-GCM-encrypted secret under `config.client_secret_encrypted` (the raw secret is never persisted or logged).

`db::system_connections::get_system_credential(db, platform, key)` is the single reader. It returns `Some((primary, Option<client_secret>))` where:

- `primary` is `config.client_id` (or `config.bot_token` for Discord), returned verbatim.
- the second element is the client secret **decrypted to plaintext**: the reader reads `config.client_secret_encrypted` and decrypts it with `key`, so callers never decrypt themselves and can never forget to. It is `None` when no secret is stored; a stored-but-undecryptable secret is a hard error, never a silent `None`.

Consumers: the admin System Connections page, playlist sync, and server-side native Twitch emote fetches via `get_twitch_emote_auth` in `apps/api/src/services/emotes.rs`. Global-bot OAuth authorize/exchange reads the config system pairs from `CredentialResolver::system_pair(platform, bot)`, not `integration_configs`; a global bot token must be minted by the same configured bot app that refreshes it.

### Shopify embedded app credentials

Shopify uses a separate public app configured by `[shopify]` (`client_id`, secret, scopes and App Store URL) and the matching per-environment `apps/shopify/shopify.app.<env>.toml`. It has no Lumio login provider, channel connection or authorization-code callback. The embedded page sends a short-lived App Bridge ID token to the REST-only `/v1/shopify/embedded/*` routes. Those routes verify the token as a Shopify staff-and-store principal, separate from `AuthContext`; the token cannot authorize Lumio account endpoints. After a link is confirmed in Lumio and completed in Shopify, the API exchanges a fresh ID token for the store's expiring offline access and refresh tokens. It encrypts those tokens in the store's `integration_configs.config` and refreshes them through `services::shopify::fresh_access_token`. See [Shopify](/features/shopify#token-storage-and-refresh).

## Credential Modes and Pinning

`CredentialResolver` resolves where a **new** connection gets its OAuth app for each `(platform, kind)` pair, where `kind` is `channel` or `bot`.

| Kind | Default `system` platforms | Default `account` platforms |
|------|----------------------------|-----------------------------|
| `channel` | Twitch, Kick | YouTube, Spotify |
| `bot` | Twitch, Kick, YouTube, Discord | none for supported bots |

The defaults can be overridden in config:

```toml
[platform_credentials]
twitch = "system"
kick = "system"
youtube = "account"
spotify = "account"

[platform_credentials.bot]
twitch = "system"
kick = "system"
youtube = "system"
discord = "system"
```

The flat `[platform_credentials]` keys are channel overrides. The nested `[platform_credentials.bot]` table is the bot override table.

Discord accepts only `"system"` in the bot table. An `"account"` override is ignored with a warning. `platformCredentialModes` includes its Bot row and reports `systemConfigured` only when both `discord_bot_client_*` keys are set. Without them the generic resolver degrades to `account`, but Discord's invite path rejects that fallback: there is no per-account Discord bot app.

If the configured/default mode is `system` but the required global keys are missing, `CredentialResolver::source_for` degrades the new connect to `account` and logs once. For `channel`, the required keys are the dedicated channel pair (with Twitch's login fallback). For `bot`, the required keys are the dedicated bot pair or, as a runtime safety net, the platform's channel pair. That fail-safe keeps local and operator-managed installs behaving like the historical BYO model. Once a connection is created, the chosen source is stored on `channel_connections.credential_source` or `bot_connections.credential_source`; changing the default later affects only future connects.

## Moving a platform to `system` later

Today only Twitch and Kick **channels** use the global Lumio OAuth app; YouTube and Spotify channels stay `account`/BYO (see **Config credentials** and **Credential Modes and Pinning** above). The credential *mode* is pure config - `[platform_credentials]` plus the compiled defaults - so **selecting** `system` for another platform needs no code. But the resolver's global-app lookup and one dev-only callback path are still hard-coded to the launch platforms, so a `system` selection for YouTube or Spotify would silently degrade back to `account` until they are filled in. This section records exactly what is already generic and what still needs a code change, so nobody has to re-derive it.

### Already generic - no code needed

- **The config override.** `CredentialResolver::configured_mode` looks up `[platform_credentials]` / `[platform_credentials.bot]` by platform key; any platform string already resolves.
- **The call sites.** `source_for` and `system_pair` take the platform and kind as parameters, and every token consumer flows through them and through the source-aware refresh in `workers/token_refresh.rs`, which keys off the row's pinned `credential_source` rather than a hard-coded platform list.
- **The redirect URI.** `unified_callback_url(web_public_url, platform)` (`routes/oauth_state.rs`) is built from the platform variable - the shared `…/api/connections/oauth/{platform}/callback` URL works for any platform.
- **The frontend.** The connections UI renders from `platformCredentialModes` (GraphQL/REST), one row per `(platform, kind)`; it is data-driven and needs no per-platform code.

### Needs a code change

1. **Add global channel keys to `AuthConfig`** (`apps/api/src/config.rs`). `google_client_id` / `google_client_secret` are the **login** app (ID App / NextAuth), not a channel app, and Spotify has no config fields at all. Moving either channel to `system` needs four new `Option<String>` fields following the existing `*_channel_client_id` / `*_channel_client_secret` convention (e.g. `google_channel_client_id` + secret and `spotify_channel_client_id` + secret), each with a `default.toml` comment.
2. **Add the channel arms to `system_pair`** (`apps/api/src/credentials.rs`). It matches only `twitch` and `kick` and returns `None` for everything else - that `None` is what makes `source_for` degrade YouTube/Spotify to `account`. Add a `youtube` and a `spotify` arm. YouTube may fall back to the login keys the way Twitch does (Google permits multiple redirect URIs per app); Spotify needs its own dedicated keys.
3. **List Spotify in `degrade_warned`** (`apps/api/src/credentials.rs`). The one-time "selected `system` but no global keys" warning only fires for platforms in the `degrade_warned` set (`twitch`, `kick`, `youtube`). Spotify is absent, so a misconfigured Spotify `system` selection degrades **silently**. The runtime behaviour is already correct - this is only the missing operator warning.
4. **Extend the Spotify `localhost` → `127.0.0.1` dev fix to the unified callback** (`apps/api/src/routes/oauth_state.rs`). Spotify rejects `localhost` redirect URIs and requires `127.0.0.1`. That swap lives in the `account` authorize branch (`routes/connections.rs`, `graphql/connections.rs`) but **not** in `unified_callback_url`, which the `system` flow uses. Without it, Spotify in `system` mode fails **locally only**; production (no `localhost`) is unaffected.

### Precondition that no code can satisfy

- **YouTube:** the Data API quota is billed to the OAuth app's Google Cloud project, so a single global Lumio app means one daily quota shared across every customer - which is the whole reason YouTube stays BYO. A `system` YouTube channel is gated on a Google quota increase, not on the code above (ZAF-978 §11 step 4b).
- **Spotify:** an app in Development Mode is capped at 25 users; serving all customers from one app needs Spotify's Extended Quota Mode, which requires an application to Spotify.

### Existing connections do not migrate

Flipping a platform to `system` governs **new** connects only. Existing rows keep the `credential_source` pinned at connect time and refresh with whichever app issued them - a refresh token minted by app A cannot be refreshed by app B. There is no migration step; a full move to `system` means users reconnect once.

## Encryption

All DB credentials are encrypted using **AES-256-GCM** with a random 96-bit nonce per encryption operation.

- **Key source:** `config.auth.token_encryption_key` (TOML config)
- **Key derivation (versioned registry):** the configured secret derives a small key registry (`crypto::EncryptionKeys::from_secret`), one AES-256 key per ciphertext version:
  - **v1** (`crypto::derive_key`) - legacy derivation: a config value of exactly 32 bytes is used *raw*, anything else is `SHA-256`-hashed. Reads every row written before versioning. Retained only for backward compatibility - because the 32-byte branch is used raw, changing the secret's *length* (31 vs 32 vs 33 bytes) silently changes v1 derivation, which is precisely why new writes use v2.
  - **v2** (`crypto::derive_key_v2`) - `HMAC-SHA256(domain-salt, secret)`, a uniform KDF over the raw secret bytes. Length-invariant (no raw/hashed mode flip). Used for **all new writes**.
- **Ciphertext format:** new writes are version-tagged `v2.{base64(nonce)}.{base64(ciphertext)}`; legacy rows are untagged `{base64(nonce)}.{base64(ciphertext)}` and read as **v1**. Standard base64 never contains `.`, so part-count disambiguates cleanly (3 dot-parts ⇒ versioned, 2 ⇒ legacy v1).
- **Implementation:** `apps/api/src/crypto.rs` (`encrypt_versioned` / `decrypt_versioned`)

Encryption happens at the boundary -- values are encrypted before database writes and decrypted after reads. The database never stores plaintext credentials.

### Typed decrypt failures (diagnosability)

Because ciphertext is version-tagged, a decrypt failure is *typed* rather than a bare AES-GCM error - this is what makes the ZAF-1196 confusion class ("undiagnosable `aead::Error`") diagnosable:

- `UnsupportedVersion` - the row's tag is not in this build's registry (e.g. a `v3.` row read by a binary that only knows `v1`/`v2`).
- `KeyMismatch` - the row is well-formed (valid framing, base64, 12-byte nonce) but AEAD authentication failed: it was written under a **different or older key** than the one currently configured. This is "wrong/rotated key", diagnosably distinct from "corrupt data".
- `InvalidFormat` - malformed framing, bad base64, or wrong nonce length.

### Rotating the key invalidates every stored secret

Versioning does **not** add old-key retention. Changing `auth.token_encryption_key` (or deploying a build that derives a different key from it) re-derives *both* the v1 and v2 keys, so **every** value ever encrypted under the old secret becomes unreadable at once - all `app_credentials` `client_id`/`client_secret` rows, and every `access_token`/`refresh_token` on `channel_connections` and `bot_connections`. The failure now surfaces as a typed `KeyMismatch` instead of a bare authentication error, but the data is equally unreadable.

Consequences and remediation:

- **App credentials** surface the broken state directly: the `appCredentials` query and its REST twin return `decryptable: false` for a row whose `client_id` no longer decrypts (the platform App section then shows an "action required" warning). `authorizeChannel` and the REST `authorize` twin refuse with the stable code `CREDENTIAL_DECRYPTION_FAILED` and the message *"Stored OAuth app credentials for {platform} can no longer be decrypted. Re-enter them in the platform tab’s App section."* **Remediation:** re-enter the client_id/secret under **Connections → App Credentials**, which re-encrypts them under the current key.
- **Channel/bot tokens** cannot be refreshed once their ciphertext (or their account's `app_credentials`) fails to decrypt; the token-refresh worker treats it as terminal and flags the connection `reconnect_required` (best-effort audit + email). **Remediation:** reconnect the affected channels.

So key rotation is only safe with a coordinated re-encrypt of every stored secret; there is no automatic migration path today.

### Forward-only format - binary rollback hazard

The version tag is a **one-way format upgrade**, not a reversible flag. Once a build that writes `v2.` ciphertext has run in an environment, rolling the API binary *back* across this change makes those rows unreadable - the pre-versioning `decrypt` cannot strip the version tag and fails with a bare `aead::Error`. **Treat a rollback past this change like a data migration:** it requires re-encrypting the affected rows, not just redeploying the old binary. This is a deliberate BC/DR constraint of the versioned scheme (ZAF-1204). New writes are v2 and legacy untagged rows are never bulk-migrated - they keep reading via the v1 key indefinitely.

## Rules

1. **Config credentials are valid only for their source.** Login config credentials are used for login and login-token refresh. System channel and bot config credentials are used for connections pinned to `system`. Connections pinned to `account`, and legacy rows without an explicit system pin, must use `app_credentials`.
2. **Token refresh follows the pinned `credential_source`.** For `account`, the OAuth app pair comes from `app_credentials` and the token row comes from `channel_connections` or `bot_connections`. For `system`, the OAuth app pair comes from config and the refresh/access tokens still come from `channel_connections` or `bot_connections`.
3. **ProfileService decrypts on demand.** It receives pre-decrypted `ChannelCredentials` from the API layer and never stores them.
4. **Secrets are never exposed via API.** The GraphQL `appCredentials` query and its REST twin return only a `client_id_hint` (last 4 characters) plus a non-null `decryptable` flag (`false` when the stored `client_id` no longer decrypts under the current key). Tokens are never included in `channelConnections` responses.
5. **Never refresh inline.** Read a fresh token only through the three accessors in `apps/api/src/oauth.rs`; a worker must not run its own refresh against a platform token endpoint.

## Reading a fresh token

All three accessors return the same `FreshToken` (`access_token`, `refresh_token`, `client_id`, `client_secret`, `expires_at`) and all three skip rows flagged `reconnect_required = true`, so a connection the user must re-authorize never yields a token:

| Function | Source row | Credentials |
|----------|-----------|-------------|
| `get_fresh_connection_token` | `channel_connections` with a source-aware `LEFT JOIN` to `app_credentials` | `system` rows use `CredentialResolver::system_pair(platform, channel)`; `account` rows decrypt per-account `app_credentials` |
| `get_fresh_oauth_token` | `login_connections` | Returns **empty** `client_id` / `client_secret` - login connections use the config credentials, which the caller supplies |
| `get_fresh_bot_token` | `bot_connections` with a source-aware `LEFT JOIN` to `app_credentials` | `system` rows use `CredentialResolver::system_pair(platform, bot)`; `account` rows decrypt per-account `app_credentials`; Discord's static global token is not refreshed |

## Token Refresh Flow

The `OAuthTokens` struct in `apps/api/src/oauth.rs` manages automatic token refresh:

1. Workers check `needs_refresh()` before each API call. It is `true` only when a `refresh_token` exists **and** `token_needs_refresh(expires_at)` holds - a 5-minute margin before expiry. A `None` expiry is treated as "no refresh needed".
2. If refresh is needed, `try_refresh()` sends a request to the platform's token endpoint via `refresh_oauth_token()`
3. The new tokens are encrypted and persisted (`update_connection_tokens` / `update_oauth_tokens` / `update_bot_connection_tokens`)
4. In-memory state is updated for the worker to continue

The time-based Token Refresh Worker cannot see a token that is dead while its `expires_at` still lies in the future (revoked, or minted by an app other than the pinned one). For that case `oauth::refresh_rejected_connection_token` is the on-demand path a platform worker calls after a provider **HTTP 401** (Twitch EventSub, Kick subscriptions). It takes the same per-connection lock as the worker, re-reads the token through `get_fresh_connection_token` (so the pinned `credential_source` decides the client), and refreshes only when the stored token is still the rejected one. A terminal refresh failure flags `reconnect_required`; a second 401 with the new token is flagged through `oauth::flag_rejected_connection_token`. Workers still never refresh inline.

Two authentication styles are supported (`AuthStyle` in the same module), resolved per platform together with the token endpoint by `oauth::token_endpoint`:
- **Body** (Twitch, YouTube, Kick): `client_id` and `client_secret` sent as POST body parameters
- **BasicHeader** (Spotify): `base64(client_id:client_secret)` sent as `Authorization: Basic` header

## Flowcharts

### User Login Flow (Config Credentials)

```mermaid
flowchart TD
    A[User visits /login] --> B[ID App / NextAuth]
    B --> C{Select platform}
    C --> D[Redirect to platform OAuth]
    D --> E[User authorizes]
    E --> F[Platform callback with code]
    F --> G[ID App exchanges code for token]
    G --> H[Create/update user + login_connections]
    H --> I[Issue JWT session]

    style B fill:#3b82f6,color:#fff
    style G fill:#f59e0b,color:#fff

    subgraph credentials_used ["Config Credentials Used"]
        direction LR
        J["auth.twitch_client_id"]
        K["auth.twitch_client_secret"]
    end
```

**Display name vs. login.** The ID App resolves a distinct display name and login before the exchange: Twitch's OIDC claims expose only the lowercase login, so its `profile()` calls Helix `GET /users` (YouTube/Google does the analogous `youtube/v3/channels` lookup). `find_or_create_user_by_provider` then persists both — the login connection keeps `display_name` (visible) and `username` (login), and the `users` row carries both `display_name` and a dedicated `login` column (the login is COALESCE-protected on update, so a login flow that sends no username, e.g. the PKCE-native path, never wipes it). Render surfaces (sidebar, account switcher, profile) fall back to `display_name` when `login` is `null`. On a returning user the login update refreshes `login` from the platform, while the Lumio-visible `display_name` and `avatar_url` are mirrored from the user's name-source login connection. `users.name_source_connection_id` pins that source; when it is `null`, Lumio uses the first-ever-connected login connection. Users switch or clear the source through GraphQL `setNameSourceConnection` or REST `PUT /v1/users/me/name-source-connection`; `PATCH /users/me` and GraphQL `updateMe` do not accept a free-text display-name override.

### Channel Connection Flow (Pinned Credentials)

```mermaid
flowchart TD
    A[User clicks Connect] --> B{Resolve source for platform + channel}
    B -->|system| C[Read global OAuth app from config]
    B -->|account| D[Read encrypted app_credentials]
    C --> E[Build authorize URL with scopes]
    D --> E[Build authorize URL with scopes]
    E --> F[Redirect to platform OAuth]
    F --> G[User authorizes channel access]
    G --> H[Callback with authorization code]
    H --> HB{Caller is the session that started the connect?}
    HB -->|no| HX[Reject - no row written]
    HB -->|yes| I[Exchange code for access_token + refresh_token]
    I --> J[Fetch channel info from platform API]
    J --> K[Encrypt tokens]
    K --> L[Store in channel_connections with credential_source]
    L --> M[Start platform worker]

    style C fill:#10b981,color:#fff
    style L fill:#10b981,color:#fff
    style M fill:#8b5cf6,color:#fff

    subgraph db_credentials ["DB Credentials Used"]
        direction LR
        N["config system pair OR app_credentials"]
        O["channel_connections.credential_source"]
        P["channel_connections.access_token"]
    end
```

Starting a connect (`authorize`) requires an interactive sign-in session, and every exchange - the unified one for the `system` flow and the account/BYO alias exchanges (`POST /v1/connections/channel/{platform}/exchange`, `POST /v1/bot-connections/{platform}/exchange`, whose state values carry the same structured handle) - completes the channel / account-bot handle only for **that same user's session** (ZAF-1922 for the alias path), re-checking account access and `connections:create` / `bot-connections:create` before `pkce::take` and before any token is stored. An API key (`lm_usr_`) can neither start nor finish a connect. The admin global-bot handle is exempt (its return leg runs on the web host without an admin session; only an admin can mint it). See [Authentication → Session-only Surfaces](../api-reference/authentication.md#session-only-surfaces).

### ProfileService Enrichment Flow

```mermaid
flowchart TD
    A[GraphQL: platformUserProfile query] --> B[API resolves account credentials]
    B --> C[Decrypt client_id + client_secret from app_credentials]
    C --> D[Decrypt access_token from channel_connections]
    D --> E[Build ChannelCredentials struct]
    E --> F[Call ProfileService.get_profile]
    F --> G{Redis cache hit?}
    G -->|Yes| H[Return cached profile]
    G -->|No| I[Load from database]
    I --> J{Enrichment stale?}
    J -->|No| K[Cache with 4h TTL]
    J -->|Yes| L{Circuit open?}
    L -->|Yes| M[Cache with 15min TTL]
    L -->|No| N[Call platform API with decrypted credentials]
    N -->|Success| O[Merge enrichment + cache 4h]
    N -->|Failure| P[Record failure + cache 30min]

    style F fill:#3b82f6,color:#fff
    style N fill:#f59e0b,color:#fff
```

## PKCE (OAuth 2.1)

OAuth-2.1 providers require PKCE (RFC 7636) on the authorize/token exchange even
for confidential clients that also send a `client_secret`. PKCE is opt-in per
platform via `PlatformOAuthConfig::requires_pkce` (`apps/api/src/platforms.rs`),
currently `true` only for **Kick** (channel and bot). It applies to every
outgoing authorize flow — channel, account bot, and admin global bot — on both
GraphQL and REST, and to the ID App login provider (next-auth's default
`checks: ["pkce", "state"]`, pinned explicitly on the Kick provider).

The `refresh_token` grant never carries PKCE, so token refresh is unaffected.

Mechanics (`apps/api/src/routes/pkce.rs`):

1. **Authorize** — when `requires_pkce`, mint a 43-char base64url `code_verifier`,
   store it in Redis under `oauth:pkce:{state}` (600s TTL), and add
   `code_challenge` (`base64url_nopad(sha256(verifier))`) + `code_challenge_method=S256`
   to the authorize URL. All six builders share `platforms::build_authorize_url`,
   so the parameters are identical across paths.
2. **Exchange** — `pkce::take(state)` reads and deletes the verifier (single-use)
   and the token exchange sends it as `code_verifier`. A missing entry (non-PKCE
   platform, or expired/replayed state) yields `None` and no field is sent.

The verifier is a short-lived secret and is never logged.

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/config.rs` | `AuthConfig` with login and system channel/bot config credentials; `PlatformCredentialsConfig` overrides |
| `apps/api/src/crypto.rs` | AES-256-GCM encrypt/decrypt + key derivation |
| `apps/api/src/db/connections.rs` | CRUD for `app_credentials` and `channel_connections` |
| `apps/api/src/oauth.rs` | `OAuthTokens` struct + token refresh logic |
| `apps/api/src/platforms.rs` | Per-platform OAuth config (`requires_pkce`) + `build_authorize_url` |
| `apps/api/src/routes/pkce.rs` | PKCE verifier mint/take + S256 challenge (RFC 7636) |
| `apps/api/src/graphql/connections.rs` | GraphQL resolvers (secrets masked in responses) |
| `apps/api/src/credentials.rs` | `CredentialResolver`, fail-safe degradation, system/account mode exposure |
| `apps/api/src/platforms.rs` | Platform OAuth configs, credential-source defaults, authorize URLs, token URLs, scopes |
| `crates/lo-chat/src/profile_service.rs` | `ChannelCredentials` struct consumed by ProfileService |

---

## Developer Guide / PKCE and Native App Auth

Source: https://docs.lumio.vision/developer-guide/pkce-native-auth

# PKCE and Native App Auth

## Overview

Lumio supports OAuth2 + PKCE (Proof Key for Code Exchange) for native applications including desktop apps, mobile apps, and CLI tools. The ID app (`apps/id`) acts as the authorization server.

Native apps never see user credentials. Instead, they receive an authorization code via a custom URL scheme redirect, then exchange that code for a JWT. PKCE ensures that even if the authorization code is intercepted, it cannot be used without the original `code_verifier` that only the native app holds.

## Supported Platforms

| Platform | Redirect URI | Examples |
|----------|-------------|---------|
| **Desktop** | `lumio://callback` | Electron, Tauri, native Win/Mac/Linux apps |
| **Mobile** | `lumio-app://callback` | iOS (Swift), Android (Kotlin), Flutter, React Native |
| **CLI** | `http://localhost:{port}` | Command-line tools, local dev tools |

## PKCE Flow (Step by Step)

### Step 1: Generate PKCE Parameters

The native app generates three values before opening the browser:

- **`code_verifier`**: A cryptographically random string of 43–128 characters using only `A-Z`, `a-z`, `0-9`, `-`, `.`, `_`, `~`
- **`code_challenge`**: `base64url(SHA256(code_verifier))` - this is sent to the server, never the verifier itself
- **`state`**: A random UUID used for CSRF protection

```typescript
import crypto from "crypto";

function generateCodeVerifier(): string {
  return crypto.randomBytes(64).toString("base64url").slice(0, 128);
}

function generateCodeChallenge(verifier: string): string {
  return crypto.createHash("sha256").update(verifier).digest("base64url");
}

function generateState(): string {
  return crypto.randomUUID();
}
```

### Step 2: Open System Browser to ID App

The native app opens the system browser pointing at the ID app login page with PKCE parameters in the query string:

```
https://id.lumio.vision/login?
  redirect_uri=lumio://callback
  &client_type=desktop
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=random-uuid
```

The ID app (`apps/id/src/app/login/page.tsx`) extracts and stores these parameters in an auth state cookie via `apps/id/src/app/login/login-client.tsx`.

### Step 3: User Authenticates

The user signs in with a platform, verified email/password or passkey inside the browser. The ID app handles credentials and, when enabled, a 2FA challenge. The native app waits passively. The API does not issue an authorization code until the challenge is completed.

### Step 4: ID App Creates an Authorization Code

Once the user authenticates, the ID app calls the Rust API:

```
POST https://api.lumio.vision/v1/auth/authorize
```

The API finds or creates the user for the provider identity, then stores `{ user_id, code_challenge }` in Redis under `auth_code:{code}` with a 300-second TTL and returns a short-lived authorization code - `lumio_auth_` plus 32 hex characters (16 random bytes).

The PKCE branch in `apps/id/src/auth.ts` is the `if (authState?.code_challenge)` block inside the `signIn` callback; it calls `authorize()` from `@lumio/api`.

### Step 5: Browser Redirects to Native App

The ID app opens `/login/done` with an allowlisted `return_to` deep link containing the authorization code and state. It attempts to open the native app and shows a **Back to the app** button in case the browser leaves the page open. That link has this shape:

```
lumio://callback?code=lumio_auth_xxxx&state=random-uuid
```

The operating system routes this URI to the registered native app.

### Step 6: Native App Validates State

The native app checks that the `state` in the callback URL exactly matches the `state` generated in step 1. If they differ, abort - this indicates a CSRF attack or a stale request.

### Step 7: Exchange Code for JWT

The native app sends the authorization code and the original `code_verifier` (not the challenge) to the API:

```http
POST https://api.lumio.vision/v1/auth/token/exchange
Content-Type: application/json

{
  "code": "lumio_auth_xxxx",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}
```

### Step 8: API Validates PKCE and Issues Tokens

The API performs the following steps:

1. Looks up `auth_code:{code}` in Redis - a miss (unknown or expired code) returns `401 Unauthorized`
2. **Deletes the Redis key immediately**, before verification - a failed exchange burns the code just as a successful one does, so an attacker cannot brute-force the verifier against a live code
3. Computes `base64url(SHA256(code_verifier))` (no padding) from the request
4. Compares it to the stored `code_challenge` with a constant-time comparison (`lo_common::constant_time_eq`)
5. On mismatch: `401 Unauthorized`
6. On match: resolves the user's first owned account, creates a session row (with the caller's IP and user-agent), and issues a JWT carrying the session id plus a long-lived refresh token

An empty `code` or `code_verifier` is rejected with `400 Bad Request` before any lookup. Authorization codes are strictly single-use.

### Step 9: Store Tokens Securely

The native app receives the JWT and refresh token and stores them in secure OS storage (see platform-specific sections below). The JWT is included in subsequent API requests as a Bearer token.

## Query Parameters Reference

| Parameter | Required | Description |
|-----------|----------|-------------|
| `redirect_uri` | Yes | Custom URL scheme callback (e.g., `lumio://callback`) |
| `client_type` | Yes | `desktop`, `mobile`, or `cli` |
| `code_challenge` | Yes | Base64url-encoded SHA256 of the code_verifier |
| `code_challenge_method` | No | Always `S256` (default; plain is not supported) |
| `state` | Recommended | Random UUID for CSRF protection |

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/v1/auth/authorize` | POST | Exchange provider token for auth code (internal - called by ID app) |
| `/v1/auth/token/exchange` | POST | Exchange auth code + code_verifier for JWT |
| `/v1/auth/refresh` | POST | Refresh an expired JWT using a refresh token |

## Mobile App Considerations

- Register the `lumio-app://` custom URL scheme in:
  - **iOS**: `Info.plist` under `CFBundleURLTypes`
  - **Android**: `AndroidManifest.xml` under `<intent-filter>` with `android.intent.action.VIEW`
- Use **ASWebAuthenticationSession** (iOS) or **Chrome Custom Tabs** (Android) to open the browser - do not use an embedded WebView, as app stores may reject it
- Handle the deep link callback in the app delegate (iOS) or the activity that registered the intent filter (Android)
- Store tokens in:
  - **iOS**: Keychain via `SecItemAdd` / `SecItemCopyMatching`
  - **Android**: `EncryptedSharedPreferences` or Android Keystore
  - **Flutter**: `flutter_secure_storage`
  - **React Native**: `react-native-keychain`

## Desktop App Considerations

- Register the `lumio://` custom URL scheme at the OS level:
  - **Electron**: use `app.setAsDefaultProtocolClient("lumio")` and handle `open-url` (macOS) / `second-instance` (Windows/Linux)
  - **Tauri**: configure the `deep-link` plugin in `tauri.conf.json`
  - **Native macOS**: register in `Info.plist` under `CFBundleURLTypes`
  - **Native Windows**: register in the Windows Registry under `HKEY_CLASSES_ROOT\lumio`
- Store tokens in the OS keychain:
  - **Electron/Node.js**: `keytar` (cross-platform keychain bindings)
  - **Tauri**: `tauri-plugin-stronghold` or the OS credential store
  - **macOS**: Keychain Services
  - **Windows**: Windows Credential Manager

## Environment Setup

The ID app requires the custom URL schemes to be listed in `ALLOWED_REDIRECT_ORIGINS` so the redirect allowlist (`apps/id/src/lib/redirect-allowlist.ts`) accepts them:

```env
ALLOWED_REDIRECT_ORIGINS=http://localhost:4000,http://localhost:4001,lumio://callback,lumio-app://callback
```

Add any additional custom schemes (e.g., for white-labeled apps) to this list.

`isAllowedRedirect()` parses both the candidate and each allowlist entry and requires an exact scheme + authority match rather than a `startsWith` prefix test. A prefix test on `lumio://auth` would also accept `lumio://auth.evil.com/...` and `lumio://authhijack/...`. A **scheme-only** entry (`lumio://`, no authority) is accepted as a wildcard for that scheme, because the OS routes every `lumio://…` URI to the registered app anyway.

## Security Notes

- **Auth codes expire after 5 minutes** - enforced by the Redis TTL set at code creation
- **Auth codes are single-use** - Redis removes the code on the first exchange attempt, including an attempt with the wrong verifier
- **2FA precedes the code** - `authorize` returns a pending `mfa_token` and `mfa_methods` until `POST /v1/auth/mfa/verify` succeeds with an app/recovery code or passkey assertion; a passkey sign-in already completes 2FA; never pass a pending challenge to the native app as a code
- **The `code_verifier` is never sent to the server during the authorization step** - only the `code_challenge` (a one-way hash) is stored
- **Always use `S256`** - plain `code_challenge_method` is not supported and will be rejected
- **Always validate `state`** - skip this check at your own risk; a missing or mismatched state allows CSRF attacks
- **Never store tokens in localStorage or sessionStorage** in a browser context; use OS-level secure storage for native apps

## Key Files

| File | Purpose |
|------|---------|
| `apps/id/src/app/login/page.tsx` | Extracts PKCE params from the query string on page load |
| `apps/id/src/app/login/login-client.tsx` | Stores PKCE params in the auth state cookie |
| `apps/id/src/auth.ts` | PKCE branch in the `signIn` callback (`if (authState?.code_challenge)`) |
| `apps/api/src/routes/auth.rs` | `POST /v1/auth/authorize` + `POST /v1/auth/token/exchange` handlers, PKCE verification |
| `apps/id/src/lib/redirect-allowlist.ts` | Validates that `redirect_uri` is an allowed custom URL scheme |
| `shared/api/src/auth.ts` | `authorize()` and `exchangeAuthCode()` client functions |

---

## Developer Guide / Passkeys and Authenticator Apps

Source: https://docs.lumio.vision/developer-guide/passkeys

# Passkeys and Authenticator Apps

## Overview

The API stores up to five TOTP apps and ten passkeys per profile in `user_mfa_factors`. The passkey user handle is random and kept separately in `user_webauthn_handles` until profile deletion. A passkey can sign in without a password, complete a pending 2FA challenge or confirm a session. REST (`routes/security.rs`) and GraphQL (`graphql/security.rs`) call the same security service. Both use an interactive session for method management and the same second-factor validation for removal, disable and recovery-code replacement. The first method gives ten recovery codes; a first-passkey registration is committed only after `recoveryCodesStored: true` (REST `recovery_codes_stored`).

`[webauthn]` pins the RP ID, name and exact browser origins; see [Installation](/getting-started/installation#passkey-relying-party-configuration). Registration requests `attestation: none`, accepts ES256 and RS256, and sends the profile display name rather than its email address. It does not query FIDO MDS. The ID app forbids embedding with `frame-ancestors 'none'` and `X-Frame-Options: DENY`. WebAuthn registration and assertion challenges are short-lived, single-use Redis records.

## Provider names and logos

`apps/api/src/services/security/passkey_aaguids.json` embeds provider names and AAGUIDs. The dashboard shows the user's label with the provider name and its logo, where one is available. Unknown or browser-suppressed AAGUIDs produce **Passkey** and the generic passkey symbol. Providers with no icon in the list or an excluded logo also show the generic symbol. Where the browser supplies a YubiKey AAGUID, the API shows its model name and the dashboard uses the Yubico logo. No provider list or logo is fetched from a third party at runtime. A trademark notice appears under the user's passkey list whenever a logo is visible.

The logo files in `apps/web/public/passkey-providers/` are light and dark SVG pairs. For entries from the AAGUID list, each file is the `icon_light` or `icon_dark` value from the same upstream commit as the API's provider names, decoded from base64 byte for byte; do not redraw, optimize or recolor it. `sources.json` records that upstream commit, the provider-name and AAGUID mapping, the commit and submitter domain for each icon, excluded providers and entries without an icon. The Yubico pair is the documented Simple Icons CC0 exception in `sources.json`. The server reads this metadata and passes only the name-to-logo mapping to the dashboard. The UI embeds third-party SVGs only through `<img>` with empty alt text because the provider name is adjacent; never inline them or use `<object>`, `<embed>` or `<iframe>`. The light and dark variants switch with the theme without changing brand colors. Logos belong only in the user's passkey list and its dialogs. Public documentation screenshots must use the generic symbol or crop provider logos out.

To refresh the provider list and logos:

1. Review the selected upstream AAGUID-list commit. For **every new or changed icon**, inspect the commit that supplied that icon and who submitted it, then check the vendor's trademark guidance for restrictions on this use. Keep excluded providers in `sources.json` without logo files. If a vendor objects, remove its logo mapping and both SVG files; its row then uses the generic symbol.
2. In one repository commit, update `passkey_aaguids.json`, `sources.json` and the matching `<slug>-light.svg` / `<slug>-dark.svg` files from that same upstream commit. Record the commit, provider names, AAGUIDs and icon submitter evidence in `sources.json`. Check that every API provider name maps to a logo, an excluded provider or an entry without an icon. If the upstream list is emptied or retired, keep the embedded copy until a reviewed replacement exists.
3. Run the SVG safety test in `apps/web/__tests__/passkey-providers.test.ts`. Its allowlist accepts only the SVG elements and namespaces already needed by the files, local `#id` references, and restricted CSS. It rejects active markup, external references, entities and unsafe CSS. An SVG that fails needs review; do not widen the allowlist merely to accept it. The static path also has an enforcing sandbox CSP and `nosniff`; see [Web Content-Security-Policy](./web-content-security-policy.md#static-svgs-under-passkey-providers).

## Privacy and exports

The JSON export uses an explicit `factors` projection: `kind`, `label`, `created_at`, `last_used_at`, plus `provider` and `backup_state` for passkeys. Do not broaden it to a row-wide serializer: secrets, credentials, IDs, counters and the user handle must stay out. Audit entries and security notices identify the method type and context, never the user's free-text label. Removing a passkey invalidates it on Lumio and returns its credential ID only to the signed-in browser for the WebAuthn Signal API; the user may still need to delete it in their password manager.

---

## Developer Guide / Email templates

Source: https://docs.lumio.vision/developer-guide/email-templates

# Email templates

## Overview

`crates/lo-email` renders every mail through one C · Brief layout. A mail has a category and date above a heading, fine lines instead of cards, content blocks, an optional button, and a footer. The HTML is light by default and supplies its own dark colors for clients that support them. Emails have no seasonal look or animation.

The 59 `NoticeKind` values in `crates/lo-email/src/notices.rs` cover account notices and 18 template mails. `templates::TemplateContext` is the typed input for the latter; it supplies values and optional blocks to the same renderer. The single Sailfish layout, `crates/lo-email/templates/brief.stpl`, draws the blocks. The `NoticeKind::ALL` catalog and exhaustive copy match require each kind to be represented.

Two purchase mails are built outside `NoticeKind`, from their own typed input, on the same layout: the order confirmation (`withdrawal::render_order_confirmation`, see [Billing → Withdrawal waiver and order confirmation](/features/billing#withdrawal-waiver-and-order-confirmation)) and the notice of an automatic refund of an undeliverable extension checkout (`refund::render_refund_notice`, see [Webhooks → Stripe Connect](/features/webhooks#stripe-connect--paypal-payouts-extension-marketplace)). Both are transactional: no notification type, no manage link, DE/EN by the buyer's resolved locale. They are not part of the `preview` example.

## Building blocks and copy

`brief::Mail` holds the language, tone, category, date, subject, inbox preview text, blocks, and footer. `brief::Block` provides headings and lead lines, paragraphs and greetings, label/value details, notes with a colored edge, metrics, CID images and charts, platform tables, channel rows, buttons, fine print, and hints. The footer explains why the recipient got the mail and shows localized legal links.

German and English copy live together in `notices.rs`. Each language supplies the subject, preview text, category, paragraphs, detail labels, button and hint text, and footer reason. Subject and body copy may use placeholders such as `{channel}` or `{date}`; callers supply plain-text values via `Notice::params` or `TemplateContext`. The renderer fills values before delivery. `**bold**` in copy marks emphasis; `brief::runs_filled` splits copy into runs before filling placeholders, so a value cannot create formatting. Sailfish escapes values in HTML. Subjects and `text/plain` remain plain text. A missing parameter omits a detail row when its entire value depends on that parameter; missing placeholders in running text remain visible, so callers must provide every required value.

Every channel row (channel invite, role changed, dissolution notice to members) shows the channel's platform marks from `{platforms}` — comma-separated platform keys that `apps/api` reads with `invite_notifications::account_platforms`, in the dashboard order Twitch, YouTube, Kick, then the rest — and the recipient's role from `{role}`. A row without platforms or without a role leaves that part out. Billing mails pass the plan as `{plan}` and the stored Stripe cadence as `{billing_interval}` (`month` or `year`). The copy uses the derived `{plan_term}`, for example “Pro · monatlich” / “Pro · monthly”; without a known interval it is the plan name alone, and the raw value never appears in a mail.

The recipient's resolved `de` or `en` locale selects the copy. Dates use the recipient's resolved timezone where the caller supplies a localized date. See [Notifications](/features/notifications#email-language-and-timezone) for the preference resolution.

## Color scheme and client fallback

The HTML head uses the following combination:

```html
<meta name="color-scheme" content="light only">
<style>
  :root { color-scheme: light dark; }
  @media (prefers-color-scheme: dark) { /* dark palette */ }
  [data-ogsc] …, [data-ogsb] … { /* Outlook dark palette */ }
</style>
```

`light only` asks Gmail's mobile apps to leave the light mail unchanged for Google accounts. The `:root` declaration lets Apple Mail use Lumio's dark palette despite that meta tag. The media query and Outlook selectors apply the dark values in supporting clients. The layout does not use `supported-color-schemes`. Gmail with a non-Google account and classic Outlook for Windows can still recolor the mail, so the layout follows all eight fallback rules:

1. **Start in light mode and supply a dark palette.** Clients without dark-style support have a complete light layout; clients that support it can select Lumio's colors.
2. **Avoid pure white and pure black.** The light page uses `#fffffe`; clients that specially replace `#ffffff` or `#000000` are less likely to produce mismatched surfaces.
3. **Keep readable content as HTML text.** Even “Lumio” beside the logo is text, so client recoloring can preserve its contrast. Words baked into an image would keep their original color.
4. **Use images that work on light and near-black backgrounds.** The solid mint logo tile, brand-colored platform marks, and mid-tone chart lines remain visible when a client changes the surrounding surface. Avoid dark or white text on transparent images.
5. **Set each page background twice.** `body`, wrapper table, and content cell each carry both `bgcolor` and an inline background style so mail clients recolor the same surface consistently.
6. **Do not encode meaning with color alone.** Category and warning words remain present when a client shifts mint, amber, or red.
7. **Treat hairlines as decoration.** A full inversion can nearly erase fine lines, so the text order and labels still communicate the content without them.
8. **Make buttons filled table cells with text.** The action remains readable if image rendering or blend modes fail; the layout does not use the Gmail `mix-blend-mode` trick.

The light and dark color tables and measurements are documented beside the layout in `brief.stpl`, derived from `shared/ui/src/globals.css`. The light primary text `#147b5e` and dark red text `#dd5f5f` are mail-specific contrast corrections. The letter layout is at most 600 px wide, with a 24 px logo and a text wordmark; category color appears as a short line and a word. Lines separate details and metrics. A note uses a colored edge, and the button has an 8 px radius.

## Images, MIME, and inbox preview

The logo, platform marks, and chart legend dots are PNGs attached by CID. Editable SVG sources and generation notes are in `assets/email/README.md`; the compiled PNGs are in `crates/lo-email/assets/`. The stream summary attaches one transparent 1120 × 260 PNG for both themes, displayed at 560 × 130; axes, range, and legend labels are HTML text. It uses mid-tone viewer and chat lines that remain readable on light and dark backgrounds. Images are embedded rather than fetched from a server. The provider does not use an open-tracking pixel or click tracking.

Every mail supplies a separate, hidden inbox preview text and a `text/plain` body generated from the same blocks. SMTP delivers `multipart/alternative` with plain text and a `multipart/related` HTML part holding the CID images; SendGrid sends the same content types with inline attachments. A mail that carries a file (the PDF of a developer's self-billed credit note, `lo_email::credit_note`) wraps that tree in `multipart/mixed` with one `Content-Disposition: attachment` part per file (`Email::attachments`, `EmailService::send_rendered_with_attachments`); SendGrid gets it as an attachment with `disposition: attachment`. The preview text is not the first visible paragraph. The subject and preview text are filled with the same caller values as the body.

## Footer and notification preferences

The footer contains a localized reason for the message plus privacy, terms, and imprint links. A “Manage notifications” link appears only when the caller passes `Notice::manage_url` or the corresponding `TemplateContext` field. Callers obtain that URL from `apps/api/src/services/notification_types.rs::manage_url`: it returns the settings page only for a registry type that is not locked. Locked and unknown types, and direct transactional mails without a preference key, have no manage link. The registry is also the source for the notification matrix; do not keep a second opt-out list in the email crate. See [Notification preferences](/features/notifications#notification-preferences).

## Preview and verification

From the repository root, generate a local index with each kind in both languages, four views, and a plain-text file per kind:

```text
cargo run -p lo-email --example preview -- /tmp/lumio-mail-preview
```

Open `index.html` in that directory. The views are light, Lumio dark, simulated Gmail iOS inversion, and simulated Gmail Android recoloring. The light view is also the expected Gmail view when `light only` is honored. The simulations are approximations; a real device is needed to verify client behavior.

Sending is an explicit manual step. `--send-to` sends the sample mails through the email provider configured in `apps/api/config`; `--lang` limits sending to `de` or `en` (default `de`, or use `all`), and `--config-dir` selects another configuration directory:

```text
cargo run -p lo-email --example preview -- /tmp/lumio-mail-preview --send-to address@example.com --lang de
```

## Adding a mail

1. Add its `NoticeKind` and DE/EN copy in `notices.rs`, including subject, preview text, category, body, button, and footer reason. For a typed template mail, add the corresponding `TemplateContext` input and map its values to the same blocks.
2. Supply every placeholder from the caller as plain text. Preserve the security-mail rule: no codes, IP addresses, or link that itself triggers an action in a security notice. Confirmation and reset mails carry their required token link and a text fallback beneath the button.
3. Choose reusable blocks in `brief.rs` and keep the color-scheme head and all eight fallback rules intact. Add images as CID PNGs with sources under `assets/email/`; never put essential words into an image.
4. Resolve the recipient language and any date/time at the caller. Use `notification_types::manage_url` only for an unlocked registry type; leave direct and locked mail without a manage link.
5. Extend the mail tests so **every kind renders in DE and EN** and the required head, preview text, `text/plain`, localized footer, and security exclusions hold. Verify subjects and preview text against the reference copy. Generate the preview and inspect light, dark, mobile, and both recoloring simulations; use `--send-to` for real-client checks when appropriate.

---

## Developer Guide / Channel Connections & OAuth Scopes

Source: https://docs.lumio.vision/developer-guide/channel-connections-oauth-scopes

# Channel Connections & OAuth Scopes

Channel connections are the mechanism by which Lumio accesses platform APIs on behalf of a user's channel. Each connection stores encrypted OAuth tokens and the scopes that were granted during authorization.

## One Connection Per Platform

Each account can have **one channel connection per platform**. This is enforced by a `UNIQUE (account_id, platform)` constraint on the `channel_connections` table. `app_credentials` and `bot_connections` carry the same constraint.

Platforms with a channel-connection OAuth config (`get_oauth_config()`): **Twitch**, **YouTube**, **Kick**, and **Spotify**. Discord and Shopify are known platforms too, but they have no `channel_connections` surface -- Discord is login + bot + integration, Shopify is integration only (`PLATFORMS` in `apps/api/src/platforms.rs`). Shopify's OAuth install is not a channel connection either: it stores its expiring offline token in `integration_configs` and requests the Admin API scopes `read_orders,read_products,read_legal_policies` from `[shopify] scopes` (see [Shopify](../features/shopify.md)).

Discord's separate global-bot invite uses `get_bot_oauth_config("discord")` with scopes `bot applications.commands identify`, `integration_type=0`, and permissions bitmask `2147576832` (View Channels, Send Messages, Manage Messages, Embed Links, Read Message History, Use Application Commands). `identify` makes Discord return a verifiable server in the code exchange; the resulting user token is revoked and never stored. The callback is `/api/connections/oauth/discord/callback`. Discord has no channel app or account-owned bot app.

## Channel Identity Columns: `channel_name` vs `channel_login` (ZAF-1461)

`channel_connections` carries **two** name columns, set from the platform's channel-info fetch on connect:

- **`channel_name`** — the **display name** (Twitch `display_name`, YouTube channel title, Kick/Spotify display). Shown in the UI. May be **localized** (`こさむん`).
- **`channel_login`** — the **login / handle** (Twitch `login`, Kick slug). The URL-safe, lowercase spelling used for IRC `JOIN`, IRC-tag routing, the stream-history freeze, and profile URLs. `NULL` for platforms without a login concept (YouTube/Spotify).

Do **not** conflate them. A Twitch `display_name` can be non-ASCII, so `JOIN #<display_name>` is never honoured (`to_lowercase` is a no-op on CJK) — the bot goes silently absent while EventSub (keyed on `broadcaster_user_id`) keeps the channel looking healthy. Consumers read `channel_login` and fall back to `channel_name` only for **legacy rows** the boot backfill has not filled yet.

**Backfill.** Rows stored before P6 have a `NULL` `channel_login`. A best-effort boot backfill (`backfill_missing_channel_logins`) fills them from `platform_chat_messages.channel_name` (where the EventSub ingest already wrote `broadcaster_user_login`, so no Helix call is needed for any channel with chat history), then via Helix `GET /users` for the remainder. The upsert `COALESCE`s `channel_login`, so a corrected value survives every later reconnect.

## Credential Source by Platform

Channel connections are not all issued by the same OAuth app source. `CredentialResolver` chooses the source for a new connect, and the resulting value is stored on `channel_connections.credential_source`:

| Platform | Channel default | Notes |
|----------|-----------------|-------|
| Twitch | `system` | Uses `twitch_channel_client_id` / `twitch_channel_client_secret` when set; may fall back to the Twitch login pair because Twitch supports multiple redirect URIs per app. |
| Kick | `system` | Uses `kick_channel_client_id` / `kick_channel_client_secret` when set; falls back to the Kick login pair (`kick_client_id` / `kick_client_secret`) with a one-time warning when unset (ZAF-1493) — Kick accepts up to 10 redirect URIs per app, so the login app can also register the channel callback. |
| YouTube | `account` | BYO Google Cloud OAuth client; quota, verification, and the 7-day Testing refresh-token rule stay with the customer app. |
| Spotify | `account` | BYO Spotify app; Spotify Development Mode limits and registered-user rules stay with the customer app. |

If a `system` platform has no global key pair configured, new connects fail safe to `account` and use the legacy per-account `app_credentials` path. Existing rows keep refreshing with whichever source minted them; changing `[platform_credentials]` affects only future connects.

## OAuth Scopes by Platform

Scopes are defined statically in `apps/api/src/platforms.rs` (`get_oauth_config()`). They are requested during the authorization flow. The Connections group of the settings window can request the current scopes again by reconnecting the **same** channel account; a disconnect is not required for an ordinary scope grant.

### Twitch (33 scopes)

| Scope | Purpose |
|-------|---------|
| `channel:read:subscriptions` | Read subscriber list and events |
| `channel:read:redemptions` | Read channel point redemptions |
| `channel:manage:redemptions` | Manage channel point redemptions |
| `channel:read:hype_train` | Read hype train events |
| `channel:read:polls` | Read poll data |
| `channel:manage:polls` | Create and manage polls |
| `channel:read:predictions` | Read prediction data |
| `channel:manage:predictions` | Create and manage predictions |
| `channel:read:goals` | Read channel goals |
| `bits:read` | Read cheer/bits events |
| `moderator:read:followers` | Read follower list (used by ProfileService) |
| `moderator:read:suspicious_users` | Read suspicious user flags |
| `moderator:manage:suspicious_users` | Update suspicious user treatment |
| `moderator:manage:banned_users` | Ban and unban users |
| `channel:bot` | Send chat messages as the channel bot |
| `user:read:chat` | Read chat messages |
| `channel:read:ads` | Read ad schedule |
| `channel:manage:raids` | Cancel raids (Lumio does not start raids) |
| `channel:moderate` | Moderate chat (delete, timeout) |
| `moderator:read:blocked_terms` | Read blocked terms list |
| `moderator:read:chat_settings` | Read chat settings |
| `moderator:read:unban_requests` | Read unban requests |
| `moderator:read:banned_users` | Read banned users list |
| `moderator:read:chat_messages` | Read chat messages as moderator |
| `moderator:read:warnings` | Read user warnings |
| `moderator:read:moderators` | Read moderator list |
| `moderator:read:vips` | Read VIP list |
| `moderator:read:chatters` | Read the connected chatters (Helix `GET /chat/chatters`) for the [chatter list](../features/chatter-list.md) |
| `moderation:read` | Read the moderator list (Helix Get Moderators) — the chatter list's moderator group |
| `channel:read:vips` | Read the VIP list (Helix Get VIPs) — the chatter list's VIP group |
| `moderator:manage:automod` | Receive held AutoMod messages and decisions through EventSub |
| `moderator:manage:blocked_terms` | Requested for later blocked-term management; Lumio does not use it yet |
| `moderator:manage:automod_settings` | Requested for later AutoMod-level management; Lumio does not use it yet |

**Extra params:** `force_verify=true` (forces re-authorization even if already granted)

Reconnect an existing Twitch channel once to grant these three scopes. The held-message queue needs `moderator:manage:automod`; the other two rights are requested in the same consent for future controls. Allow and Deny use the moderator's **login** grant instead, which also needs `moderator:manage:automod`: `ConnectionStatus.loginMissingScopes` / `login_missing_scopes` reports the login scopes the acting user's stored grant lacks (empty when unknown, nothing is missing or there is no grant; `openid`, `email` and `profile` are never reported), and a decision with a known scope set that lacks it fails with `login_scope_missing` before any Helix call. The backend's login-scope lists (`TWITCH_LOGIN_SCOPES`, `GOOGLE_LOGIN_SCOPES`, `KICK_LOGIN_SCOPES` in `apps/api/src/platforms.rs`) must match `apps/id/src/lib/providers.ts`; `apps/api/tests/login_scopes_drift.rs` fails on drift.

### YouTube (2 required scopes, 1 optional scope)

| Scope | Purpose |
|-------|---------|
| `https://www.googleapis.com/auth/youtube.readonly` (required) | Read channel, video, and live chat data |
| `https://www.googleapis.com/auth/youtube.force-ssl` (required) | Full YouTube Data API access (chat, comments) |
| `https://www.googleapis.com/auth/yt-analytics-monetary.readonly` (optional) | Read estimated revenue for channels in the YouTube Partner Program |

Google scopes are requested as full URIs, not short names.
The YouTube own-app guide has six steps. It displays the two required Data API scopes and the optional Analytics monetary scope from `channelOAuthScopes`. Its final step accepts a Google web-client JSON file, validates its callback address in the browser and extracts the client ID and secret. Declining the optional scope keeps the channel connected and does not populate `missing_scopes`.

**Extra params:** `access_type=offline` (enables refresh tokens), `prompt=consent` (forces consent screen)

> **The 7-day "Testing" refresh-token cap:**
> Channel connections use **per-account BYO Google credentials** - the customer's own Google Cloud OAuth client - so the customer's own consent-screen publishing status governs token lifetime. An **External** consent screen in publishing status **"Testing"** issues **refresh tokens that expire after 7 days** (the exception is name/email/profile-only scopes; because we request `youtube.readonly` + `youtube.force-ssl`, both sensitive, the rule always applies). When that refresh token dies the Token Refresh Worker sees `invalid_grant`, classifies it **terminal**, flags `reconnect_required`, and emails the owner - so in the product it looks like "YouTube keeps disconnecting every few days."
> 
> **Fix (customer-side):** set the OAuth client to **"In production"** (verification may be required for `youtube.force-ssl`), then reconnect once. Already-issued tokens stay 7-day-capped until reconnection. Check the OAuth client's **publishing status** before debugging the refresh path for a Google/YouTube "expires too fast" complaint. See [Connections → Reconnect Flags](../features/connections.md#reconnect-flags).

### Kick (8 scopes)

| Scope | Purpose |
|-------|---------|
| `user:read` | Read user profile information |
| `channel:read` | Read channel information |
| `events:subscribe` | Subscribe to real-time events |
| `chat:write` | Send chat messages |
| `moderation:chat_message:manage` | Delete chat messages |
| `kicks:read` | Read KICKs (`kicks.gifted` events, KICKs leaderboard) |
| `channel:rewards:read` | Read channel-point rewards and redemptions (`channel.reward.redemption.updated`) |
| `ads:read` | Read ad-break status for the stream-history revenue estimate; polled only for a live Kick stream and once at finalization |

`channel:rewards:write` is **not** requested: Lumio shows channel-point redemptions but does not manage rewards. Kick does not document whether it ties webhook subscriptions to these scopes. A Kick connection missing `ads:read` must be reconnected once for ad estimates; `missing_scopes` lists it, and a provider 403 removes it from the stored grant so the reconnect notice returns. The ad-break status is polled, not delivered by a webhook.


### Spotify (7 scopes)

| Scope | Purpose |
|-------|---------|
| `user-read-playback-state` | Read current playback state |
| `user-modify-playback-state` | Control playback (play, pause, skip) |
| `user-read-currently-playing` | Read currently playing track |
| `playlist-read-private` | Read private playlists |
| `playlist-read-collaborative` | Read collaborative playlists |
| `playlist-modify-public` | Modify public playlists |
| `playlist-modify-private` | Modify private playlists |

The Spotify own-app guide has five steps: confirm the intended account has Premium, create the app with Lumio's callback, allow the connecting account in Development Mode, copy the keys, and enter them in Lumio. The guide reads scope names from `channelOAuthScopes`. Spotify authorization ends 180 days after consent even when access tokens refresh; `ChannelConnection.authExpiresAt` / REST `auth_expires_at` exposes that date, and the hub prompts reconnection during the last 14 days. Reconnecting renews the authorization while retaining the app credentials.

## OAuth Connection Flow

The complete flow from source resolution to active worker:

```mermaid
sequenceDiagram
    participant User
    participant Dashboard as Dashboard (Next.js)
    participant API as API Server (Rust)
    participant DB as PostgreSQL
    participant Platform as Platform OAuth

    Note over User,Platform: Step 1: Authorize Channel
    User->>Dashboard: Click "Connect"
    Dashboard->>API: Get authorize URL
    API->>API: Resolve credential_source for (platform, channel)
    alt system source
      API->>API: Read global app from [auth] via CredentialResolver
      API->>API: Mint unified state handle
    else account source
      API->>DB: Read encrypted app_credentials
      API->>API: Mint legacy account state
    end
    API->>API: Build URL with scopes from get_oauth_config()
    opt platform requires PKCE (OAuth 2.1, e.g. Kick)
      API->>API: Mint code_verifier, store under oauth:pkce:{state} (600s)
      API->>API: Add code_challenge + code_challenge_method=S256 to URL
    end
    API-->>Dashboard: Redirect URL
    Dashboard->>Platform: Redirect to OAuth authorize
    Platform->>User: Show consent screen
    User->>Platform: Approve
    Platform-->>API: Callback with authorization code

    Note over API,DB: Step 2: Token Exchange
    API->>API: Reuse the pinned source from state
    opt platform requires PKCE
      API->>API: Take code_verifier from oauth:pkce:{state} (single-use)
    end
    API->>Platform: Exchange code (+ code_verifier) for access_token + refresh_token
    Platform-->>API: Token response
    API->>Platform: Fetch channel info (name, ID)
    Platform-->>API: Channel details
    API->>API: Encrypt tokens with AES-256-GCM
    API->>DB: Upsert into channel_connections with credential_source

    Note over API: Step 3: Start Worker
    API->>API: Start platform worker (EventSub, chat listener, etc.)
```

### PKCE (OAuth 2.1)

Providers that run OAuth 2.1 require PKCE (RFC 7636) on every authorize/exchange,
even for confidential clients that send a `client_secret`. This is opt-in per
platform via `PlatformOAuthConfig::requires_pkce` in `apps/api/src/platforms.rs`
(currently `true` only for **Kick**, channel and bot). When set, the authorize
step mints a 43-char base64url `code_verifier`, stores it in Redis under
`oauth:pkce:{state}` (10-minute TTL, single-use), and puts the S256
`code_challenge` on the authorize URL (`apps/api/src/routes/pkce.rs`). The token
exchange takes the verifier back and sends `code_verifier`. All six authorize
builders share `platforms::build_authorize_url`, so the PKCE parameters cannot
drift between the channel/bot/global-bot paths on GraphQL and REST. `refresh_token`
grants never carry PKCE.

## Scope Behavior

### Static Scopes

Scopes are defined at compile time in `get_oauth_config()`. `PlatformOAuthConfig.scopes` contains the base scopes; `optional_scopes` contains grants a feature can work without. `build_authorize_url` requests both lists on every connection. Google may still let the user untick an optional scope on its consent screen. YouTube's monetary Analytics scope is optional, while its two Data API scopes are base scopes.

### Changing Scopes

When the requested scope list grows, existing connections keep their old grant. Their tokens keep working for the scopes they hold, but the features behind the new scopes stay off until the owner **reconnects**: the normal connect flow (`authorizeChannel` / `GET /v1/connections/channel/{platform}/authorize`) requests the full current list, and the OAuth exchange upserts the existing row with the grant the provider returned. A user may decline an optional Google scope. No disconnect is needed.

After a reconnect the platform worker restarts with the new token. For Kick, the worker lists the existing event subscriptions and subscribes to every event not yet subscribed (`workers/kick.rs`), so events that needed the new scopes start arriving without further action. A reconnect records `account:connection_added` like a first connect (see [Audit Log](../features/audit-log.md)).

#### Chatter-list scopes (one reconnect)

The [chatter list](../features/chatter-list.md) needs three Twitch scopes, added together so existing connections get exactly **one** reconnect prompt: `moderator:read:chatters` (Get Chatters), `moderation:read` (Get Moderators) and `channel:read:vips` (Get VIPs). The older `moderator:read:moderators` / `moderator:read:vips` are EventSub `channel.moderate` scopes and are **not** accepted by the two list endpoints. Until the owner reconnects, the list reports `available = false`, `reason = "missing_scope"` and shows only people who write; without the moderator/VIP scopes the groups fall back to chat badges. The poller uses the **channel** connection's token (via `get_fresh_connection_token`), never a login token.

### Missing Scopes

Every channel connection exposes **`missing_scopes`**: the **base** scopes the platform's connect flow requests today that the stored grant lacks, in request order. A non-empty list means "reconnect to grant these". Optional scopes never enter this list, so declining YouTube Analytics does not leave a permanent warning on the connection card or in the connection notices. The revenue area checks the stored grant separately and can show `not_granted` there.

`channelOAuthScopes(platform)` / `GET /v1/connections/oauth-scopes/{platform}` returns `{platform, required, optional}` with full provider names. `required` is the base list, `optional` is the optional list, and authorization requests both. Both protocols use `feature:connections` and `connections:read` and return `Unsupported platform: X` for an unsupported platform.

| Protocol | Field | Guard |
|----------|-------|-------|
| GraphQL | `channelConnections { missingScopes }` (`[String!]!`) | `feature:connections` + `connections:read` (same as `scopes`) |
| REST | `GET /v1/connections/channel` → `missing_scopes` (`string[]`) | `feature:connections` + `connections:read` (same as `scopes`) |

Both protocols compute it with the same helper, `platforms::missing_scopes(platform, scopes)`, which returns the base `get_oauth_config().scopes` minus the stored grant. It is always a list, never `null`:

- **Nothing missing** → `[]`.
- **Grant never recorded** (`scopes` is `NULL` or empty — legacy rows, or a token response without a `scope` field) → `[]`. What such a token holds is unknown, so it is not reported as missing; this avoids a false "reconnect" on every old connection.
- **Platform without an OAuth config** → `[]`.

This is independent of `reconnect_required`, which flags a **dead** grant (terminal refresh failure). A connection with `missing_scopes` still works for everything its grant covers.

For optional features, `platforms::grant_has_scope` checks the actual stored grant; a `NULL` or empty grant does not prove that the optional scope is present. `platforms::granted_optional_scopes` records the optional scopes granted in the `account:connection_added` audit event's `optional_scopes_granted` metadata. See [YouTube Analytics setup](/getting-started/oauth-setup#youtube-analytics-api).

### Scope Storage

Granted scopes are stored in the `scopes` column of `channel_connections` as a nullable `TEXT[]` array. This records what was actually granted (which may differ from what was requested if the user denied specific scopes on platforms that support partial grants). `bot_connections` carries the same `scopes TEXT[]` column for the bot-side token. Extension chat moderation checks it before calling the provider: a Twitch bot row without `moderator:manage:banned_users` (ban, unban, timeout) or `moderator:manage:chat_messages` (delete), or a YouTube bot row without `youtube.force-ssl`, fails with `bot_scope_missing` without touching `reconnect_required`. An empty `scopes` value counts as unknown and is not blocked up front; a provider 401 then maps to the same code. The bot scope lists live in `get_bot_oauth_config()`, separate from the channel lists above.

## Credential Requirements

The required OAuth app source depends on the row's pinned `credential_source`:

| Source | Required for refresh | Token row |
|--------|----------------------|-----------|
| `account` | `app_credentials` for `(account_id, platform)` | `channel_connections` |
| `system` | Global config pair from `[auth]` via `CredentialResolver::system_pair` | `channel_connections` |

If an `account`-pinned connection loses its `app_credentials`, refresh cannot succeed. If a `system`-pinned connection has no global pair at refresh time, refresh fails clearly instead of silently using a different app.

If `channel_connections` are deleted, no API calls can be made for that platform.

Deleting `app_credentials` via the API is source-aware. `deleteAppCredentials` deletes an `account`-pinned channel connection together with the credentials it depends on. A `system`-pinned channel connection survives because it refreshes with the global Lumio app; only the stray account credential row is removed. Use `disconnectChannel` to drop only the channel connection and keep account credentials.

## Refresh Failure Handling

The Token Refresh Worker classifies every failed refresh (`apps/api/src/oauth.rs`, `classify_refresh_response` → `RefreshError`):

- **Terminal** (`invalid_grant` / `unauthorized_client`, or HTTP 400/401) - the grant is dead. `record_refresh_failure` sets `reconnect_required = true` on the row (channel/login/bot), which stops the hourly retry (the candidate query skips flagged rows) and, on the first transition, emits an audit event and sends the reconnect email.
- **Transient** (5xx / 429 / timeout / network, or an internal encrypt/persist error) - the refresh is retried on the 1-hour backoff; the flag is left untouched.

A reconnect never nulls a still-valid stored refresh token: `upsert_connection` uses `refresh_token = COALESCE(EXCLUDED.refresh_token, channel_connections.refresh_token)`, matching `bot_connections` and the login path. See [Connections → Reconnect Flags](../features/connections.md#reconnect-flags) for the user-facing surface and the Google 7-day "Testing" rule.

## Permissions

| Operation | Permission |
|-----------|-----------|
| Connection queries (list credentials / connections / status) | `connections:read` |
| `saveAppCredentials` | `connections:create` |
| `authorizeChannel` | `connections:create` |
| `deleteAppCredentials` | `connections:delete` |
| `disconnectChannel` | `connections:delete` |

Connection permissions are granular (`read` / `create` / `edit` / `delete`); there is no `connections:write`.

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/platforms.rs` | `get_oauth_config()` -- scopes, URLs, extra params per platform; `missing_scopes()` -- requested minus granted scopes; `PLATFORMS` capability table |
| `apps/api/src/db/connections.rs` | CRUD for `app_credentials`, `channel_connections` and `bot_connections` |
| `apps/api/src/graphql/connections.rs` | GraphQL mutations for save/delete credentials, authorize, disconnect |
| `apps/api/src/oauth.rs` | `OAuthTokens`, `get_fresh_connection_token()`, `get_fresh_oauth_token()`, `get_fresh_bot_token()` -- the only sanctioned refresh entry points |
| `apps/api/src/crypto.rs` | AES-256-GCM encryption/decryption |
| `apps/api/migrations/20260318000007_create_connections.up.sql` | Table definitions |

---

## Developer Guide / ProfileService

Source: https://docs.lumio.vision/developer-guide/profile-service

# ProfileService

The ProfileService is a unified profile enrichment system that combines local database records with live platform API data. It provides a single entry point for fetching user profiles across all supported chat platforms.

## Architecture

- **Crate:** `crates/lo-chat/src/profile_service.rs`
- **GraphQL:** `platformUserProfile(platform, platformUserId)` - guarded by `FeatureGuard("feature:multichat")` **and** `PermissionGuard("chat:userinfo")`
- **REST twin:** `GET /v1/chat/users/{platform}/{platform_user_id}`
- **Platforms:** Twitch (full), YouTube (partial), Kick (partial). Any other platform string returns the DB-only profile with no enrichment.

### Core Struct

```rust
pub struct ProfileService {
    pub redis: lo_cache::RedisClient,
    pub db: sqlx::PgPool,
    pub http: reqwest::Client,
    pub config: ProfileServiceConfig,
}

pub struct ProfileServiceConfig {
    /// Auto-enrichment interval for YouTube profiles (days). 0 = disabled.
    pub youtube_enrichment_interval_days: i64,
    /// Auto-enrichment interval for other platforms (days). 0 = disabled.
    pub enrichment_interval_days: i64,
}
```

The service is instantiated once at API startup and shared across all request handlers. It holds a Redis client for caching, a PostgreSQL connection pool for database access, a shared HTTP client for platform API calls, and the enrichment-interval config.

`ProfileServiceConfig` is populated in `apps/api/src/main.rs` from the `[profile]` config section:

```toml
[profile]
# YouTube enrichment costs Data API quota, so it is far less frequent.
youtube_enrichment_interval_days = 14
enrichment_interval_days = 1
```

Setting either to `0` disables automatic enrichment for that group - profiles then refresh only on an explicit `chat:refresh_user` request. ENV overrides: `LUMIO__PROFILE__YOUTUBE_ENRICHMENT_INTERVAL_DAYS`, `LUMIO__PROFILE__ENRICHMENT_INTERVAL_DAYS`.

## Data Flow

The `get_profile()` method follows a layered lookup strategy:

```mermaid
flowchart TD
    A["get_profile(account_id, platform, user_id, credentials)"] --> B{Redis cache?}
    B -->|Hit| C[Return cached profile]
    B -->|Miss| D[Load from platform_users DB table]
    D --> E{Enrichment stale?}
    E -->|Fresh| F["Cache with 4h TTL, return"]
    E -->|Stale| G{Credentials provided?}
    G -->|No| H["Cache DB-only profile (30min TTL)"]
    G -->|Yes| I{Circuit breaker open?}
    I -->|Open| J["Cache DB profile (15min TTL)"]
    I -->|Closed| K[Call platform API]
    K -->|Success| L[Merge enrichment into profile]
    L --> M[Persist to DB]
    M --> N["Cache with 4h TTL"]
    K -->|Failure| O[Record failure in circuit breaker]
    O --> P["Cache DB profile (30min TTL)"]

    style A fill:#3b82f6,color:#fff
    style K fill:#f59e0b,color:#fff
    style C fill:#10b981,color:#fff
```

### Step-by-step

1. **Redis cache check** -- Key: `lumio:user_profile:{account_id}:{platform}:{user_id}`. If found, return immediately.
2. **Database lookup** -- Query the `platform_users` table for the user's stored profile data (message count, mod/sub/vip status, ban info, etc.).
3. **Enrichment check** -- If the profile's `enriched_at` timestamp is null or older than the platform's max age, enrichment is needed. The default max age is **24 hours** for Twitch / Kick and **14 days** (`24 * 14` hours) for YouTube, because YouTube enrichment costs Data API quota. Both are overridable via `ProfileServiceConfig`.
4. **Circuit breaker check** -- If the circuit is open for this account+platform, skip API calls and return DB data.
5. **Cold-start lock** -- Before calling the platform, take a Redis `SETNX` lock (`PROFILE_LOCK_TTL_SECS = 5`). A concurrent caller that loses the race waits `PROFILE_LOCK_WAIT_MS = 250` ms and re-reads the cache instead of firing a duplicate API call, so a burst of chat messages from one new user does not stampede the platform API.
6. **Platform API call** -- Fetch additional profile data from the platform API using decrypted credentials.
7. **Merge and persist** -- Apply enrichment data to the profile, write enrichment fields back to the database, and reset the circuit-breaker failure counter.
8. **Cache** -- Store the profile in Redis with the appropriate TTL.

## Cache Keys and TTLs

| Key Pattern | TTL | Condition |
|-------------|-----|-----------|
| `lumio:user_profile:{account_id}:{platform}:{user_id}` | 4 hours (14400s) | Successful enrichment |
| `lumio:user_profile:{account_id}:{platform}:{user_id}` | 30 minutes (1800s) | DB-only fallback (no credentials or enrichment failure) |
| `lumio:user_profile:{account_id}:{platform}:{user_id}` | 15 minutes (900s) | Circuit breaker open |

## Circuit Breaker

The circuit breaker protects against cascading failures when a platform API is unavailable or rate-limited.

### Keys

| Key Pattern | Purpose |
|-------------|---------|
| `lumio:circuit:{account_id}:{platform}` | Cooldown flag -- existence means circuit is open |
| `lumio:circuit_count:{account_id}:{platform}` | Failure counter within the current window |

### Parameters

| Parameter | Value | Description |
|-----------|-------|-------------|
| Threshold | 5 failures | Number of failures before the circuit opens |
| Window | 60 seconds | Time window for counting failures |
| Cooldown | 300 seconds (5 min) | Duration the circuit stays open |

### Behavior

1. Each enrichment failure calls `record_failure()`, which increments `lumio:circuit_count:{account_id}:{platform}`.
2. On the first failure, the counter gets a 60-second TTL (the window).
3. When the counter reaches 5, the circuit opens:
   - A `lumio:circuit:{account_id}:{platform}` key is set with a 300-second TTL.
   - The counter is reset.
4. While the circuit is open, all enrichment attempts for that account+platform are skipped.
5. After the cooldown expires (key TTL), the circuit closes automatically.

## Platform Enrichment Data

Each platform provides different enrichment fields. `enrich()` dispatches to one boxed enricher per platform (`Box::pin`), so a lookup carries only the future of the platform it calls, not the largest one. Keep new platform arms boxed; `enrichment_futures_stay_within_budget` checks it.

### Twitch (Full Enrichment)

| Field | Source |
|-------|--------|
| `avatar_url` | `profile_image_url` from Helix Users API |
| `description` | User bio from Helix Users API |
| `broadcaster_type` | `"partner"`, `"affiliate"`, or `""` |
| `account_created_at` | User creation date |
| `is_follower` | Checked via Helix Followers API |
| `followed_at` | Follower timestamp (if following) |
| `follower_count` | The user's own follower count: `total` of Helix `GET /channels/followers?broadcaster_id=<user>&first=1` (`HelixClient::get_follower_count`) |

Requires `moderator:read:followers` scope for follower checks. If the scope is missing, the follower check fails gracefully (non-fatal). The follower count needs no scope (Helix returns `total` to any user token) and is non-fatal as well; only the Helix Users call failing fails the Twitch enrichment.

### YouTube (Avatar, Bio, Account Age)

| Field | Source |
|-------|--------|
| `avatar_url` | Channel snippet thumbnails (high > medium > default) |
| `description` | Channel snippet description |
| `account_created_at` | Channel `publishedAt` date |

### Kick (Avatar, Bio)

| Field | Source |
|-------|--------|
| `avatar_url` | User `profile_picture` |
| `description` | Channel `channel_description` |

Two API calls, run concurrently and **independently**: one for the user profile (avatar), one for the channel info (description). `merge_kick_enrichment` logs each failure at `warn` with the HTTP status and keeps whatever the other call returned; only when both fail is the enrichment an error that counts toward the circuit breaker. Kick exposes no follower count, so `follower_count` stays `NULL`.


## ChannelCredentials

The `ChannelCredentials` struct decouples the ProfileService from the encryption module:

```rust
pub struct ChannelCredentials {
    pub client_id: String,           // From app_credentials (decrypted)
    pub client_secret: String,       // From app_credentials (decrypted)
    pub access_token: String,        // From channel_connections (decrypted)
    pub refresh_token: Option<String>, // From channel_connections (decrypted)
    pub platform_channel_id: Option<String>, // Broadcaster ID
}
```

The API layer is responsible for loading credentials from the database, decrypting them, and constructing this struct. The ProfileService never touches encryption directly.

## UnifiedProfile

The `UnifiedProfile` struct combines database fields with enrichment data:

| Field | Source | Description |
|-------|--------|-------------|
| `platform` | DB | Platform identifier |
| `platform_user_id` | DB | Platform-specific user ID |
| `username` | DB | Platform username |
| `display_name` | DB | Display name (may differ from username) |
| `avatar_url` | Enrichment | Profile picture URL |
| `color` | DB | Chat color |
| `is_mod` / `is_sub` / `is_vip` | DB | Role flags from chat messages |
| `badges` | DB | Platform badges (JSON) |
| `message_count` | DB | Total messages seen |
| `first_seen_at` / `last_seen_at` | DB | Activity timestamps |
| `is_banned` | DB | Ban status |
| `banned_at` / `banned_by` / `ban_reason` / `ban_type` | DB | Ban details |
| `timeout_expires_at` | DB | Timeout expiration |
| `user_treatment` | DB | `"none"`, `"suspicious"`, or `"monitored"` |
| `description` | Enrichment | User bio |
| `broadcaster_type` | Enrichment | Twitch broadcaster type |
| `is_follower` / `followed_at` | Enrichment | Follower status |
| `account_created_at` | Enrichment | Account age |
| `follower_count` | Enrichment | Own follower count (Twitch only; never overwritten by a failed lookup) |
| `enriched_at` | DB | Last enrichment timestamp |

## Key Files

| File | Purpose |
|------|---------|
| `crates/lo-chat/src/profile_service.rs` | ProfileService, ProfileServiceConfig, ChannelCredentials, UnifiedProfile, circuit breaker |
| `crates/lo-chat/src/platform_users.rs` | Database queries for `platform_users` table |
| `apps/api/src/config.rs` | `ProfileSettings` (`[profile]` config section) |
| `apps/api/src/main.rs` | Builds the shared `ProfileService` from config at startup |
| `apps/api/src/graphql/chat.rs` | `platformUserProfile` GraphQL resolver |
| `apps/api/src/routes/chat.rs` | `GET /v1/chat/users/{platform}/{platform_user_id}` REST twin |
| `crates/lo-twitch-api/` | Twitch Helix API client |
| `crates/lo-youtube-api/` | YouTube Data API client |
| `crates/lo-kick-api/` | Kick API client |

---

## Developer Guide / Emote Catalog

Source: https://docs.lumio.vision/developer-guide/emote-catalog

# Emote Catalog

The **emote catalog** is the durable store behind every emote lookup: the
`chat_emotes` table in the primary PostgreSQL, with Redis and an in-process LRU
demoted to caches in front of it. It is read on the chat-ingest path and written
whenever we learn about an emote.

The [7TV EventAPI listener](/developer-guide/seventv-event-listener) is a
writer for added and renamed channel emotes. It upserts those rows and
invalidates the channel map, while clearing the assembled channel hot cache
for every emote-set change. Removal does not delete catalog rows: the
upsert-only catalog may continue to resolve that shortcode until its cached
map expires. The hot-cache six-hour TTL is a fallback for missed events, not
the normal delay before a newly available emote appears in the picker.

## Why Postgres owns this

Before the catalog, every shortcode → image-URL mapping lived **only** in Redis
(`lumio:emotes:{platform}:{channel_id}`, today versioned as
`lumio:emotes:v4:{platform}:{channel_id}`, for the fetched third-party sets,
`lumio:yt:channel_emotes:{channel_id}` for YouTube observations). The only
persistence was the denormalised `emotes` JSONB on each chat message, with the
CDN URL frozen at write time.

That made a cache expiry indistinguishable from "this channel has no emotes",
which cost real data: the YouTube Data-API ingest path has no emote source of its
own, so a cold key meant the message was stored with `emotes = NULL` - and
because the mapping existed nowhere else, that loss was permanent and
unrepairable. With a durable catalog, an expiry only empties a cache.

The catalog lives in the **primary** Postgres, not TimescaleDB. It is a
slowly-changing dimension: keyed upserts, a unique constraint, point lookups, a
few thousand rows per channel. Hypertables win on append-only time series with
range scans; time partitioning buys nothing here, would cost the unique
constraint, and would put reference data in the wrong pool for ingest and config
reads.

## The three tiers

```
LruCache (in-process, ~60s)  ->  Redis (6h)  ->  Postgres chat_emotes
```

| Tier | Purpose | Miss behaviour |
|------|---------|----------------|
| **1 - LRU** | Removes the per-message Redis round-trip. Chat ingest previously did a full `GET` plus a full-map JSON deserialize for *every* inbound message. | Falls through to Redis |
| **2 - Redis** | Shared hot cache across API instances. A **present but empty** map is a hit, not a miss - that is what stops an emote-less channel from querying Postgres on every message. | Falls through to Postgres |
| **3 - Postgres** | The truth. Result is written back into Redis (even when empty) and the LRU. | Returns an empty map |

Implemented by `lo_chat::emote_catalog::EmoteCatalog` in
`crates/lo-chat/src/emote_catalog.rs`, modelled on the existing two-tier
`MembershipBadgeCache` (`crates/lo-chat/src/youtube_badges.rs`).

### Fail-open at every tier

Neither an unreachable Redis nor a Postgres error may drop or delay a chat
message - only leave it un-enriched. Two consequences worth knowing:

- A read that **cannot reach Postgres** is deliberately *not* cached. Caching an
  error as "no emotes" would pin a wrong answer for a whole TTL window, and
  Postgres being unreachable already means chat rows are not being written.
- During a Redis outage the LRU still bounds the load to one Postgres query per
  channel per LRU TTL, rather than one per message.

### Writes invalidate, they do not merge

When `EmoteCatalog::upsert` changes something in Postgres, it then **deletes**
the Redis key for every channel it touched, so the next reader rebuilds from the
truth. The previous read-modify-write against Redis was not atomic and could
lose entries when two workers observed the same channel concurrently. A write
that changes nothing invalidates nothing - see [A write that changes nothing is
not a write](#a-write-that-changes-nothing-is-not-a-write) below.

Because a `DEL` cannot reach another process's LRU, the LRU TTL is also the
worst-case staleness for a freshly observed emote across API instances - which
is why it is short (60 s) on a store that otherwise changes slowly.

### A write that changes nothing is not a write

The upsert's `DO UPDATE` carries a `WHERE`: a row is rewritten only when a field
a reader can observe actually changed (`url`, `animated`, `owner_id`,
`platform`) or when `last_seen_at` has gone stale by more than an hour.
Everything else is skipped by Postgres and reported back as `0` rows affected,
and **invalidation is keyed off that count** - an upsert that changed nothing
leaves the Redis map and the LRU entry alone.

This matters because of how often the write path runs. Chat ingest upserts the
emotes it saw once per poll batch (every ~10 s per live channel), so in steady
state it is re-stating rows Postgres already holds. Unconditionally, each of
those batches would:

- write a new tuple version plus WAL and leave a dead tuple for autovacuum, for
  every emote, forever. The row count stays flat - that is what the unique key
  buys - but the *write* volume would track stream-hours, which is the one
  quantity here that grows without bound; and
- `DEL` the channel's Redis map and drop its LRU entry, so the 6 h and 60 s TTLs
  would be discarded every 10 s on exactly the channels busy enough to need
  them.

The cost of the guard is that `last_seen_at` is accurate only to the hour. Every
reader is fine with that: it is a liveness signal, used as the provider
tie-break when two providers host the same shortcode, not a per-message
timestamp - chat messages already carry their own.

## Schema

```sql
CREATE TABLE chat_emotes (
    id                UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    platform          TEXT NOT NULL,        -- where it is usable
    provider          TEXT NOT NULL,        -- who hosts it
    channel_id        TEXT,                 -- NULL = global set
    provider_emote_id TEXT NOT NULL,
    name              TEXT NOT NULL,
    url               TEXT NOT NULL,
    animated          BOOLEAN NOT NULL DEFAULT FALSE,
    owner_id          TEXT,
    source            TEXT NOT NULL,        -- 'api_fetch' | 'observed'
    first_seen_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    last_seen_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
    CONSTRAINT chat_emotes_key UNIQUE NULLS NOT DISTINCT
        (provider, channel_id, provider_emote_id, name)
);
```

`platform` vs `provider` are genuinely different axes: a 7TV emote is **hosted**
by 7TV (`provider = '7tv'`) but **usable** in a Twitch channel
(`platform = 'twitch'`). `provider` values match `lo_chat::EmoteProvider`.

Three details that are easy to get wrong:

- **`UNIQUE NULLS NOT DISTINCT`** (PostgreSQL >= 15; dev and CI run `postgres:18`). The global sets all carry `channel_id IS NULL`; under the
  default `NULLS DISTINCT` every re-fetch would insert a fresh row forever.
- **The upsert must name the constraint** - `ON CONFLICT ON CONSTRAINT
  chat_emotes_key`. A `NULLS NOT DISTINCT` constraint **cannot** be inferred from
  a column list.
- **`provider_emote_id` is part of the key on purpose.** A *renamed* emote that
  keeps its id becomes a second row, so both shortcodes stay resolvable - which
  is what chat history needs. A re-fetch of the same `(id, name)` pair is an
  idempotent update - and, per [A write that changes nothing is not a
  write](#a-write-that-changes-nothing-is-not-a-write), usually no write at all.
  `first_seen_at` is never touched.

### `channel_id` means "usable here", not "owned by"

For a YouTube observation, `channel_id` is the **broadcaster whose chat the
emote appeared in**, and the channel that *hosts* it goes in `owner_id`.

This fixes a long-standing read/write asymmetry: the old Redis write keyed on the
hosting channel (the `emojiId` prefix) while the read keyed on the broadcaster
being polled. Those coincide only for a broadcaster's own emotes, so any emote
hosted elsewhere - a viewer pasting another channel's custom emote - was written
under a key nobody ever read. `channel_id` now answers exactly the question the
ingest asks: *which emotes can appear in this channel's chat?*

## Adding a writer

1. Build `lo_chat::EmoteRow` values. Set `source` to
   `SOURCE_API_FETCH` (fetched from a provider API) or `SOURCE_OBSERVED`
   (seen in-band in a chat message).
2. Persist and invalidate:
   - A caller that owns a long-lived `EmoteCatalog` (the chat-ingest worker) calls
     `EmoteCatalog::upsert(&rows)` - it also pops the in-process LRU.
   - A request-path caller with no catalog instance (the `emotes` query) calls the
     standalone `emote_catalog::upsert_and_invalidate(db, redis, &rows)`.

   Both dedupe within the batch, do a single `UNNEST` round-trip regardless of
   batch size, and **invalidate (`DEL`) the affected channel map keys** rather
   than merging.
3. Treat the result as **best-effort**: log a failure, never propagate it into
   the path that produced the rows.

Rows are written only on a set fetch or an observation batch - never per chat
message. `platform_chat_messages.emotes` remains the usage log that
`db::top_emotes` aggregates; the catalog is the definition store.

### Catalog writers

| Writer | `source` | `channel_id` | Entry point |
|--------|----------|--------------|-------------|
| **Emote-set API fetch** - the `emotes` query fetching Twitch/YouTube/Kick/7TV/FFZ/BTTV sets | `api_fetch` | the channel for a channel set, `NULL` for a provider's global set | `services::emotes::resolve_channel_emotes` → `upsert_and_invalidate` |
| **YouTube observation** - shortcodes seen in InnerTube chat | `observed` | the broadcaster whose chat it appeared in (host in `owner_id`) | `workers::youtube` → `EmoteCatalog::upsert` |
| **7TV EventAPI listener** - added and renamed channel emotes | `api_fetch` | every connected channel using the active set | `workers::seventv_events` → `upsert_and_invalidate` |

A provider's **global** set must be collected with `channel_id = None`, not the
channel being resolved. This is why the native Twitch fetch is split into
`fetch_twitch_channel_emotes` and `fetch_twitch_global_emotes` rather than one
combined call: merging them would write every global Twitch emote once per
channel, inflating the catalog and defeating the `NULL`-channel global read.

**Kick writer.** For `platform = "kick"` the fetch also writes Kick's **native**
sets from the undocumented `kick.com/emotes/{slug}`
(`services::emotes::fetch_kick_emotes`): the channel set with `channel_id` = the
Kick broadcaster id, Kick's `Global` and `Emojis` sets with `channel_id = NULL`,
all `provider = "kick"`, `source = api_fetch`, URL
`https://files.kick.com/emotes/{id}/fullsize`. The slug comes from
`channel_connections.channel_login` (fallback: official
`GET /public/v1/channels?broadcaster_user_id=`). The catalog does not store
`subscribers_only` or the set `section`: `subscribers_only` exists only in a
fresh fetch response, and the `section` of a catalog-rebuilt Kick row is derived
from its scope (see below). The fetch is fail-open — a blocked or changed
endpoint writes nothing and leaves the catalog as it was.

Every Kick fetch outcome is counted in
`chat_emote_set_fetch_total{platform="kick",outcome}` with `outcome` one of
`ok`, `empty`, `not_found`, `challenge`, `unrecognised`, `error`, `no_slug`, and
every non-`ok` outcome is also logged at `warn` with the slug and HTTP status
(the slug and status stay in the log, never in a metric label). `challenge`
means Cloudflare answered instead of Kick: a response flagged
`cf-mitigated: challenge`, or an HTML page served with `200`. A run of
`challenge` (or `error` with status `403`) on the production host means Kick's
bot protection is blocking the server's IP.

Channel-set rows carry `owner_id = "kick:<user id>"`, the broadcaster from the
set's `user` object, namespaced so a Kick owner can never collide with a
numeric Twitch owner id. `Global`/`Emojis` rows have `owner_id = NULL`. The
catalog does **not** store the owner's name or avatar: those are only on the
fresh fetch (and in the Redis hot cache with it), so a response rebuilt from the
catalog returns `owners: null` and the emote library falls back to its generic
"Kick Channel" label.

Kick has no counterpart to Twitch's `chat/emotes/user` (the emotes of every
channel the viewer is subscribed to). The Kick website gets that list through
the viewer's session cookie, and Lumio never sends its OAuth token to
undocumented Kick hosts, so no writer adds other channels' Kick emotes.

The native Twitch fetch additionally needs a Helix bearer token, minted from the
`twitch` system credential as an app access token - see
[Emotes → The Twitch app access token](../features/emotes.md). Without a
mintable token both Twitch fetches are skipped, and the catalog simply keeps
whatever the other providers wrote.

### Serving the catalog on an upstream outage

The `emotes` query is also a **reader** of the catalog, at two granularities
(`services::emotes::assemble_channel_emotes`):

| What failed | Served | Hot-cache TTL |
|-------------|--------|---------------|
| Nothing | the fresh fetch | 6 h |
| Only the **platform-native** provider (Kick's own sets; Twitch Helix channel or global) | that provider's catalog rows via `emote_catalog::load_channel_provider_emote_sets(db, platform, channel_id, provider)`, first in order, replacing whatever that provider returned, plus the fresh third-party sets | 5 min |
| Every provider (a total upstream outage) | the whole catalog via `emote_catalog::load_channel_emote_sets(db, platform, channel_id)` | 5 min |
| The catalog read itself | whatever was fetched | not cached |

Both loaders return the channel's rows **plus** the platform's global
(`channel_id IS NULL`) rows, grouped by provider into the full `EmoteSet` shape.
This is what stops an outage from wiping a channel's emote map - including the
common case where only Kick's undocumented endpoint is blocked while 7TV, BTTV
and FFZ still answer, which previously dropped every Kick set from the menu.

Catalog-rebuilt **Kick** rows get their menu `section` back from the scope: a
channel-scoped row is `channel`; a global row is `emojis` when its name starts
with `emoji` (every entry of Kick's `Emoji` set does, e.g. `emojiAngel`) and
`global` otherwise (`emote_catalog::kick_catalog_section`). So the menu keeps its
**Channel / Kick Global / Kick Emojis** sections in degraded mode too.

A degraded response is cached for **5 minutes**, not 6 hours, so a transient
failure (a Cloudflare challenge, a timeout) is retried within minutes instead of
being pinned. Like every catalog path it is fail-open: a Postgres error degrades
to what was fetched and is never pinned in the hot cache.

### The hot-cache key is versioned

The assembled response is cached in Redis under
`lumio:emotes:{version}:{platform}:{channel_id}` (currently `v2`,
`EMOTE_CACHE_VERSION` in `services/emotes.rs`). **Bump the version whenever the
cached `Vec<EmoteSet>` changes shape or content rules** - a new field, a
provider added to or removed from a platform, a new section. Nothing else
replaces a present key before its TTL runs out, and no user-facing control can
bust it (the emote library's Refresh clears only the browser's `localStorage`),
so an unversioned key keeps serving the previous build's response for up to
6 hours after a deploy.

### Read paths beyond ingest (ZAF-578)

Two more callers read the catalog. None writes; all are best-effort and
fail-open - an unavailable catalog only leaves a message or report un-enriched.

| Reader | What it reads | Why |
|--------|---------------|-----|
| **Kick chat send** (`services::chat_send::send_kick`) | `load_channel_provider_emote_sets(db, "kick", broadcaster_id, Kick)` | Kick renders an emote only from `[emote:ID:NAME]` markup, so each outgoing word matching a known Kick emote name is converted before sending. Once per send, not per message ingest. |
| **Stream-report read path** (`services::history::service`) | `resolve_emote_urls(db, &[(provider, name)])` | Fills a missing image on a frozen `top_emotes` entry at read time; an entry that already has a `url` keeps its snapshot. Covers the report, exports, share page and summary e-mail. |

Two ingest fixes ride along:

- **Kick ingest needs no catalog.** Kick's webhook carries each emote inline as
  `[emote:ID:NAME]` in `content`, so `services::kick_emotes::extract_kick_emotes`
  builds `{id, name, url, provider: "kick", animated}` per occurrence straight
  from the marker, with the URL frozen from the id — no catalog lookup on the
  ingest path. Kick emotes therefore always carry a `name` and a `url` and rank
  in `db::top_emotes` like Twitch's.
- **URL freshness on the renderer.** The chat renderer
  (`message-content.tsx` / `emote-text.tsx`) prefers the **live** channel-map URL
  over the frozen per-message one when the name matches, so a rotated CDN URL
  renders again; the frozen URL is the fallback. A name with no usable URL on
  either side renders as plain text, not a broken image.

### Read through the tiers, not around them

`load_channel_map` and `load_channel_emote_sets` **are tier 3** - they go
straight to Postgres. Reach for them only where the read happens once per
connection or per request, or from inside the catalog itself.

Anything on a **per-message** path must go through an `EmoteCatalog` so the LRU
can absorb it. In a request handler that means `state.emote_catalog`, which is
built once in `main.rs` and shared by every route; workers build their own
(`workers::youtube`). Calling `load_channel_map` per message instead silently
converts the hottest path in the API into one Postgres round-trip per message -
the catalog still answers correctly, so nothing fails and nothing is logged; only
the write-ahead log and the connection pool notice.

A second `EmoteCatalog` is not a correctness problem: tier 1 is per-instance and
short-lived by design, and invalidation is a Redis `DEL` that no LRU sees anyway
(see [Writes invalidate, they do not merge](#writes-invalidate-they-do-not-merge)).

## Privacy

Catalog rows hold only **public chat metadata** - the same image URL every
viewer's browser loads, fetched from an open API for the third-party sets. There
is deliberately **no `account_id`**: a tenant boundary on public reference data
would duplicate every row per account and make the global 7TV/BTTV/FFZ sets
unmodellable. Read paths that need a tenant-specific answer constrain by the
channel ids they already hold.

For the same reason the catalog emits **no audit event** - see the
[audit-events guide](./audit-events.md) for what does qualify.

The YouTube GDPR erasure path (`services::youtube_memberships`) **does not touch
the catalog** - it deletes neither `chat_emotes` rows nor the emote cache key.
The catalog is deliberately left intact, for the reasons in the note below.

> **Emote catalog is out of Art. 17 scope and is not erased (ZAF-580):**
> The emote catalog is a **cross-channel reference directory**, so the YouTube GDPR
> erasure **leaves it untouched**. Two independent reasons:
> 
> 1. **Not personal data.** An emote shortcode plus its public CDN image URL is
>    channel content/branding reference data - the same URL every viewer's browser
>    loads - with no message text, no `account_id`, and no behavioural or profile
>    linkage. It is **not personal data of the erased member that the right to erasure
>    (Art. 17) reaches** (founder's legal position, 2026-08-19: "unser emote
>    verzeichnis fällt nicht unter Artikel 17, und muss nicht gelöscht oder geleert
>    werden" - ZAF-580).
> 
> 2. **Shared across channels.** An emote hosted by channel A is pasted and stored
>    under channel B's chat (the row carries A's `owner_id`). Deleting rows by
>    `owner_id`/`channel_id` would strip the emote from **every other channel's**
>    historical messages and moderation reports, leaving them image-less. The delete
>    would actively break the cross-channel directory this catalog exists to be.
> 
> So the erasure path removes no catalog rows and clears no emote cache key. A
> standing integration test (`member_erasure_leaves_the_emote_catalog_intact` in
> `apps/api/tests/chat_emote_catalog.rs`) asserts the rows survive.
> 
> What Art. 17 **does** reach is erased in full, fatal-on-failure: Lumio's cached
> YouTube membership rows for the member (Redis, across every account) and, in
> the instructing account only, the member's chat PII (message text, identity, and
> badge/emote JSONB in `platform_chat_messages`) and the rest of their channel data
> (see [Chat › Erasure](../features/chat.md#erasure-gdpr-art-17)).

## Key files

| File | Purpose |
|------|---------|
| `apps/api/migrations/20260818000004_create_chat_emotes.{up,down}.sql` | Table, constraint, indexes |
| `crates/lo-chat/src/emote_catalog.rs` | `EmoteCatalog` three-tier read-through, `EmoteRow`, upsert / load, `upsert_and_invalidate`, `load_channel_emote_sets` / `load_channel_provider_emote_sets`, `kick_catalog_section`, `resolve_emote_urls` |
| `crates/lo-chat/src/youtube_emote_cache.rs` | YouTube `:shortcut:` tokenizer + message enrichment (storage-independent) |
| `crates/lo-chat/src/emotes.rs` | `parse_emotes` + `enrich_message_emotes_from_sets` |
| `apps/api/src/services/emotes.rs` | Emote-set API-fetch writer + outage fallback reader (`resolve_channel_emotes`, `assemble_channel_emotes`), shared by the REST route and GraphQL resolver |
| `apps/api/src/services/kick_emotes.rs` | Kick `[emote:ID:NAME]` parser (ingest) and encoder (send), Kick send-path catalog read |
| `apps/api/tsdb_migrations/20260930000001_kick_chat_emote_markup_backfill.{up,down}.sql` | One-off rewrite of Kick rows stored before the parser |
| `apps/api/src/state.rs` | `AppState::emote_catalog` - the shared catalog every request handler reads through |
| `apps/api/src/workers/youtube.rs` | Observation writer + both chat-ingest readers |
| `apps/api/src/services/history/service.rs` | Report read-time image fallback (`backfill_emote_urls`) |
| `apps/api/src/services/youtube_memberships.rs` | GDPR member erasure (membership + chat PII); leaves the catalog intact |
| `apps/api/tests/chat_emote_catalog.rs` | Phase 1 integration tests (`common::test_db()`) |
| `apps/api/tests/emote_catalog_writers.rs` | Phase 2 integration tests: API-fetch writer + outage and per-provider (native) fallback, degraded TTL, Kick section restore (`common::test_db()`) |
| `apps/api/tests/emote_report_fallback.rs` | Phase 3 integration tests: read-time report image fallback incl. fail-open (`common::test_db()`) |

## Testing

`apps/api/tests/chat_emote_catalog.rs` runs against the per-test Postgres
database `common::test_db()` clones from the migrated template. In agent runs, the injected `DATABASE_URL` selects
the host test Postgres; run `cargo test -p lumio-api --test chat_emote_catalog`.
`common::offline_redis()` points at a refused connection
and is fail-open, so tier 2 always misses and **every** `channel_map` call
exercises the cold-cache → Postgres fallback - which doubles as the standing
proof that emote lookup survives a full Redis flush.

Covered: upsert idempotency, URL drift, in-batch duplicates, empty batches,
renamed emotes, NULL-channel global rows, the cold read-through, the LRU hit,
write invalidation, platform and channel scoping, a fail-open Postgres error, and
the ZAF-580 ruling that a GDPR member erasure leaves the catalog intact.

`apps/api/tests/emote_report_fallback.rs` covers the Phase 3 read-time fallback:
`resolve_emote_urls` matching on `(provider, name)`, most-recent-row wins across
channels, unknown pairs absent, `backfill_emote_urls` filling a missing url while
leaving a frozen snapshot untouched, and the fail-open branch (an unreachable
catalog leaves the report unchanged rather than failing it). The Kick parser and
encoder are unit-tested in `apps/api/src/services/kick_emotes.rs` (Kick's doc
example verbatim incl. the inclusive positions, back-to-back identical emotes,
multibyte text, malformed markers, no-emote messages, send-side conversion); the
backfill migration in `apps/api/tests/tsdb_kick_emote_backfill.rs` (TimescaleDB,
gated on `RUN_TSDB_MIGRATION_TEST`; asserts SQL output == Rust parser output). The frontend URL-freshness precedence
is covered by `apps/web/__tests__/components/message-content-emote-url.test.tsx`.

---

## Developer Guide / Editor Live Sync

Source: https://docs.lumio.vision/developer-guide/editor-live-sync

# Editor Live Sync

The editor live sync system keeps widget and overlay editors in real-time sync across all connected sessions. When a mutation happens (upload, update, delete), every open editor tab sees the change immediately - without polling.

The system is built on top of the existing WebSocket + Redis pub/sub infrastructure. No additional services are required.

## Architecture

```
Mutation (REST or GraphQL handler)
         │
         ▼
  Redis pub/sub publish
  "lumio:sounds:{account_id}"  ←─ channel helper in lo-cache
         │
         ▼
  Event Relay Worker  (apps/api/src/workers/event_relay.rs)
  PSUBSCRIBE "lumio:sounds:*" → forwards to WsServer
         │
         ▼
  WebSocket channel "sounds:{account_id}"
  (gated by gate.rs: ChannelGate::AccountScoped + feature:sounds)
         │
         ▼
  useEditorPresence hook  (apps/web/src/hooks/use-editor-presence.ts)
  extraChannels: ["sounds:{accountId}"]
  onEvent: (channel, eventType, data) => { ... }
         │
         ▼
  Version counter incremented
         │
         ▼
  Child component re-fetches data
```

### Key files

| File | Role |
|------|------|
| `crates/lo-cache/src/pubsub.rs` | Channel name helpers (`channels::sounds`, `channels::events`, …) |
| `apps/api/src/workers/event_relay.rs` | Redis PSUBSCRIBE → WsServer relay; `CHANNEL_MAPPINGS` table |
| `crates/lo-websocket/src/gate.rs` | `channel_gate_for` and `channel_feature_for`; controls who may subscribe |
| `apps/web/src/hooks/use-editor-presence.ts` | Frontend WebSocket hook; `extraChannels` + `onEvent` API |

## Data Flow in Detail

### 1. Backend publishes an event

After any mutation, the REST and GraphQL handlers call `publish_json` with the structured payload:

```rust
let channel = lo_cache::pubsub::channels::sounds(&account_id.to_string());
let _ = state.pubsub.publish_json(&channel, &serde_json::json!({
    "event_type": "sound:list:updated",
    "data": { "action": "created", "sound_id": row.id }
})).await;
```

The publish must happen in **both** the REST handler (`routes/sounds.rs`) and the GraphQL handler (`graphql/sounds.rs`). This is required by the GraphQL/REST parity rule - a mutation on either protocol must produce identical side-effects.

### 2. Event Relay Worker forwards to WebSocket

The relay worker runs a `PSUBSCRIBE` loop over all entries in `CHANNEL_MAPPINGS`:

```rust
const CHANNEL_MAPPINGS: &[(&str, &str)] = &[
    ("lumio:sounds:*", "sounds:"),
    ("lumio:events:*", "events:"),
    // ...
];
```

When a message arrives on `lumio:sounds:{account_id}`, the worker maps it to the WsServer channel `sounds:{account_id}` and wraps it in the standard WebSocket envelope:

```json
{
  "type": "event",
  "channel": "sounds:{account_id}",
  "event_type": "sound:list:updated",
  "data": { "action": "created", "sound_id": "..." }
}
```

The `event_type` and `data` fields are extracted from the Redis payload before wrapping. This is the same envelope format used by overlay channels.

### 3. Channel gate controls who can subscribe

`channel_gate_for` in `gate.rs` determines the authentication requirement for each channel type:

```rust
"sounds" => ChannelGate::AccountScoped,
```

`AccountScoped` - not `Authenticated` - because Widget and Overlay tokens carry an account but no account-level RBAC, and must still reach only their **own** account's sound events.

`channel_feature_for` adds an optional feature-flag check:

```rust
"sounds" => Some("feature:sounds"),
```

Subscriptions are rejected if the gate fails or the feature flag is disabled. An unregistered channel type falls through to `ChannelGate::Unknown` and is always rejected - a new channel that is not added to **both** functions simply does not work.

### 4. Frontend subscribes via `useEditorPresence`

The widget editor subscribes to extra channels alongside the presence channel:

```typescript
const [soundsVersion, setSoundsVersion] = useState(0);

const handleEditorEvent = useCallback(
  (_channel: string, eventType: string) => {
    if (eventType === "sound:list:updated") {
      setSoundsVersion((v) => v + 1);
    }
  },
  []
);

const presence = useEditorPresence({
  resourceChannel: `widget:${initial.id}`,
  extraChannels: [`sounds:${accountId}`],
  onEvent: handleEditorEvent,
  wsUrl,
  wsToken,
});
```

The `onEvent` callback receives every event from every extra channel. Filter on `eventType` to handle only the events your component cares about.

### 5. Child components react to version changes

Components that display the synced data receive `version` as a prop and re-fetch when it changes:

```typescript
useEffect(() => {
  fetchSounds(0, search, false);
}, [version]);
```

Using a version counter rather than updating state directly from the event avoids stale-data and race-condition issues: the refetch always loads fresh data from the server.

## `useEditorPresence` API

```typescript
interface UseEditorPresenceOptions {
  resourceChannel: string;      // Primary presence channel (e.g. "widget:{id}")
  extraChannels?: string[];     // Additional channels to subscribe for data sync
  onEvent?: EditorEventHandler; // Called for every event on extra channels
  wsUrl?: string;
  wsToken?: string;
  enabled?: boolean;
}

export type EditorEventHandler = (
  channel: string,
  eventType: string,
  data: unknown
) => void;

interface UseEditorPresenceResult {
  connections: PresenceConnection[];
  isConnected: boolean;
}
```

**Implementation notes:**

- `extraChannels` and `onEvent` are excluded from the `useEffect` dependency array on purpose. Adding them would cause WebSocket reconnects every render cycle when callbacks are recreated. Wrap `onEvent` in `useCallback` with a stable dependency list.
- The hook maintains a single WebSocket connection shared between presence tracking and data channels. No extra connections are created for `extraChannels`.

## Event naming convention

| Pattern | Meaning |
|---------|---------|
| `{resource}:list:updated` | The collection changed (item created, updated, or deleted) |
| `{resource}:{action}` | A specific action on a single resource |

The `data` field carries `action` (`"created"` \| `"updated"` \| `"deleted"`) and the affected resource ID. Examples:

- `sound:list:updated` - sound library changed; subscribers should refresh the list
- `sound:play` - a sound was triggered for playback
- `sound:stop` - playback was stopped

## Channel gate types

When adding a new channel, choose the appropriate gate in `gate.rs`:

| Gate | When to use |
|------|-------------|
| `Public` | No authentication. Only for publicly readable data (e.g. login assignment codes) |
| `PublicWhenFeature("system:flag")` | Public while the named system flag is on; rejects with `FEATURE_DISABLED` when off. The channel id is **not** parsed as an account UUID |
| `Authenticated` | Any authenticated identity (not Anonymous). Note this does **not** check the account in the channel name - do not use it for account-scoped data |
| `AccountScoped` | Caller must be able to access the account id encoded in the channel name, but needs no specific permission. This is the right gate for account-scoped channels that Widget/Overlay tokens must reach, since those carry an account but no account-level RBAC |
| `Permission("resource:read")` | Account access **plus** the named account permission. Use for sensitive data visible only to team members with the right role |
| `UserPermission("resource:read")` | The named permission in the caller's **user-scoped** permissions; the channel id is not an account UUID |
| `WidgetToken` | Only widget tokens whose `widget_id` matches the channel |
| `OverlayToken` | Only overlay tokens whose `overlay_id` matches the resolved overlay |
| `ExtensionOwner` | Only the developer who owns the extension in the channel name |
| `Unknown` | The fallthrough - an unregistered channel type is always rejected |

`Authenticated` is a common mis-pick for account-scoped data: any authenticated identity could subscribe to another account's channel. `sounds` was moved to `AccountScoped` for exactly that reason.

Pair the gate with a `channel_feature_for` entry if the channel is behind a plan feature flag. Keep that mapping conservative - gating a Free-tier channel by mistake bricks the dashboard for Free users; when in doubt return `None` and rely on the per-resource feature checks in the REST/GraphQL handlers.

## Step-by-step: adding a new sync channel

Follow these steps to add real-time sync for a new resource type.

### Step 1 - Add a channel helper

In `crates/lo-cache/src/pubsub.rs`, add a helper to the `channels` module:

```rust
/// My resource events: `lumio:my-resource:{account_id}`
pub fn my_resource(account_id: &str) -> String {
    format!("lumio:my-resource:{}", account_id)
}
```

### Step 2 - Register the relay mapping

In `apps/api/src/workers/event_relay.rs`, add an entry to `CHANNEL_MAPPINGS`:

```rust
const CHANNEL_MAPPINGS: &[(&str, &str)] = &[
    // existing entries ...
    ("lumio:my-resource:*", "my-resource:"),
];
```

If the payload format is `{ "event_type": "...", "data": { ... } }`, add a matching branch in `run_relay_loop` to extract `event_type` and `data` and re-wrap in the standard envelope. See the `lumio:sounds:*` branch as the reference implementation.

### Step 3 - Add a channel gate

In `crates/lo-websocket/src/gate.rs`, add the channel type to both match arms:

```rust
// channel_gate_for
"my-resource" => ChannelGate::Authenticated,  // or Permission("my-resource:read")

// channel_feature_for
"my-resource" => Some("feature:my_resource"),  // omit if no feature flag
```

### Step 4 - Broadcast from your handlers

In your REST handler (`apps/api/src/routes/my_resource.rs`) and GraphQL handler (`apps/api/src/graphql/my_resource.rs`), publish after every mutation:

```rust
let channel = lo_cache::pubsub::channels::my_resource(&account_id.to_string());
let _ = state.pubsub.publish_json(&channel, &serde_json::json!({
    "event_type": "my-resource:list:updated",
    "data": { "action": "created", "id": row.id }
})).await;
```

Do this in **both** REST and GraphQL handlers. Skipping one creates a parity gap where mutations via one protocol are not reflected in open editors.

### Step 5 - Subscribe in the editor hook

In the editor component (`widget-editor.tsx` or `overlay-editor.tsx`), add the extra channel subscription:

```typescript
const [myResourceVersion, setMyResourceVersion] = useState(0);

const handleEditorEvent = useCallback(
  (_channel: string, eventType: string) => {
    if (eventType === "my-resource:list:updated") {
      setMyResourceVersion((v) => v + 1);
    }
  },
  []
);

const presence = useEditorPresence({
  resourceChannel: `widget:${initial.id}`,
  extraChannels: [`my-resource:${accountId}`],
  onEvent: handleEditorEvent,
  wsUrl,
  wsToken,
});
```

### Step 6 - Pass version to child components

Pass the version counter down to any component that displays the synced data:

```typescript
<MyResourceContent
  accountId={accountId}
  version={myResourceVersion}
/>
```

### Step 7 - Refetch on version change

In the child component, watch `version` with a `useEffect`:

```typescript
useEffect(() => {
  fetchMyResources(0, search, false);
}, [version]);
```

## What NOT to use for sync

The `extra` field in `WindowState` (managed by `getWindowExtra` / `setWindowExtra` in `shared/ui/src/floating-window.tsx`) is stored in `localStorage`. It is designed for **persisting UI preferences** across page reloads (e.g. volume level, filter state, column widths) - not for propagating data changes between users or tabs.

For anything that must be reflected on another user's screen, use the pub/sub + WebSocket channel pattern described above.

## All registered channels

The full set of Redis patterns registered in `CHANNEL_MAPPINGS`:

| Redis pattern | WsServer channel prefix | Gate | Feature flag |
|---------------|------------------------|------|--------------|
| `lumio:events:*` | `events:` | `Permission("events:read")` | - |
| `lumio:spotify:*` | `spotify:` | `Permission("spotify:read")` | - |
| `lumio:chat:*` | `chat:` | `Permission("chat:read")` | `feature:multichat` |
| `lumio:automations:*` | `automations:` | `Permission("automations:read")` | `feature:automation` |
| `lumio:overlay:*` | `overlay:` | `OverlayToken` | - |
| `lumio:widget:*` | `widget:` | `WidgetToken` | `feature:widgets` |
| `lumio:ext-storage:*` | `ext-storage:` | `ExtensionStorage` (storage read rule of the install) | `feature:extensions` |
| `lumio:sounds:*` | `sounds:` | `AccountScoped` | `feature:sounds` |
| `lumio:history:*` | `history:` | `Permission("history:read")` | `feature:stream_history` |

`gate.rs` knows more channel types than the relay maps - these are subscribable but are broadcast to from inside the API process rather than relayed from a Redis pattern:

| Channel type | Gate | Feature flag |
|--------------|------|--------------|
| `presence` | `PresenceScoped` (signed-in members of the owning account; a widget token only for its own widget) | - |
| `login-assignments` | `Public` | - |
| `ideas` | `PublicWhenFeature("system:ideas_hub_public")` | `system:ideas_hub` |
| `ext-logs` | `ExtensionOwner` | `feature:extension_development` |
| `ext-install-logs` | `InstallLogs` (`bot-modules:read` or `automations:read` by install category) | `feature:bot_module_extensions` |

---

## Developer Guide / Channel Status

Source: https://docs.lumio.vision/developer-guide/channel-status

# Channel Status

The channel status system tracks which streaming channels are currently online. It is a generic utility that any feature can consume - currently used by the Spotify worker to avoid unnecessary API requests and event storage when offline.

New Redis keyspaces and invalidation paths follow the [data design standard](./data-design.md).

## Architecture

```
PostgreSQL (durable state anchor) + Redis (live snapshot + pub/sub)
```

`channel_status` is written to PostgreSQL **only on real state transitions**
(online / offline / upcoming / `live_chat_id` / title / category change). The
high-frequency live counters - `viewer_count`, YouTube `like_count` /
`total_views` - live in the Redis snapshot and the 60-second
[stream-history](./stream-history-platforms.md) sample instead of writing to
PostgreSQL every poll cycle. PostgreSQL keeps only its irreducible jobs: startup
recovery, the YouTube broadcast lifecycle (`upcoming` / `live_chat_id`), and the
durable current-state anchor.

### Database

The `channel_status` table in PostgreSQL stores the current state per account per platform:

```sql
channel_status (
    account_id       UUID NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
    platform         VARCHAR(50) NOT NULL,   -- "twitch", "youtube", "kick"
    broadcast_id     VARCHAR(255) NOT NULL DEFAULT 'default',  -- per-broadcast id (multi-stream)
    is_online        BOOLEAN NOT NULL DEFAULT FALSE,
    broadcast_status VARCHAR(20),            -- "live", "upcoming", or NULL
    stream_title     TEXT,
    category         TEXT,
    viewer_count     INTEGER,
    like_count       INTEGER,                -- YouTube only
    total_views      BIGINT,                 -- YouTube only
    started_at       TIMESTAMPTZ,
    scheduled_start  TIMESTAMPTZ,            -- upcoming broadcast start time
    live_chat_id     TEXT,                   -- YouTube live chat ID
    updated_at       TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    PRIMARY KEY (account_id, platform, broadcast_id)
)
```

`idx_channel_status_account_online` is a partial index on `(account_id) WHERE is_online = TRUE`, so "does this account have any online channel?" is a single index probe.

`like_count` / `total_views` are refreshed by the YouTube worker from two quota-free sources: InnerTube (primary, every 60 s per live broadcast) and, for whatever InnerTube does not deliver, the public channel Atom feed (at most every 15 minutes per channel). See [Broadcast Statistics](../features/youtube-streaming.md#broadcast-statistics). These per-poll counter refreshes update **only** the Redis snapshot (via the `set_online` poll-refresh path), not the Postgres columns - so the Postgres `viewer_count` / `like_count` / `total_views` are frozen at the last transition. `update_stream_data()` (the Twitch poll path) is likewise Redis-only for `viewer_count`; a genuine `stream_title` / `category` change is still persisted, as a rare transition.

The dashboard read endpoints therefore overlay the live counters at read time - see [Reading live counters](#reading-live-counters).

### Redis

Three Redis structures per account:

| Key | Type | Purpose |
|-----|------|---------|
| `lumio:channel_status:{account_id}:{platform}` | String (JSON) | Cached status per platform (24h safety TTL) |
| `lumio:channel_online:{account_id}` | SET | Set of online platform names (`SADD`/`SREM`/`SCARD`); 7-day safety TTL, refreshed on every online write and on the startup rebuild |
| `lumio:channel_status:{account_id}` | Pub/Sub | Status change notifications |

The online set uses `SADD`/`SREM` for idempotency - duplicate events have no effect. Its TTL only bounds a missed offline transition: Twitch goes live from a single EventSub event and is not polled, so the TTL has to outlast a multi-day stream rather than a poll interval.

### Manual Connect

| Key | Type | Purpose |
|-----|------|---------|
| `lumio:spotify_manual:{account_id}` | String | Manual override, TTL 30 minutes |

## Rust API

The channel status service (`apps/api/src/services/channel_status.rs`) exposes a platform-agnostic interface:

```rust
// Core operations — every write path takes both pools plus the Redis client and
// pub/sub handle, because a transition also drives the stream-history session
// hook (TimescaleDB) and publishes a status change.
set_online(pool, tsdb, redis, pubsub, account_id, platform, &OnlineMetadata) -> Result<(), ChannelStatusError>
set_offline(pool, tsdb, redis, pubsub, account_id, platform) -> Result<(), ChannelStatusError>
set_broadcast_offline(pool, tsdb, redis, pubsub, account_id, platform, broadcast_id) -> Result<(), ChannelStatusError>
update_stream_data(...)                       // Twitch poll path, Redis-only for viewer_count

// Reads
get_status_with_live_counters(pool, tsdb, redis, account_id) -> Result<Vec<db::ChannelStatusRow>, ChannelStatusError>
is_any_online(redis, account_id) -> bool      // Redis SCARD, no DB hit
is_platform_online(redis, account_id, platform) -> bool
get_viewer_count(...)

// Manual connect
is_manual_connect_active(redis, account_id) -> bool
manual_connect_remaining(redis, account_id) -> Option<i64>
start_manual_connect(...) / stop_manual_connect(...)

// Recovery
rebuild_redis_from_db(...)  // startup: repopulate the snapshot + online set
verify_online_status(...)

// Raw row access (apps/api/src/db/channel_status.rs)
db::channel_status::get_status(pool, account_id) -> Result<Vec<ChannelStatusRow>, sqlx::Error>
db::channel_status::is_any_online(pool, account_id) -> Result<bool, sqlx::Error>
db::channel_status::get_all_online_accounts(pool) -> Result<Vec<(Uuid, Vec<String>)>, sqlx::Error>
```

Note the two `is_any_online` variants: the **service** one takes the Redis client and returns a plain `bool` (fail-open, no DB round trip); the **db** one takes the Postgres pool and returns a `Result`. Consumers on the hot path should use the service/Redis variant.

### Integration with Platform Adapters

Platform adapters call the channel status module directly when detecting stream status changes:

```rust
// In the Twitch EventSub worker:
"stream.online" => {
    channel_status::set_online(&db, &redis, account_id, "twitch", metadata).await?;
    // ... then proceed with normal event processing
}
"stream.offline" => {
    channel_status::set_offline(&db, &redis, account_id, "twitch").await?;
    // ... then proceed with normal event processing
}
```

The same pattern applies to YouTube, Kick adapters.

### Worker Lifecycle

A `channel_status_relay` background worker subscribes to `lumio:channel_status:*` via `PSUBSCRIBE` and reacts to status changes by starting/stopping the Spotify worker through the WorkerManager.

A separate 60-second poll task checks for expired manual connect keys.

```
Status change → channel_status_relay → WorkerManager → start/stop Spotify worker
```

Decision logic:

```
SCARD(online_set) > 0 OR manual_key exists?
├── YES + Worker not running → start_spotify_worker()
├── YES + Worker running     → no-op
├── NO  + Worker running     → stop_spotify_worker()
└── NO  + Worker not running → no-op
```

A channel in its dissolution grace period never gets a Spotify worker: the
relay checks `dissolution_scheduled_for` before it starts one and fails closed
on a database error. All platform workers of such a channel are stopped when
the dissolution is scheduled; see
[Accounts › Suspension](../features/accounts.md#suspension-while-a-dissolution-is-scheduled).

### Server Start Recovery

On startup, the API server:

1. Reads `channel_status` from PostgreSQL for all accounts
2. Rebuilds Redis keys (cache + online sets)
3. Starts Spotify workers only for accounts with at least one online channel
   (and none for a channel in its dissolution grace period)

## GraphQL API

```graphql
type ChannelStatus {
  platform: String!
  broadcastId: String!
  isOnline: Boolean!
  broadcastStatus: String
  streamTitle: String
  category: String
  viewerCount: Int
  likeCount: Int
  totalViews: Int
  startedAt: DateTime
  scheduledStart: DateTime
  liveChatId: String
  updatedAt: DateTime!
}

type SpotifyManualStatus {
  active: Boolean!
  remainingSeconds: Int
}

type Query {
  channelStatus: [ChannelStatus!]!
  spotifyManualStatus: SpotifyManualStatus!
}

type Mutation {
  startSpotifyManual: SpotifyManualStatus!
  stopSpotifyManual: Boolean!
}
```

All queries/mutations use `account_id` from `AuthContext`.

## REST API

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/v1/channel-status` | Status for authenticated account |
| `GET` | `/v1/spotify/manual-connect` | Manual connect status + remaining time |
| `POST` | `/v1/spotify/manual-connect` | Start manual connect (30min TTL) |
| `DELETE` | `/v1/spotify/manual-connect` | Stop manual connect |

All routes support popout token auth.

### Reading live counters

Because the live counters are frozen in Postgres after the slim-down, both read
endpoints (`channelStatus` and `GET /v1/channel-status`) go through one shared
service function, `get_status_with_live_counters`, which overlays the fresh
values onto each online row:

1. the Redis snapshot (`lumio:channel_status:{account_id}:{platform}`) - the
   authoritative live value;
2. failing that (a cold cache after a Redis loss), the most recent
   `channel_history_stats` sample (≤ 60 s stale).

GraphQL and REST share the same function, so the two protocols never drift.

## WebSocket Events

`channel_status_relay` re-publishes every status change onto the account's event channel (`lumio:events:{account_id}`, built by `channels::events`). The envelope is `{ "type": ..., "data": ... }`, where `type` is derived from `is_online` in the payload:

- `channel:online` - `data` = `{ platform, is_online: true, stream_title, category, viewer_count, started_at }`
- `channel:offline` - `data` = `{ platform, is_online: false, stream_title: null, category: null, viewer_count: null, started_at: null }`

The field is `category`, not `game_name` - the column was renamed in `20260326000004_rename_game_name_to_category`.

## Adding New Consumers

To use channel status in a new feature:

1. Import `api::services::channel_status`
2. Call `is_any_online(redis, account_id)` for a fast boolean check (Redis `SCARD`, fail-open)
3. Or `PSUBSCRIBE lumio:channel_status:*` (or subscribe to a single account's `lumio:channel_status:{account_id}`) for reactive updates

The service itself needs no change to add a read-only consumer. A consumer that must also start or stop a worker on transitions belongs in `channel_status_relay`, next to the Spotify evaluation - that is where the `PSUBSCRIBE` loop and the WorkerManager handle already live.

---

## Developer Guide / Data design standard

Source: https://docs.lumio.vision/developer-guide/data-design

# Data design standard

The Data Architect reviews data choices before implementation when a chain meets a review trigger below. This standard applies to migrations, `lo-database`, `lo-cache`, `lo-storage`, and crawler, bot, and worker write paths. **MUST** rules block approval until satisfied. **SHOULD** rules are defaults; a plan can deviate with a one-line reason.

## 0. When this standard is applied (Trigger 1)

A chain gets a **"Data design review"** child (assigned to the Data Architect, `blockedBy` edge to the first implementation child, ZAF-621) when it introduces any of:

1. a new table or hypertable, or any store decision (the store decision tree);
2. a schema change on a **hot or large** table — `platform_chat_messages`, `platform_event_logs`, `platform_users`, `audit_events`, `channel_history*`, `public_channel_*`, `notifications`, `sessions`, `api_keys`;
3. a new Redis keyspace, TTL, invalidation pattern or pub/sub channel;
4. a new kind of stored object (uploads, assets, exports);
5. a new query on a hot path (per chat message, per event, per crawl sample, per authenticated request).

**Exempt:** permission/flag/plan-feature seeds, a nullable column on a small table, bug fixes with no schema change. When in doubt, request the review — it costs one heartbeat.

## 1. Store decision tree

Answer in order; the first "yes" decides.

| # | Question | Store | Lumio examples |
|---|---|---|---|
| 1 | Is it a binary/blob, or text > ~64 KB that is written once and read whole (image, audio, bundle, export)? | **Object storage** (`lo-storage`) + a metadata row in Postgres | `uploads`, `sounds`, extension bundles/versions, avatars |
| 2 | Is it append-mostly, keyed by time, queried by time range, and does it grow with platform activity (per message / event / sample / request)? | **TimescaleDB hypertable** | `platform_chat_messages`, `platform_event_logs`, `audit_events`, `channel_history_stats`, `extension_events` |
| 3 | Is it a *derived, time-bucketed* read model of a hypertable? | **TimescaleDB continuous aggregate** | `channel_history_stats_5m`, `_1h` |
| 4 | Is it a read model that lives next to TSDB data and is joined with it (crawler/stats public read model), even if it is updated in place? | **TimescaleDB, plain table** (ZAF-791 / ZAF-843) | `public_channel_*`, `channel_history`, `channel_history_streams`, `csp_violation_reports` |
| 5 | Is it tenant/user state with relations, constraints, or an RBAC/billing/auth meaning? | **PostgreSQL (primary)** | `accounts`, `account_memberships`, roles, `channel_connections`, `plans`, `overlays`, `automations`, `platform_users` |
| 6 | Can it be **lost at any moment** (Redis flush, failover, eviction) and rebuilt from a source of truth or simply expire? | **Redis** (`lo-cache`) with TTL | permission cache, profile cache (4 h), rate limits, OAuth state, emote sets, channel status |
| 7 | Must it be delivered to other processes/replicas **now** and is loss acceptable? | **Redis pub/sub** | permission invalidation, overlay/widget fan-out, WS relay |
| 8 | Must it be delivered **at least once** across a restart/deploy, with replay? | **Broker** — not available yet (ZAF-673). Until then: write to Postgres/TSDB first (outbox) or a Redis list **with** a durable drain + dead-letter, never an in-memory channel | chat buffer (Redis list → 5 s flush → TSDB + 72 h dead-letter) is the accepted pattern |

**Boundary rules**

- **MUST — Redis is never the only copy of tenant data.** If losing the key loses user-visible data, it belongs in Postgres/TSDB; Redis may cache it. *Reason:* extension storage is Redis-only, no TTL, no quota, survives uninstall (F6, ZAF-2186). Exceptions are buffers with a durable drain (chat buffer), and they need a dead-letter and a bounded length.
- **MUST — the Postgres ↔ TimescaleDB boundary (ZAF-791):** time-series and their read models live in TSDB; relational tenant state lives in Postgres. There are **no cross-database FKs** — a TSDB row carries `account_id` as a plain `UUID`, and the deletion path for that account must be written explicitly (the retention section, GDPR deletion paths). *Reason:* `public_channel_*` had to be moved after the fact (ZAF-843).
- **MUST — no write path drops data on a store error without a retry/dead-letter.** "Log and continue" on an insert is data loss, not error handling. *Reason:* platform events were inserted straight into TSDB and dropped on error, and EventSub does not redeliver (F7, ZAF-2187). Platform-event ingest uses `lo_events::persist_event` (park + replay); see [Chat and event durability](./ingest-durability.md).
- **MUST — in-memory queues are drained on SIGTERM** (graceful shutdown handles SIGTERM, not just SIGINT), and are bounded. *Reason:* F7 — the Twitch EventSub `mpsc(1024)` persist queue was lost on every deploy. `apps/api/src/shutdown.rs` is the pattern: cancel, await the worker (which awaits its queue), then the final flush.
- **MUST — a statement that legitimately runs longer than the pool's `statement_timeout` (30 s on the API pools) lifts it for its own transaction** with `lo_database::begin_unbounded`; never raise the pool-wide limit for one query. *Reason:* one slow query on the 5-connection TSDB pool stalled chat flush, events and audit together (F7).
- **SHOULD — high-churn columns don't sit on hot relational rows.** A per-message `UPDATE` creates one dead tuple per message (audit the retention section "what breaks first" #3). Debounce (update when value changed or older than N minutes), aggregate per flush, or move the counter to TSDB/Redis. *Reference:* `platform_users.message_count` is tallied in process and written once per chat-flush tick per account, with `fillfactor = 80` so the update stays HOT (ZAF-2195, [Chat → Chatter tally](../features/chat.md#chatter-tally-platform_users-write-cadence)).

## 2. Naming & key conventions

### 2.1 Tables and columns
- `snake_case`, plural table names (`account_memberships`), singular column names.
- **MUST:** tables holding cross-platform user-facing platform data use the `platform_` prefix (`platform_users`, `platform_chat_messages`, `platform_event_logs`, `platform_moderation_log`, `platform_user_notes`); the old `chat_*` / `event_logs` names no longer exist (Serena `database/platform-table-naming`).
- Public crawler/stats read model: `public_channel_*`, `public_stream_*` (TSDB). Extension telemetry: `extension_*`. Join tables: `<a>_<b>` in the dependency direction (`account_role_permissions`).
- Booleans `is_*` / `has_*`; enumerations as `TEXT` + `CHECK (col IN (…))` (cheap to extend in a migration, unlike a PG `ENUM`'s `ALTER TYPE`).
- Indexes `idx_<table>_<cols>`; unique `uq_<table>_<cols>`; FK constraints keep the PG default name unless a migration needs to reference them.

### 2.2 Primary keys
- **MUST:** every table has a PK. Default `id UUID PRIMARY KEY`.
- **SHOULD:** new ids are generated as **UUIDv7** in Rust (`Uuid::now_v7()`, already 930 call sites) — time-ordered, so B-tree inserts stay right-leaning and index pages stay hot. `DEFAULT gen_random_uuid()` (v4, 124 columns today) is acceptable only on small tables; on a large append table a random leading key costs page splits and cache misses (audit F4: `channel_history_stats` had a random-UUID-leading PK and now defaults to `uuidv7()`, PostgreSQL 18).
- Natural/composite PKs are fine for pure join tables (`PRIMARY KEY (role_id, permission)`).
- **MUST — hypertables (ZAF-433):** the PK and every UNIQUE constraint include the partitioning time column: `PRIMARY KEY (id, created_at)` / `(id, time)`. Put `id` first only if lookups by id are a real query; otherwise lead with the column the hot query filters on. Never retrofit — ZAF-433/434 had to rewrite tables and edited a merged migration while doing it.

### 2.3 Foreign keys
- **MUST:** every FK states `ON DELETE` explicitly, chosen deliberately:
  - `CASCADE` — the child is meaningless without the parent (memberships, layers, nodes).
  - `SET NULL` — the child is the *account's* record and must survive the actor (`*_by`, `uploaded_by`, `dissolution_requested_by`).
  - `RESTRICT` — only when deletion must be blocked on purpose, and the deletion flow handles it (`accounts.owner_id`: profile deletion answers `409 OWNS_CHANNELS`). Write `RESTRICT`, never `NO ACTION` or no clause: the catalog cannot tell an explicit `NO ACTION` from a forgotten one, so the FK guard test rejects both.
  *Reason:* ~50 FKs to `users`, many `NO ACTION` (`uploads.uploaded_by`, `sounds.uploaded_by`) → `DELETE FROM users` fails with 23503 for anyone who uploaded into a foreign account (F2, ZAF-2182).
- **MUST:** every FK column is the leading column of some index (§3, FK indexes).
- **MUST:** no cross-database FKs (Postgres ↔ TSDB ↔ extensions DB). Store the id as plain `UUID`, document who deletes it.

### 2.4 Timestamps and types
- **MUST:** `TIMESTAMPTZ`, never `TIMESTAMP` (all 269 existing timestamp columns comply). Stored in UTC; display conversion is the client's job.
- `created_at TIMESTAMPTZ NOT NULL DEFAULT now()` on every table; `updated_at` only where rows are updated, set by the writer (no trigger magic on hot tables). Hypertables: the time column is `NOT NULL` and is what the hot query ranges over (`created_at` for logs, `time` for samples).
- Soft-delete / lifecycle markers as nullable timestamps (`deletion_requested_at`, `revoked_at`), never boolean flags.
- `TEXT` over `VARCHAR(n)`; enforce length with `CHECK (char_length(col) <= n)` where it matters. Money as `BIGINT` minor units + currency, never `FLOAT`/`NUMERIC` without scale. `JSONB` for sparse/opaque payloads only — anything filtered or joined on gets a real column.
- Secrets (`channel_connections` tokens, `app_credentials`) are encrypted at rest (AES-256-GCM) and never land in a cache, log, metric label or audit `metadata`.

## 3. Index policy

### 3.1 When to add an index
- **MUST:** every index in a plan names **the query it serves** and its expected selectivity. An index without a query is write amplification and RAM (audit S-items: 6 duplicate + ~20 prefix-redundant indexes on `next`).
- **SHOULD:** don't index columns with < ~5 % selectivity on their own (booleans, `platform`, `status`) — make them the trailing column or a partial-index predicate instead.
- **MUST NOT:** create an index whose columns are a leading prefix of an existing index on the same table (redundant), or an exact duplicate of a PK/UNIQUE index.
- **MUST:** every ordered `LIMIT` read on a hypertable carries a **time lower bound** on the partitioning column. `ORDER BY created_at DESC LIMIT n` runs as a `ChunkAppend` that walks chunks newest-first until it has `n` rows; when fewer than `n` rows exist (an empty account, the last page of a history, a sparse account) it opens **every** chunk, so its cost grows with retention × chunk count. Bound the read by the retention cutoff when it is finite and enforced, otherwise by a walk window that hands back a continuation cursor at the window edge instead of "end of history" — never hide a reachable row. An account-scoped lower bound that no writer undercuts ends the walk early: the merged chat history stops 7 days before `accounts.created_at` (the slack covers a YouTube live-chat backlog stored with its original timestamps; ZAF-2254), so an account without chat ends on its first page instead of walking the install's history window by window. Before relying on such a bound, check every dated writer, import, backfill and re-keying path. *Measured (ZAF-2251, TSDB 2.30.1):* the empty first page of the merged chat history on a 366-chunk `platform_chat_messages` cost 167 482 shared buffers cold / 14 583 warm (planning + execution) unbounded, 16 572 / 530 with a 30-day floor (31 chunks). Run such a read **unprepared** (`.persistent(false)` on the sqlx query): a cached prepared statement may switch to a generic plan after five executions, and a generic plan cannot exclude chunks by a bound parameter at plan time — it lists (and the executor locks) every chunk, excluding them only at executor startup. *Measured (ZAF-2254):* the generic plan of the same page lists 366 of 366 chunks; the unnamed statement plans 31 on every run. Note: any time predicate turns TimescaleDB's `DeferredChunkAppend` (per-chunk `LIMIT` pushdown) into a plain `ChunkAppend`; on a small, dense chunk the planner may then prefer Seq Scan + Sort of that one chunk — pin the plan with a volume test.
- Hot-path queries (per message / event / sample / request) need an index-only or single-index plan; the reviewer may ask for `EXPLAIN (ANALYZE, BUFFERS)` on representative synthetic data. The [volume tests](volume-tests.md) provide that data set (`small` in CI, `large` on demand) and pin hot-path plans by their counters; the implementer or QA runs them.

### 3.2 FK indexes
- **MUST:** every FK column (or FK column set) is the leading column(s) of an index. A cascade/`SET NULL` on the parent otherwise seq-scans the child once per deleted parent row. *Reason:* 96 unindexed FKs on `next`; user deletion scales with the largest child table (F2).
- A **partial** index does **not** count as the FK index (`notifications.user_id` used to have only a partial index → cascades seq-scanned). The one exception is a single-column partial index whose predicate is exactly `<fk column> IS NOT NULL`: the cascade's `fk = $1` implies it.
- **Enforced:** `apps/api/tests/zaf2182_fk_on_delete.rs` fails when an FK to `users` / `accounts` or into the extension tree (`extensions` / `extension_versions` / `extension_installs`) has no explicit `ON DELETE` action (`RESTRICT` only through its allowlist), or when such an FK or an FK to `channel_connections` does not lead an index.

### 3.3 Partial and covering indexes
- **SHOULD:** use a partial index when the hot query always carries the same predicate (`WHERE revoked_at IS NULL`, `WHERE status = 'pending'`). The query's `WHERE` must imply the index predicate literally, or the planner won't use it.
- **SHOULD:** use `INCLUDE (…)` for small columns read by a hot lookup to get index-only scans; never `INCLUDE` JSONB/large text.
- Time-ordered reads: index `(tenant_key, time DESC)` — matches "latest N for account X".
- TSDB compressed chunks: a B-tree index on the hypertable is also used as a **sparse (bloom/min-max) index** on compressed batches (current TimescaleDB; measured on 2.30.1, the host test stack version). Add one for every non-segmentby equality filter a hot or GDPR query uses. *Measured:* GDPR erasure by `(platform, user_id)` decompressed 2 800/2 800 batches (228 ms on 3 M rows, ~1–2 min at 1 B rows); with the index 14 batches (66 ms, +9 % size).

### 3.4 `CONCURRENTLY` and the sqlx constraint
- sqlx 0.9 runs every migration in a transaction **unless the file starts with `-- no-transaction`** (`sqlx-core` `migrate/source.rs`). `CREATE INDEX CONCURRENTLY` / `DROP INDEX CONCURRENTLY` / `REINDEX CONCURRENTLY` cannot run in a transaction.
- **MUST** for an index on a **large/hot table** (the review triggers list, or any table expected > ~1 M rows): `CREATE INDEX CONCURRENTLY IF NOT EXISTS …` in its **own** migration whose first line is `-- no-transaction`, containing **exactly one statement** (a multi-statement simple query is an implicit transaction block and fails the same way). The `.down.sql` is likewise `-- no-transaction` + `DROP INDEX CONCURRENTLY IF EXISTS …`.
- A failed `CONCURRENTLY` build leaves an `INVALID` index; `IF NOT EXISTS` would then skip it. The recovery (manual `DROP INDEX CONCURRENTLY` + rerun) belongs in the PR body.
- **`lock_timeout` and the runner:** the API runner (`lo_database::run_migrations`) runs migrations with `lock_timeout = '5s'` and retries on `55P03` — except `-- no-transaction` up migrations. Each of those runs in its own pass with `lock_timeout = 0` (everything before it runs first, with the timeout; a final pass runs the rest). `CONCURRENTLY` waits for older transactions; under the timeout that wait would leave an `INVALID` index that the retry skips (`IF NOT EXISTS`) or trips over (`already exists`). Its locks never queue ordinary writers, so it needs no timeout. After migrating, the runner logs every `INVALID` index (`pg_index.indisvalid = false`) at `error`; recovery is a manual `DROP INDEX CONCURRENTLY` and re-running the statement. The `migrate` CLI sets no `lock_timeout` at all.
- Small tables (< ~100 k rows, e.g. `plans`, `feature_flags`, `oauth_clients`): plain `CREATE INDEX` inside the normal transactional migration is fine.
- **Hypertables:** `CONCURRENTLY` is not supported. Use `CREATE INDEX … WITH (timescaledb.transaction_per_chunk)` — also non-transactional, so the same one-statement `-- no-transaction` rule applies. It locks one chunk at a time instead of the whole hypertable.
- *Examples:* `apps/api/migrations/20261012200002_moderation_log_delete_target_index` (`CREATE INDEX CONCURRENTLY` on `platform_moderation_log`), `20261012200001_drop_redundant_platform_users_index` (`DROP INDEX CONCURRENTLY` on `platform_users`), `apps/api/tsdb_migrations/20261011150000_chat_messages_platform_user_index` (`transaction_per_chunk`).

## 4. Retention per data class

**MUST:** every new table or hypertable declares its retention in the plan: a window, *or* "lifetime of parent row X (cascade)", *or* "kept forever because `reason`". "Unbounded" without a reason is a review block. *Reason:* ZAF-648 (no hypertable had retention) and ZAF-221 (`chat_retention_days` not enforced).

| Data class | Store | Retention | Mechanism | Rule for new work |
|---|---|---|---|---|
| Chat messages | TSDB `platform_chat_messages` | **plan-driven**: `plans.chat_retention_days` (Free 365 d / Pro 1095 d), admin override in `account_limits`; `0` resolves to the 1095-day ceiling | per-account sweep `workers/chat_retention.rs`: row `DELETE` by `account_id` + time in slices of ≤ 30 days walked from the oldest chunk (cheap on compressed chunks, 11 ms measured), then `drop_chunks` below the longest effective window + 1 day; the tail runs for `0` too | New chat-derived data inherits the finite chat window. The same `0` = 1095-day rule covers events, chatter profiles and moderation data. |
| Platform events | TSDB `platform_event_logs` | plan-driven, same window as chat | same per-account sweep | Orphaned account rows are removed by `workers/chatter_orphan_sweep.rs`; new event-derived data must follow the same deletion paths. |
| Audit | TSDB `audit_events` | 12 months full → network fields (IP/GeoIP/UA) nulled → row deleted at 24 months; erasure-proof types (`event_types::ERASURE_PROOF`) deleted at 36 months | jobs `anonymise_old_audit_events` (`20260823000002`) and `purge_old_audit_events` (`20261011130000`, `drop_chunks` past 36 months + row `DELETE`) | Do not put PII in `metadata`. A new erasure-proof type needs the constant and an `alter_job` config migration (test `tsdb_audit_purge`). |
| Crawler raw samples | TSDB `channel_history_stats` | 90 days | `add_retention_policy` | Raw ≤ 90 d; anything longer is a rollup. |
| Crawler rollups | TSDB caggs `_5m`, `_1h` | `_5m`: 12 months · `_1h`: **none** (kept by product promise) | `add_retention_policy` on `_5m` (ZAF-2219) | Reads older than 12 months fall back to `_1h`. New caggs need their own retention + compression (F4/L1). |
| Stream history / reports | TSDB `channel_history*`, milestones | lifetime of the account | account deletion | Frozen JSONB lists (`top_chatters`, `links`, `commands`, `keywords`, `announcements`, `pins`) and `account_bot_keys` contain chatter identities → the instructed subject erasure scrubs them in every session of the instructing account (`services::history::erasure`, ZAF-2346; never the crawler account): counts stay, identity fields are blanked, `erased: true`. A new frozen column with chatter identities MUST be added to that scrub. |
| Channel chatter suppression list | PG `account_chatter_suppressions` (ZAF-2641, data design ZAF-2649) | until the account is deleted: no TTL, no job | `accounts ON DELETE CASCADE` | PK `(account_id, platform, platform_user_id)` + lower-cased Twitch/Kick `logins` (matched only against list entries without a user id); no reason column. Written only by the instructed erasure of one person in one channel, before that channel's history scrub. Read (fail closed, no cache) by `services::history::suppression::subjects_for_account` before every freeze and read-time derive of **that** account's stream history (sampler finalize, bot backfill/re-derive, `chat_insights::derive` / `refreeze_keywords`); error → session left unfrozen (retried next tick), read-time derive shows no lists. Never acts on another account or on Lumio Stats. |
| Lumio chatter suppression list | PG `chatter_suppressions` (ZAF-2351) | until withdrawn: no TTL, no job | lifting an objection deletes the row; an `'erasure'` row is not lifted by the objection path | Holds `(platform, platform_user_id)` + lower-cased Twitch/Kick `logins`, `reason` `erasure` / `objection`. Acts on Lumio's own surfaces only: read (fail closed, no cache) by `services::history::suppression::subjects_for_lumio` on every public stream read with the leaderboard on (`services::public_stats`, ZAF-2356, as the last read; error → `top_chatters = None`). It never blanks a channel's report, freeze, derive, share link or export. |
| Withdrawal-waiver proof | PG `withdrawal_waiver_consents` | **lifetime of the account** (`account_id ON DELETE CASCADE`); a deleted buyer only nulls `user_id` | account deletion (`services/storage_erasure.rs`) cascades; no sweep | One row per paid Stripe checkout (ZAF-2690, design ZAF-2703). Proof columns are write-once; `plan_id` / `extension_id` are plain ids so deleting a plan or extension never rewrites proof. Extension purchases (`extension_purchases.account_id` / `extension_id` / `version_id ON DELETE SET NULL`) outlive the account and the extension but not their own 8-year retention (row below); the proof does not outlive the account. |
| Extension purchase ledger | PG `extension_purchases` (+ `extension_licenses`, `extension_purchase_rollups`) | **8 Europe/Berlin calendar years after the last booking event** (`GREATEST(created_at, updated_at)`; § 14b UStG / § 147 AO): a row is deletable from 1 Jan of (that Berlin year + 9). Held without end: `disputed` rows, a running subscription (`stripe_subscription_id` set, `subscription_ended_at` NULL), a `completed` row with neither a `sub_…` nor a PaymentIntent (mode unknown), a purchase a `contract_declarations` row references (FK `RESTRICT`; the declaration's own retention removes it first), a purchase that still has renewal invoices (row below) | daily step `workers::account_security::run_daily` (ZAF-2800, design ZAF-2799): one CTE statement per batch of 500, at most 20 batches, `FOR UPDATE SKIP LOCKED`, no time index (small table, one seq scan a day); logs `deleted`, `licences_written`, `held_*`; no audit event | Every `UPDATE` of a purchase row MUST set `updated_at = now()`, or the row is deleted early. A deleted one-time purchase leaves an `extension_licenses` row (no amounts or Stripe ids; `accounts`/`extensions ON DELETE CASCADE`), and `has_purchased` reads purchase OR licence. Deleted rows are added to `extension_purchase_rollups`, so totals computed from the ledger (deletion snapshot, analytics revenue, revenue summary) read live + rollup and never shrink through retention; only the per-row developer purchase list does. |
| Extension subscription renewals | PG `extension_subscription_invoices` | **8 Europe/Berlin calendar years after the last booking event**, the same clock as the purchase ledger; `disputed` rows are held | same daily step, **before** the purchase purge (ZAF-2706, design ZAF-2857): batches of 500, `FOR UPDATE SKIP LOCKED`; logs `invoices_deleted`, `held_invoices` | One row per paid renewal invoice (invoice #1 is the purchase row itself). `purchase_id` is `RESTRICT`, so a purchase is held while it has invoices. Deleted invoices add their `revenue_share` to `extension_purchase_rollups.completed_revenue_share` (not to the purchase counts); the deletion snapshot and analytics revenue read live invoices + rollup. |
| Developer payout ledger | PG `developer_payouts` | **8 full calendar years after the year of the last booking event** (§ 147 Abs. 1 Nr. 4, Abs. 3 AO): deletable from 1 January 00:00 Europe/Berlin of (Berlin year of `GREATEST(created_at, updated_at)` + 9). `pending` / `processing` rows are held and never deleted | daily step `workers::account_security::run_daily` (after the purchase purge) → `db::extension_payments::purge_expired_payouts` (`completed` / `failed` only, batches of 500, `FOR UPDATE SKIP LOCKED`) | Detached from the profile (`developer_id ON DELETE SET NULL`, ZAF-2804, design ZAF-2803): a profile or user deletion keeps the row. Every insert goes through `extension_payments::insert_payout`, which copies the payee from the **verified** `developer_verifications` row (`payee_*`) and stores a masked `payout_reference` (Stripe `acct_…` in full, PayPal `j***@domain`, IBAN `DE89****00`); without a verified verification nothing is inserted (only verified developers are paid). A `BEFORE DELETE` trigger on `developer_profiles` refuses the delete while `revenue_balance > 0` or a payout is `pending`/`processing` (SQLSTATE `LM001` → `409 DEVELOPER_FUNDS_OUTSTANDING`). A `BEFORE UPDATE` trigger moves `updated_at` on every change except the `SET NULL` detach itself, which is not a booking event and keeps the retention clock. |
| Developer credit notes (Gutschrift) | PG `developer_credit_notes` + write-once PDF in `lo-storage` (`billing/credit-notes/<year>/<id>.pdf`, private, sha256 on the row); numbering in `credit_note_counters` (one row per Berlin year, never deleted) | **8 Berlin calendar years after the issue year** (§ 14b Abs. 1 UStG, § 147 AO): deletable from 1 January 00:00 Europe/Berlin of (Berlin year of `issued_at` + 9); an original and its cancellation are purged **together**, once both are past the cut | daily step `workers::account_security::run_daily` (after the payout purge) → `db::credit_notes::purge_expired_credit_notes` (groups by `COALESCE(cancels_id, id)`, batch counts groups, plain `FOR UPDATE`); PDF keys go to `storage_deletion_queue` in the same statement | Detached from profile and payout (`developer_id` / `payout_id ON DELETE SET NULL`, ZAF-2807, design ZAF-2806). One effective note per payout, issued in the payout transaction by `extension_payments::insert_payout_with_note` on every insert path; payout amount = `gross_amount`. A cancellation is a new row (`cancels_id`, own number, negated amounts). A `BEFORE UPDATE` trigger (SQLSTATE `LM002`) allows only the cancellation mark, the one-time PDF store, `delivered_at` and the FK detach. |
| Extension telemetry | TSDB `extension_events/errors/install_logs` | 180 / 90 / 30 d | `add_retention_policy` | — |
| Platform users / moderation / notes | PG `platform_users`, `platform_moderation_log`, `platform_user_notes` | **plan-driven** like chat (Free 365 d / Pro 1095 d, `account_limits` override wins), clamped to 1095 d — `0` or a missing account also gets 1095 d (ZAF-2272). `platform_users` `W` after `last_seen_at`; in a moderation state (effective ban, treatment, note) `W` after the last moderation activity (latest of `last_seen_at`, `banned_at`, `treatment_updated_at`, newest note edit — never `updated_at`, which reads and enrichment also bump); notes with their chatter (orphaned: `W` after `updated_at`); moderation log `W` after `created_at`. Per-platform caps (`retention::PLATFORM_RETENTION_CAP_DAYS`) only shorten | `workers/chatter_retention.rs` (ZAF-2200, ZAF-2272): per-account key-window sweep, no time index, reads every retained row each cycle (`chatter_retention_last_cycle_seconds`); `autovacuum_vacuum_scale_factor = 0.02`; event-driven erasure ZAF-2181; a disconnect deletes nothing here (ZAF-2641, the sweep is per account and keeps running) | The ceiling `retention::MAX_CHANNEL_DATA_RETENTION_DAYS` (1095) is shared by the sweep and the admin validator (REST + GraphQL) — nothing may configure a longer window. New per-chatter tables MUST ship their erasure path. |
| Twitch AutoMod held-message log | PG `platform_automod_messages` | **plan-driven** chat window `W` (`COALESCE(account_limits, plans).chat_retention_days`, Free 365 d / Pro 1095 d, clamped to 1095 d; `0` or missing = 1095 d) from `held_at`, for the row and its `content` (text, flagged spans, term text, emote/cheer refs) together, all outcomes including `pending` | one always-on deleter `workers/automod_log_retention.rs` (hourly, advisory lock, runs even with `chat.chatter_retention_enabled = false`; index `(account_id, held_at, id)`; counts into `chatter_retention_rows_deleted_total{table="platform_automod_messages"}`); subject erasure/objection, account dissolution and the orphan sweep delete rows (a Twitch disconnect keeps them, ZAF-2641) | `content` is capped at 4 KiB JSONB (emote/cheer refs dropped first, then term text, spans, text). Sender look columns `sender_avatar_url`, `sender_color`, `sender_badges` (badges dropped above 1 KiB) are a snapshot of `platform_users` at hold time and go with the row. The log is read live for the private Stream History tab and the merged chat history and is never frozen into a report or export. |
| Sessions / tokens | PG `sessions`, `api_keys`, `overlay_tokens`, OAuth state | expiry columns; Redis state by TTL | expiry + cleanup | **MUST:** every credential table has `expires_at` or `revoked_at` **and** a prune job for rows dead > 30 d. Redis copies (`session_valid`) are deleted on revoke, not left to TTL (`RedisClient::invalidate_session_validity` on every session-revoke path). |
| Notifications | PG `notifications` | **none** (S6) | — | **SHOULD:** read notifications pruned after 90 d, unread after 1 y. |
| CSP reports, login devices | PG/TSDB | prune jobs | job | — |
| Uploads / objects | storage + PG metadata | lifetime of the metadata row | **only if the delete path deletes the object** (F3) | the object storage section. |

### How retention is implemented
- **Whole-table window** on a hypertable → `add_retention_policy` (drops whole chunks; near-free). Requires chunk interval ≪ window (the TimescaleDB section, Chunk interval).
- **Per-tenant window** (plan-driven) → batched `DELETE … WHERE account_id = $1 AND <time> < now() - window` per account; `account_id` is `segmentby`, so compressed batches are pruned by metadata. Batch per account, never one global statement.
- **Plain Postgres tables** → a worker deleting in batches of ≤ 10 000 rows by an indexed time column, committing per batch (`DELETE … WHERE ctid = ANY(ARRAY(SELECT ctid … LIMIT n))` or by PK range). Never one unbounded `DELETE`.
- **Hot Postgres table without a time index** (the time column is rewritten on the hot path, so an index would make those updates non-HOT) → walk each account in key windows over its `account_id`-leading unique index (`OFFSET n-1 LIMIT 1` gives the window's upper key), delete `(lo, hi]` with the retention predicate on the `DELETE` itself so a concurrently refreshed row is re-checked, then `lo = hi`. Each statement is bounded by the scanned window, not by matched rows. *Reference:* `workers/chatter_retention.rs` (ZAF-2200).
- **Anonymise instead of delete** only when the row itself must survive (audit trail); null the PII columns via a job, and say in the plan which columns remain (pseudonymous ≠ anonymous) and when the row itself is deleted (audit: 24 months).

### GDPR deletion paths (MUST)
- Every table/keyspace/object prefix that stores **personal data** (a chatter's id/name/message, a user's IP/UA/email, uploads) names its deletion paths in the plan:
  1. **subject erasure** (a viewer/chatter, `chat_privacy.rs` path),
  2. **user deletion** (`users` row, ZAF-2116),
  3. **account dissolution** (`account_dissolution.rs`),
  4. **retention expiry**.
- Postgres cascades only cover Postgres. **TSDB rows, Redis keys and storage objects need explicit code in each path** — and that code must run even when the parent row is already gone (F1, F3).
- An erasure query on a hypertable must be index-supported (§3, Partial and covering indexes sparse index), or it decompresses everything.
- Retention wording and windows are signed off by **Legal & Compliance**; the data layer implements them.
- A **frozen copy** of personal data (JSONB lists written at finalize, denormalised names) outlives its source's retention, so the subject erasure must reach it directly — in every session of the instructing account, not only in the sessions whose source rows it just deleted (channel data belongs to the channel, so the erasure acts per account, ZAF-2626). *Reference:* `services::history::erasure::scrub_subjects(tsdb, account_id, subjects)` (ZAF-2346): candidate ids collected read-only by JSONB containment over that account's rows (`account_id = $1` on `idx_channel_history_account_started`; no index on the lists, erasure is rare; the crawler account is never scrubbed), then read `id = ANY(…) FOR UPDATE` and rewritten in batches of 500, counts kept, identity fields blanked, `erased: true`; fatal on failure, count in the audit metadata (`scrubbed_history_session_count`).
- A **derived read model** (§5.6) is deleted with its source: erasing the source rows queues a recompute that removes the derived rows. An erasure path that must take effect at once also deletes the derived rows in its own transaction (the crawler opt-out erases the `public_channel_browse*` rows of the channel next to its `channel_history_streams` rows).

## 5. TimescaleDB

### 5.1 Chunk interval
- **MUST:** every `create_hypertable` sets `chunk_time_interval` explicitly. *Reason:* the 7-day default made one `channel_history_stats` chunk ≈ 79 GB at 30 k live crawled channels (F4). `channel_history_stats`, `platform_chat_messages` and `extension_install_logs` use 1-day chunks; the other hypertables still run on the 7-day default.
- **Sizing rule:** one chunk incl. its indexes ≤ **~1 GB uncompressed at the 12-month forecast**, and the sum of all *active* (uncompressed) chunks across hypertables fits in ~25 % of the TSDB host's RAM. Minimum 1 hour.
- Guide values: chat/events/audit → **1 day**; crawler raw samples → **1 h–1 day** depending on crawl scope (≥ 30 k live channels → ≤ 2 h); low-volume telemetry → 7 days.
- Changing the interval (`set_chunk_time_interval`) only affects **future** chunks — the cost of getting it wrong is carried until old chunks age out.

### 5.2 Compression (columnstore)
- **MUST:** every hypertable that keeps data > 7 days enables compression with a policy. Every hypertable compresses, including the extension telemetry (`extension_install_logs`, `extension_events`, `extension_errors`) and both `channel_history_stats` caggs.
- `segmentby` = the column every hot query and every retention/erasure sweep filters on by equality — normally `account_id`; for crawler data the channel key (`session_id` / channel id). **Rule of thumb:** ≥ ~1 000 rows per segment per chunk; a segmentby with too high cardinality (e.g. `user_id`) produces tiny batches and no compression.
- `orderby` = the time column `DESC` (plus a second key if range scans use it). Declare it explicitly, don't rely on the default.
- **MUST: set the compression order explicitly.** Every hypertable that enables compression sets both `timescaledb.compress_segmentby` and `timescaledb.compress_orderby`. `compress_orderby` leads with the time column (`created_at DESC` / `time DESC`) unless the data design review names a different dominant range predicate. Never rely on the default: when TimescaleDB compresses a chunk it derives the order from the table's indexes, which with the `(id, <time>)` primary-key convention (ZAF-433) puts `id` first (the chat table got `id, created_at DESC, platform, lumio_user_id`), and batch min/max metadata then cannot skip anything on a time predicate. *Measured (ZAF-2197):* the chat retention delete decompressed 25 batches and touched 236 k buffers with the default order, against 1 batch and 11.7 k buffers with `created_at DESC`.
- **Changing the order of a hypertable that already has compressed chunks:** the new setting only applies to chunks compressed from then on; TimescaleDB stores the order per chunk. Never recompress inside the migration (one transaction at API start: every chunk stays locked until commit and is inflated to its raw size). Rewrite the old chunks with a TimescaleDB job that recompresses a few chunks per run, newest first, one chunk per transaction, with `compress_chunk(chunk, recompress => true)` — see `recompress_stale_orderby_chunks` (ZAF-2197), which also covers any later order change on the four hot hypertables once re-enabled with `alter_job(id, scheduled => true)`.
- Compress **after** the active write window: `compress_after` ≥ chunk interval and ≥ the late-arrival window (chat 1 day, crawler 1 day, audit 7 days).
- Updates/deletes on compressed chunks work (TSDB ≥ 2.11) but decompress the touched batches — keep them per-segment (retention by `account_id`) or index-supported (§3, Partial and covering indexes).
- Syntax: `ALTER TABLE … SET (timescaledb.compress, timescaledb.compress_segmentby = '…', timescaledb.compress_orderby = '… DESC')` + `add_compression_policy` (repo idiom). The 2.18+ columnstore names (`timescaledb.enable_columnstore`, `add_columnstore_policy`) are equivalent; pick one per migration.

### 5.3 Retention
- Window per the retention section. `add_retention_policy(… if_not_exists => TRUE)`. A cagg's raw source retention must be **longer** than the cagg's refresh window (`_5m`/`_1h` refresh 2 d / 30 d vs raw 90 d — OK).

### 5.4 Continuous aggregates
- Use a cagg when a dashboard/stats query aggregates > ~100 k raw rows per request or the same aggregate is read repeatedly.
- **MUST:** each cagg has a refresh policy, **its own retention policy** (or a stated "kept forever" reason) and **compression** if kept > 30 days.
- Hierarchical caggs (`_1h` from `_5m`) are preferred over two aggregates over raw.
- Real-time aggregation (`materialized_only = false`) only where freshness < refresh interval matters; it adds a raw scan per query.

### 5.5 Plain tables in TSDB
- Allowed for read models next to hypertables (the store decision tree row 4). Same Postgres rules apply (PK, indexes, retention) — "it's in TSDB" is not a retention policy.

### 5.6 Derived read models (per-entity summaries) {#derived-read-models}
When a request would otherwise aggregate every row of a growing table (the public browse grouped every `channel_history_streams` row on each request), keep a per-entity summary next to it. The public browse read model (`public_channel_browse*`, ZAF-2300) is the reference implementation:
- **Summarise what no longer changes.** The summary covers *closed* rows only. Rows that change every minute (open streams) go into a small overlay table that is rebuilt as a whole on a fixed cadence (`DELETE` + `INSERT` in one transaction — **not** `TRUNCATE`, whose `ACCESS EXCLUSIVE` lock blocks readers). The overlay stores the *combined* (summary + open) values, so both are read by index.
- **Feed it from row triggers, not from every writer.** A source table with many writers gets `AFTER INSERT/UPDATE/DELETE` row triggers whose `WHEN` clause is false on the hot path (here: an update of an open row), so the hot path does not even call the trigger function. The trigger only appends the entity key to an **append-only** queue table (plain `INSERT`, no unique key): a writer never waits on the drainer, and two writers cannot deadlock on the queue.
- **One drainer.** A worker takes a transaction-level advisory lock (`pg_try_advisory_xact_lock`), removes the visible queue rows of up to N entities and recomputes those entities from the source in the same transaction. An uncommitted queue row is invisible to it and survives, so no update is lost. Two drainers could recompute one entity from two snapshots, which is why there is one.
- **One arm per row.** An entity that has an overlay row is excluded from the summary arm through a flag (`has_open`) kept in sync by the overlay rebuild, with the summary's sort indexes partial on `NOT has_open`. An anti-join against the overlay would walk past every overlay entity that sorts ahead.
- **Backfill through the queue.** The migration seeds the queue with every entity; the read path switches over on a persisted "first drain completed" flag.
- **Bound public reads.** Public pagination caps its depth and counts with `LIMIT cap + 1` (`MAX_BROWSE_DEPTH`).
- **Reuse the summary for indexing.** The Stats channel sitemap reads `public_channel_browse` in stable primary-key order, limited to 45,000 rows per file, with a 12-month `last_started_at` floor and read-time opt-out exclusion. Its count uses the same table but does not subtract opt-outs. The channel share card probes `public_channel_browse_live` first, then `public_channel_browse` by `(platform, platform_channel_id)` and joins `public_channel_metrics`; it reads the main database for visibility only on a hit and probes the existing live-stream reader only when live. Neither path scans `channel_history_streams` per request. `idx_pcb_sitemap` covers the sitemap fields.
- Pin the read plans at volume (`tests/volume_plans.rs`, P16): no read of the source table, and the same page cost at twice the source rows.

## 6. Cache (Redis, `lo-cache`)

### 6.1 Key schema
- **MUST:** `lumio:<domain>:<scope…>:<id…>` — lowercase, `:` separated, `_` inside segments. `<domain>` is one of the existing namespaces (`perms`, `chat`, `chatters`, `events`, `emotes`, `kick`, `yt`, `spotify`, `ratelimit`, `overlay`, `widget`, `session`, `apikey`, …) or a new one named in the plan.
- **MUST — tenant isolation:** any key holding tenant-scoped data contains the **tenant id** (`account_id`, and `user_id` where per-user) as a segment, and the code that reads it derives that id from the authenticated context, never from client input alone. Keys holding credentials also contain the credential's identity (`client_id`), not just the platform. *Reason:* ZAF-897 cache leak class; `lumio:oauth:app_token:{platform}` lacks `client_id` (latent, audit notes).
- Values: JSON (or the existing binary codec) with a schema version in the key or value when the shape can change (`lumio:x:v2:{id}`), so a deploy doesn't read the old shape.
- **SHOULD:** single values ≤ ~100 KB; hashes/lists/sets ≤ ~1 000 members unless read with `HSCAN`/`LRANGE` windows. *Reason:* `HGETALL lumio:chatters:*` up to 5 000 fields ≈ 1 MB; emote-set blobs of several hundred KB — the likeliest causes of the > 500 ms tail (ZAF-1532).

### 6.2 TTL
- **MUST:** every key has a TTL, set **atomically** with the write (`SET … EX`, `SET … PX`, or a pipeline/`MULTI`/Lua — never `INCR` then a separate `EXPIRE`, S2). Collections get `EXPIRE` refreshed on every write.
- Allowed exceptions, each named in the plan: a buffer with a durable drain and a bounded length (chat buffer), and bounded static data (fonts). *Reason:* `channel_online` sets had no TTL until ZAF-2188 (S3; now a 7-day safety TTL refreshed on every online write); extension storage was Redis-only without TTL until ZAF-2186 (F6).
- TTL guide: auth/permission caches ≤ 5 min (and explicit invalidation, §6, Invalidation); profile/enrichment 1–4 h; platform metadata (emotes, badges) 1–24 h; OAuth state ≤ 10 min; rate-limit windows = window length.

### 6.3 Invalidation
- **MUST:** every cache of authorisation data (permissions, roles, memberships, sessions, API keys) is invalidated **synchronously in the same code path as the write**, on **both** GraphQL and REST (protocol parity). TTL is only the backstop. *Reason:* REST `update_role`/`delete_role` used to skip the `lumio:perms:*` invalidation GraphQL did → revoked permissions stayed usable 5 min via REST (F5; both now call `services::roles`, ZAF-2185); `session_valid` was not deleted on revoke until ZAF-2188 (S4).
- Invalidation = `DEL` of the exact keys, after the DB commit. If the set of affected keys is not computable, use a generation key instead of pattern deletes: a unique token (never a counter — an expired counter can repeat a value) whose TTL outlives the entries, read in the same `MGET` as the entry and stamped into the entry's value (`lumio:perms:ver:{user}` / `lumio:perms:epoch`, ZAF-2235).
- Cross-replica in-process caches are invalidated via a pub/sub channel **that has a subscriber** — a published channel with no subscriber is dead code (the former `PERMISSION_INVALIDATE` constant was deleted for this reason, ZAF-2185).

### 6.4 Forbidden patterns on the shared connection
- **MUST NOT:** `KEYS`, `SCAN` over the full keyspace (`MATCH lumio:*…` without a hash-tag/index set) on a request or periodic path, unbounded `LRANGE 0 -1` / `SMEMBERS` / `HGETALL` on collections that can grow, `FLUSH*`, blocking commands (`BLPOP`, `XREAD BLOCK`) on the multiplexed connection. Keep an explicit **index set** (`lumio:<domain>:index:{account}` with TTL) if you need to enumerate keys. *Reason:* one multiplexed connection carries every command; one slow command stalls all of them (ZAF-1532); chat flush did a full-keyspace `SCAN` every 30 s per replica until ZAF-2188 (S1) — it now reads the index sets `lumio:chat:{buffer,deadletter}:pending`, maintained in the same `MULTI`/`EXEC` as the list writes, and scans only at worker start and ~15 min later to heal them.
- Subscribers and anything blocking use a dedicated connection (already the pattern).

### 6.5 Stampede protection
- **SHOULD** for any key whose miss costs > ~50 ms or hits an external API/rate limit: single-flight on miss (`SET lumio:<domain>:lock:{id} NX PX <ms>`; losers wait briefly or serve stale), plus TTL jitter (±10 %) for keys written in bulk.
- **SHOULD** for external-API-backed data (Helix, InnerTube, Kick, 7TV): serve-stale-while-revalidate — keep a soft TTL in the value and a longer hard TTL on the key.
- Negative caching (short TTL, 30–60 s) for "not found" from external APIs.

### 6.6 Latency & memory budget
- Budget: p99 **< 5 ms** per command, server-side; nothing in a request path may exceed **50 ms**. The client response timeout is 2 000 ms (`command_timeout_ms`, `lo-config/src/common.rs`) — a timeout there is an incident, not a tuning knob.
- Every plan adding a keyspace gives a **memory estimate** (`keys × avg size`, at 12 months). Redis has no `maxmemory` today (H1, ZAF-2190); with `noeviction` a full Redis fails writes loudly — so the memory estimate is a capacity commitment.
- Metrics: `redis_command_duration_seconds` by command (no key, no account id as label — label-cardinality rule).

### 6.7 Pub/sub channels
- Name `lumio:<domain>:<event>[:{account}]`. Pub/sub is fire-and-forget: a consumer that must not miss a message needs a durable source to resync from (DB read on reconnect). Every published channel has a named subscriber in the plan.

## 7. Object storage (`lo-storage`)

### 7.1 Naming
- **MUST:** `accounts/<account_id>/<kind>/<uuidv7>[.<ext>]` for tenant objects (`…/uploads/…`, `…/sounds/…`, `…/avatar/…`); `users/<user_id>/…` for user-owned objects; content-addressed shared objects (`extensions/<ext>/uploads/<sha>`) only for data that is **not** personal, or with a reference-counted delete (ZAF-2183). Legacy `<account_id>/…` upload keys are not renamed.
- **MUST:** the tenant/user id is the segment right after `accounts/` / `users/`, so a dissolution/user deletion can enumerate every kind with one `delete_prefix("accounts/<account_id>/")`. *Reason:* legacy uploads use `{account_id}/{uuidv7}` with no common prefix, which made them unreachable once their row was gone (F3).
- Object keys never contain user-supplied names, emails or other PII; the original file name lives in the Postgres metadata row.
- Every object has a Postgres metadata row (`uploads`, `sounds`, …) with `storage_key`, `content_type`, `size_bytes`, `account_id`, `created_at`. The row is the source of truth; an object without a row is an orphan.

### 7.2 Public vs private
- **Public** (served via `public_url`/CDN): only assets meant to be embedded publicly (overlay/widget assets, avatars, published extension bundles). Key contains an unguessable id; never listable.
- **Private** (exports, GDPR data exports, non-published uploads): served only via `presigned_download_url` with expiry ≤ 15 min, after an RBAC check.
- **MUST:** the plan states which one; default is private.

### 7.3 Cache headers
- Immutable keys (new key per new content — the default with `uuidv7`/sha256): `Cache-Control: public, max-age=31536000, immutable`. Never overwrite an object in place under the same key; write a new key and update the row.
- Private objects: `Cache-Control: private, no-store`.
- Today `upload()` sets only `Content-Type` — adding `Cache-Control` per kind is a `lo-storage` API change (Rust Backend).

### 7.4 Lifecycle & deletion
- **MUST:** every delete path of the metadata row (user action, cascade, dissolution, user deletion, retention) deletes the object **after** the DB commit, and failures go to a retry queue/table — not a log line. Cascaded row deletes can't call S3, so the deletion service collects keys **before** deleting the parent. The account delete does this through the `storage_deletion_queue` outbox (`services::storage_erasure`: keys queued in the delete transaction, deleted after commit, retried by the hourly account-security worker).
- **MUST:** temporary objects (exports, previews) carry an expiry: a bucket lifecycle rule on the prefix (S3/R2/MinIO) **and** an `expires_at` on the row, so the local backend is covered too.
- **SHOULD:** quota enforced at upload against `max_storage_bytes` (plan limit) by summing `size_bytes` — generic uploads check uploads + own sounds (`db::uploads::create_upload_within_quota`).
- **SHOULD:** a periodic orphan sweep over a prefix (`StorageClient::list_prefix` / `delete_prefix`, S3 `ListObjectsV2` or a local directory walk; the prefix must end in `/`).

## 8. Migration safety on large tables

### 8.1 Format
- **MUST:** reversible pair `<YYYYMMDDHHMMSS>_<name>.up.sql` / `.down.sql` (cutoff `20260410000000`); `.down.sql` restores the schema **exactly** — `apps/api/tests/migrations.rs` round-trips it (Serena `database/reversible-migrations`). A `.down.sql` that cannot restore data (dropped column) restores the **schema** and says so in a comment.
- **MUST NOT:** edit a merged migration — not even a comment. sqlx checksums the file; every database that applied it refuses to start (ZAF-433/434, ZAF-1769). Fix forward with a new migration.
- **MUST:** a migration version is unique across open PRs — check open PRs for the same timestamp prefix (ZAF-711 merge ordering). TSDB migrations live in `apps/api/tsdb_migrations/`, never in `migrations/`.
- `sqlx::migrate!()` embeds at compile time — a new file needs a rebuild of `lumio-api`.

### 8.2 Lock levels (tables in the the review triggers hot/large list, or > ~1 M rows)

| Operation | Lock | Rule |
|---|---|---|
| `ADD COLUMN` nullable or with a **constant** default | `ACCESS EXCLUSIVE`, metadata only | OK. Volatile default (`now()`, `gen_random_uuid()`) rewrites the table → **forbidden**; add nullable, backfill, then set default. (TSDB also rejects volatile defaults on compressed hypertables.) |
| `ADD COLUMN … NOT NULL` without default | rewrite/fails | Add nullable → backfill → `ADD CONSTRAINT … CHECK (col IS NOT NULL) NOT VALID` → `VALIDATE CONSTRAINT` → `SET NOT NULL` (uses the validated check, no scan). |
| `ALTER COLUMN TYPE` | `ACCESS EXCLUSIVE` + rewrite (except varchar widening, `varchar→text`) | **forbidden** on large tables; new column + backfill + switch reads + drop old in a later release. |
| `ADD FOREIGN KEY` / `ADD CHECK` | `SHARE ROW EXCLUSIVE` + scan | `… NOT VALID` in one migration, `VALIDATE CONSTRAINT` (`SHARE UPDATE EXCLUSIVE`, doesn't block writes) in the next. |
| `CREATE INDEX` | `SHARE` (blocks writes) | `CONCURRENTLY` per §3, `CONCURRENTLY` and the sqlx constraint (hypertables: `transaction_per_chunk`). |
| `ADD UNIQUE` / `PRIMARY KEY` | — | Build the unique index `CONCURRENTLY`, then `ADD CONSTRAINT … USING INDEX`. |
| `DROP COLUMN` | `ACCESS EXCLUSIVE`, metadata only | Only after a release in which no code reads it (expand → migrate → contract). |
| `RENAME` table/column | `ACCESS EXCLUSIVE`, instant | Breaks running old replicas during a rolling deploy → expand/contract (new name + view/dual write) unless the table is unused. |
| `VACUUM FULL`, `CLUSTER` | `ACCESS EXCLUSIVE` + rewrite | Never in a migration. |

- **MUST:** a migration touching a large table starts with `SET LOCAL lock_timeout = '5s';` (fail fast instead of queueing every writer behind an `ACCESS EXCLUSIVE` wait; `LOCAL` scopes it to the migration's transaction). `-- no-transaction` files hold one statement and cannot set it; `CONCURRENTLY` takes no write-blocking lock anyway. The API's migration runner (`lo_database::run_migrations`) also sets a session-wide `lock_timeout = '5s'` and `statement_timeout = 0` on its dedicated connection and retries a run that hits the lock timeout (every 5 s, 12 attempts). The `migrate` CLI binary (`apps/api/src/bin/migrate.rs`) runs sqlx's migrator directly without those settings, so the explicit `SET LOCAL` stays required.
- **MUST:** after deploying a `CONCURRENTLY` or `transaction_per_chunk` index migration, `SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;` on the affected database (for hypertables, the TimescaleDB) returns no rows. Both builds are non-transactional; an interrupted one leaves an `INVALID` index (or chunk index) that is maintained on writes but never used for reads. Drop and rebuild anything it lists.
- Compressed hypertables: schema changes that TSDB cannot apply to compressed chunks (some `ALTER TYPE`, drops of segmentby/orderby columns) require decompress → alter → recompress — that is an operation plan, not a migration, and needs the CTO + the SRE.

### 8.3 Backfills
- **MUST NOT:** `UPDATE big_table SET …` over all rows in a migration.
- **MUST:** backfills run as an idempotent job/worker in batches of 1 000–10 000 rows by PK/time range, one commit per batch, a short sleep between batches, resumable (cursor or `WHERE new_col IS NULL`), behind an advisory lock so only one replica runs it. Precedent: `milestones::backfill` (advisory lock, batches, background at start).
- On compressed hypertables backfill per chunk, newest first, and expect decompression cost — estimate it in the plan.

### 8.4 Deploy compatibility
- Old and new code run side by side during a rollout: a migration must not break the **previous** release's queries (no rename/drop of anything it reads). Sequence: expand (migration) → code using both → contract (later migration).

## 9. Template — `## Data design` section (Trigger 1 deliverable)

Written into the chain's `plan` document (or as a comment on the parent if the document can't be written). Omit sections that don't apply with `n/a — <why>`; never omit Retention or Verdict.

```markdown
## Data design

**Reviewer:** Data Architect · **Date:** YYYY-MM-DD · **Standard:** data-design standard v1 (the Data Architect review)
**Scope reviewed:** <plan revision / sections>

### Store choice
- <data>: **<Postgres | TSDB hypertable | TSDB cagg | TSDB table | Redis | pub/sub | object storage>** — because <decision-tree row + reason>.
- Not <alternative>: <why not>.

### Schema & keys
| Table | PK | Columns (type, null, default) | FKs (ON DELETE) | Notes |
|---|---|---|---|---|

### Indexes
| Index | Columns / predicate / INCLUDE | Serves query | Selectivity | Build (`CONCURRENTLY` / plain / `transaction_per_chunk`) |
|---|---|---|---|---|
FK columns covered: yes / <list missing>.

### Retention & compression
| Data class | Window | Mechanism | GDPR paths covered (erasure / user deletion / dissolution / expiry) |
|---|---|---|---|
Hypertables: chunk interval <x> (chunk ≈ <GB> at 12 mo) · segmentby <col> · orderby <col DESC> · compress after <x> · caggs <refresh / retention / compression>.

### Cache
| Key | Value / size | TTL | Invalidated by (GraphQL + REST) | Stampede protection | Memory @12 mo |
|---|---|---|---|---|---|
Pub/sub channels: <name → subscriber>.

### Objects
Key layout · public/private · Cache-Control · deletion paths · lifecycle/expiry · quota.

### Volume model
| Table / keyspace | Rows/day | Size/day | 12 months raw | 12 months compressed | Assumptions |
|---|---|---|---|---|---|

### Migration safety
| Migration | Table (size class) | Statement | Lock level | Strategy |
|---|---|---|---|---|
Reversible `.up/.down`: yes · backfill: <job, batch size, idempotency> · no merged migration edited · version prefix free across open PRs.

### Verdict
**must** (blocks the build until in the plan):
1. …
**should** (fine now, cheaper than later):
1. …
→ **Approved** / **Approved with musts** / **Rework** (state which).
```

A review that finds nothing is one line under `## Data design`:
`Fine as is: <store>, <retention>, <why it's bounded>. No musts.`

## 10. Trigger-2 diff check (for reference)

Before `gh pr ready` on a chain that had a Trigger-1 review, the Data Architect compares
`git diff origin/next...origin/<branch> -- apps/api/migrations apps/api/tsdb_migrations crates/lo-database crates/lo-cache crates/lo-storage`
against the `## Data design` section, item by item (PK, indexes + build mode, `ON DELETE`, retention/compression calls, TTLs, invalidation call sites on both protocols, object deletion). Result as an issue comment; mismatches name `file:line` and the fix.

---

---

## Developer Guide / Chat and event durability

Source: https://docs.lumio.vision/developer-guide/ingest-durability

# Chat and event durability

Platforms deliver most chat messages and events exactly once. EventSub over
WebSocket, the Kick and StreamElements sockets and most webhooks do not
redeliver, so whatever the API fails to store is gone. This page describes how
the API keeps that data when TimescaleDB, Redis or the process itself has a
problem, and what is still not covered.

## Guarantees at a glance

| Situation | Chat messages | Platform events (subs, gifts, bits, tips, raids …) |
|---|---|---|
| Normal operation | Redis buffer → batch insert every 5 s | Inserted directly, then broadcast |
| TimescaleDB down, slow or out of connections | Stay in the Redis buffer; after 5 failed flushes per account they move to the dead-letter list | Parked in the Redis dead-letter list; the live alert is still broadcast |
| TimescaleDB back | Flush resumes; dead letters replay within ~60 s | Parked events replay within ~30 s with their original id and timestamp |
| Redis refuses writes | Direct insert into TimescaleDB | Direct insert (normal path; Redis is only needed when that fails) |
| Both down | Lost, counted | Lost, counted |
| Deploy / `docker stop` (SIGTERM) | In-memory persistence queue drained into Redis, final flush | Events already parked stay in Redis for the next process |

## Chat messages

Every chat ingest path calls `lo_chat::buffer_or_persist`
(`crates/lo-chat/src/buffer.rs`): the message is pushed onto
`lumio:chat:buffer:{account_id}`; if that push fails it is inserted directly.
The chat flush worker (`apps/api/src/workers/chat_flush.rs`) drains the buffers
every 5 s. A batch that fails 5 times in a row moves to
`lumio:chat:deadletter:{account_id}` (72 h TTL), which a leader-gated drain
replays every ~60 s. The insert is idempotent (`ON CONFLICT DO NOTHING`), so
replays never duplicate.

## Platform events

Ingest paths (platform workers, webhooks, the 7TV and stream-status services)
persist events with `lo_events::persist_event`
(`crates/lo-events/src/durable.rs`):

1. The event gets its row `id` and `created_at` **before** the first insert
   attempt.
2. The insert is tried once, inline, for at most 3 s
   (`EVENT_INSERT_TIMEOUT`). Ingest loops are serial, so with a saturated pool
   waiting the full 30 s acquire timeout per event would stall alerts.
3. On a **transient** error (I/O, pool timeout, connection lost, statement
   timeout, the 3 s bound, serialization failure …) the event is appended to
   `lumio:events:deadletter:{account_id}` (72 h TTL, refreshed on every park)
   and the caller gets the row it will be stored as, so the live alert still
   goes out.
4. On a **permanent** error (SQLSTATE class `22`, `23` or `42`, or a decode
   error) nothing is parked; replaying it could never succeed. The error is
   returned and counted as `rejected`.

The event retry worker (`apps/api/src/workers/event_retry.rs`) replays the
lists every 30 s. One replica per cycle replays, the holder of
`lumio:events:deadletter:drain:leader`. For each account it drains the list and
inserts each event with its original `id` and `created_at`, so the event lands
in the stream session it happened in. It stops at the first transient error and
puts the rest back, and that ends the whole pass: the remaining accounts wait for
the next cycle, so replay never competes with live ingest for the TimescaleDB
pool while it is still unhealthy. The same Redis scan feeds the replay and the
`events_dead_letter_depth` gauge.

Replays are idempotent:

- events with an `external_id` keep the advisory-lock + `EXISTS` dedup on
  `(account_id, external_id)`;
- events without one conflict on the primary key `(id, created_at)`.

A replay that finds the event already stored counts as recovered.

Two callers keep the fail-fast `lo_events::insert_event`:

- REST `POST /v1/events/emit`: the client sees the error and can retry.
- The Spotify playback-control log (GraphQL and REST, the same on both). It
  records a dashboard user's own action, not a platform delivery.

### Not covered

- An event whose insert fails while Redis is also unreachable is lost.
- A parked event older than 72 h (by its original timestamp) is dropped on
  replay.
- A replayed event is not broadcast again. Its alert already went out when it
  was parked.
- Follow-up writes that target the row before it lands find nothing. The
  gift-bundle recipient enrichment is one example: the header row is replayed
  without the recipient list.
- The dead-letter list is drained with an atomic read-and-delete. A process
  killed between that read and the insert or re-park loses the batch.

## Shutdown

Docker and Kubernetes stop a container with SIGTERM, then SIGKILL after the
grace period (Docker default: 10 s). The API handles SIGTERM and SIGINT itself
(`apps/api/src/shutdown.rs`; actix's own signal handling is disabled):

1. The HTTP server stops gracefully. In-flight requests get 5 s, then open
   WebSocket sessions are closed.
2. At the same time, ingest and timer workers are cancelled. The per-account
   platform workers get 5 s to stop. The Twitch EventSub worker drains its
   in-memory persistence queue into the Redis chat buffer before it reports
   stopped.
3. The chat flush worker is cancelled last and runs one final flush, bounded
   to 3 s.

The drain takes at most 8 s, so keep the container stop grace period at 10 s or
more. Whatever is still in Redis afterwards is picked up by the next process.

`crawler-twitch` also handles SIGTERM. Its writer flushes what is already on the
result bus. A shard's current aggregation window, not yet published to the
bus, is not covered.

## Database timeouts

The API pools set `statement_timeout` on every connection
(`[database]` / `[timescale]` `statement_timeout_secs`, default `30` in
`apps/api/config/default.toml`; `0` = no limit). One runaway query is cancelled
(SQLSTATE `57014`) instead of holding one of the five TimescaleDB connections
indefinitely and stalling chat flush, event ingest and audit writes at once. A
cancelled event insert is transient, so the event is parked, not lost.

Work that legitimately runs longer lifts the limit for one transaction with
`lo_database::begin_unbounded` (or the crate-local equivalent):

- retention deletes (chat, events, GIF content);
- GDPR erasure deletes and the data-export reads;
- the account dissolution `DELETE`.

Startup backfills run on a separate one-connection TimescaleDB pool without the
limit, which is closed once they finish. Code on that path must never acquire
from the pool while it holds a transaction from the same pool: the second
acquire waits for the one connection the transaction already holds, fails after
`connect_timeout`, and the boot stalls before the server binds. Reads inside a
transaction go through the transaction (query helpers take
`impl sqlx::PgExecutor<'_>`, not `&PgPool`).

Migrations (`lo_database::run_migrations` / `run_tsdb_migrations`) run on a
dedicated connection with `statement_timeout = 0` and `lock_timeout = '5s'`. A
DDL statement queued behind a long query would otherwise block every later query
on that table. With the timeout it gives up and is retried every 5 s, up to 12
times, then startup fails. The connection is closed afterwards, so neither
setting reaches the pool. A second replica that waits on the migrator's advisory
lock meanwhile gives up after the same budget, about 2 minutes.

`crawler-twitch`, `bot-module-worker` and `automation-worker` share
`lo-database` but not the API config, so their pools have no
`statement_timeout` unless their own config sets `statement_timeout_secs`.

## Metrics

| Metric | Meaning |
|---|---|
| `events_persist_failures_total{outcome}` | Failed event inserts by outcome: `parked`, `recovered`, `lost`, `rejected`. Any `lost` is event loss |
| `events_dead_letter_depth` | Parked events across all accounts, measured from Redis every 30 s. Not returning to `0` = replay is stuck |
| `chat_*` | See [Metrics](./metrics.md#chat-domain-series-zaf-680-2) |

No series carries an account label (cardinality rule).

---

## Developer Guide / Volume tests (pinned query plans)

Source: https://docs.lumio.vision/developer-guide/volume-tests

# Volume tests (pinned query plans)

Most data-layer regressions only show with data volume. A test that seeds a handful of rows stays green when a statement's plan degrades to "decompress every batch" or "one probe per historical row". The volume tests seed a realistic data set into TimescaleDB and pin the plan that production statements get on it.

- Fixture: `apps/api/tests/common/volume.rs`
- Pinned plans: `apps/api/tests/volume_plans.rs` (Bazel target `//apps/api:integration_volume_plans`, tag `requires-tsdb`)

## Assert plan counters, never milliseconds

Every pin runs `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` and asserts structural facts:

- node types (no `Sort`, no `Seq Scan`, one `ModifyHypertable`, …)
- `Chunks Visited` and the chunks a plan touches
- `Batches checked by bloom` / `Batches pruned by bloom`
- `Batches decompressed`, `Batches deleted`, `Tuples decompressed`
- `Tuples Inserted`, `Conflicting Tuples`, conflict arbiter indexes
- `Actual Loops` of scans on a table (per-row probes)
- shared buffers touched or dirtied, with a budget of at least 3× the measured count

Timings are printed for humans only. The test host is shared and CPU-capped, so a millisecond assertion would be a flaky test.

## Profiles

| | `small` | `large` |
|---|---|---|
| Used by | every PR (CI job *API tsdb Migration Test*) | manual, before a data design check on a hot table |
| Accounts | 20 | 200 |
| Chat rows | 200 000 over 21 days | 4 000 000 over 14 days |
| Events | 20 000 | 200 000 |
| Crawler | 2 000 live streams × 60 one-minute samples | 30 000 live streams × 120 one-minute samples |
| Crawler streams in total | 6 000 (1 live + 2 ended per channel) | 90 000 |
| `platform_users` (main Postgres, P11 only) | 10 000 | 157 000 |
| Database size | ~110 MB | ~2.3 GB |
| Seed time on the host test stack | ~7 s, once per server and day | ~3.5 min, every run |

The data has the shape of the capacity model:

- **Skewed accounts.** Each row picks its account as `1 + floor(N * random()^3)`. In `large` the biggest account holds about 17 % of the rows; in `small` it holds about 37 %. Chatters are skewed with `floor(C * random()^2)`.
- **Several chunks, mostly compressed.** Every chunk older than its hypertable's `compress_after` is compressed. Most plan regressions only show on compressed chunks. The newest chunk holds the anchor time and stays uncompressed. The anchor is `now()`, moved to at least 30 % into its chunk.
- **Realistic row widths.** Chat rows are about 735 B including indexes and carry JSONB badges and emotes, a 36-character `platform_message_id` and an avatar URL. Events carry a JSONB payload of about 1 KB.
- **Crawler rows.** Crawler sessions and streams have `account_id` set to the nil UUID and `source = 'external_crawler'`. The fixture leaves the crawler sessions open - the worst case for the first-party work list: a crawler that is down, or rows written before the crawler's close sweep (ZAF-2193).

## Running

Small profile (all non-ignored pins, ~10 s on a warm server):

```sh
DATABASE_URL="$TEST_TSDB_DATABASE_URL" RUN_TSDB_MIGRATION_TEST=1 \
  cargo test -p lumio-api --test volume_plans
```

Large profile (every pin plus one report table, ~4 min):

```sh
DATABASE_URL="$TEST_TSDB_DATABASE_URL" RUN_TSDB_MIGRATION_TEST=1 \
  cargo test -p lumio-api --test volume_plans -- --ignored large --nocapture
```

The large run checks free disk space first. It needs at least 20 GiB free on `/workspace`, or on `/` if `/workspace` does not exist; set `VOLUME_DISK_GUARD_PATH` to check another path. It seeds into its own `lumio_vol_<unix>_<uuid>` database and drops it at the end, including when it fails. It asserts the pins that are green on `small`. For pending pins, the report says whether they still fail as expected or now pass, in which case you remove their `#[ignore]`.

Human developers point `DATABASE_URL` at the Dev Stack's TimescaleDB server (see [Installation](../getting-started/installation.md)).

## How the fixture works

- **Real schema.** The fixture applies the real `apps/api/tsdb_migrations` tree, never a copy. It deschedules every background job right after the migrations, because `add_job` fires immediately and a policy would race the seed.
- **Deterministic seed.** Seeding is set-based: `setseed(0.42)`, `generate_series`, rows written in time order, one day per statement, no round trip per row. Ids are `md5('zaf2196-…' || n)::uuid`, so a test can name any seeded row. `fixture_small_shape` pins checksums of the seeded ids and values. If you change the seed SQL, bump `SEED_VERSION` and re-pin the checksums.
- **One template per day.** `small` is seeded once per server, migration set and UTC day into the template `lumio_vtmpl_<hash>_<yyyymmdd>`. Each test gets a `CREATE DATABASE … TEMPLATE` clone, which is dropped when the test ends. Clones a killed process left behind, half-built templates and templates older than two days are pruned the next time a template is built. Never touch `lumio_v*` databases by hand.
- **TimescaleDB scheduler.** TimescaleDB keeps a background scheduler connected to every database that has the extension, and `CREATE DATABASE … TEMPLATE` fails while anyone is connected. Renaming a database stops its scheduler, and `ALLOW_CONNECTIONS false` keeps it from coming back. The fixture therefore builds the template as `lumio_vbuild_…` and renames it when complete; the rename also marks the template as finished. `common::test_db()` parks its own template under another name and back for the same reason, so it also works on a TimescaleDB server.

## Pinned plans

| # | Statement (source) | Pinned property | Status |
|---|---|---|---|
| P1 | Chat history first page (`lo_chat::queries::list_messages_before`, floored at the 30-day walk window) | 1 chunk visited, no decompression, buffer budget; ordered per-account index scan without `Sort` for a typical account; an unknown account visits at most window + 1 chunks, decompresses no tuple and stays within a per-chunk **and** an absolute buffer budget (planning + execution, warm connection); the window-edge catalog probe opens no data chunk; end to end the unknown account's first page ends its history. `p1_aged_small` adds 365 compressed one-day chunks (rolled back) and proves the unbounded page would blow the absolute budget. The plan shape production runs is pinned too (ZAF-2254): both keyset reads leave no prepared statement after six runs on one connection (so every request gets a custom plan), the page sent with bound values on an unnamed statement stays bounded on every one of six runs, and the generic plan a cached statement could switch to lists every chunk | green |
| P2 | Plan retention delete (`delete_old_messages`, one slice of the sweep's walk: lower bound at the oldest chunk), cutoff inside a compressed chunk | batches below the cutoff deleted by metadata, ≤ 2 % of the account's batches decompressed | green; needs the explicit `compress_orderby` (ZAF-2197) |
| P3 | Single-message soft-delete (`soft_delete_message`) as a prepared statement, generic plan | ≥ 90 % of the checked batches pruned by bloom; hit, repeat and unknown id | green |
| P4 | Ban/timeout soft-delete (`soft_delete_user_messages`) | `Tuples decompressed` < 10 000; every message of the chatter in the 24 h window flagged, another chatter untouched | green |
| P5 | Event dedup probe (`lo_events::queries::insert_event`) | only chunks inside the 7-day dedup window touched | green |
| P6 | Chat flush insert, 1 000 rows (`insert_messages_batch`) | one `ModifyHypertable`, 0 conflicts, ≤ 3 buffers dirtied per row; the replay inserts nothing | green |
| P7 | GDPR erasure by `(platform, user_id)` (`delete_messages_for_platform_user`) | the `user_id` bloom keeps every batch without the subject closed: decompressed batches ≤ erased rows + 2 % of the checked batches | green |
| P8 | Public browse `COUNT` on the direct path (`public_stats_browse::browse_channels_from_streams`, used until the browse read model is backfilled): generic plan for the default page and the live filter, custom plan for the live filter | only open stream rows probe `channel_history_stats`, each chunk scanned at most once per open row and at most two scans per open row (the freshness window's chunks); closed rows never probe | green |
| P9 | Sampler work list (`channel_history::list_open_sessions`) | no crawler (nil-account) session; first-party sessions still listed | green |
| P10 | Crawler `UNNEST` sample insert (`apps/crawler-twitch/src/writer.rs`) | one statement, arbiter `idx_channel_history_stats_sample`, an unchanged re-poll updates nothing | green |
| P11 | Chat-flush `platform_users` write (`lo_chat::upsert_chatter_batch`), main Postgres | ≥ 50 % HOT updates (`n_tup_hot_upd / n_tup_upd`) | green |
| P12 | Event list (`lo_events::list_events`): the dashboard home feed page and its capped count, without `from`, after 365 days of compressed history are added (rolled back) | page and count visit at most the chunks of the 30-day default window + 2, also for a filter nothing matches; the count's inner `LIMIT` is `LIST_TOTAL_CAP + 1`; the same statements over the whole history open more than twice that, proving the window bounds them | green |
| P13 | Crawler close sweep (`apps/crawler-twitch/src/writer.rs` `close_stale_streams`), generic plan: steady state and backlog | steady state closes nothing, backlog closes every stale live stream in one batch; no compressed `channel_history_stats` chunk scanned, no tuple decompressed | green |
| P14 | Crawler stream + session upserts (`writer.rs` `write_stream_rows`) for every open crawled stream as one flush | one statement each, arbiter `uq_channel_history_streams_public_key`; an unchanged re-poll updates nothing; a peak rise updates every row and some updates are HOT (no index covers `peak_viewers`) | green |
| P15 | Crawler stream-metadata diff (`writer.rs` `write_stream_metadata_history`) for the same flush | one statement; the latest value per broadcast and field comes from `idx_public_stream_metadata_history_broadcast`; no sequential scan of the stream or history table; an unchanged re-observation inserts nothing | green |
| P16 | Public browse on the read model (`public_stats_browse::read_model_*_sql`): every channel page (6 sorts × all / live / offline), page 200, the COUNTs, search, category page and count, category + search, Games page / search / count — after extra closed streams are seeded (`small` 100 k / 10 k channels; `large` 1 M / 50 k) plus one stream in each of 25 000 extra categories and the read model is built with the worker steps, then again at twice the streams | no read of `channel_history_streams` / `channel_history_stats`; buffer budgets; the index top-N shapes cost the same at 2× the streams. `large` (1 M → 2 M streams, 30 k open, 2026-10-14): pages ≤ 0.1 ms, `live` / `offline` tab ≤ 3.2 ms (O(live channels) when the planner reads the live table in full), page 200 ≤ 6.4 ms, COUNTs ≤ 3.3 ms, Games over 25 k categories ≤ 40 ms. Category + search walks the category's pairs (O(category), not O(page)): ≤ 10 ms for a ~6 k-pair category; if a real category approaches 100 k pairs, copy the channel identity onto the pair grain. Manual run of this pin alone: `-- --ignored p16_large --nocapture` | green |
| P17 | Bot-module `chat:delete` (`lo_chat::get_message_text` + `soft_delete_platform_message`) with the 6 h lookback bound as a literal (the statements run unprepared): a fresh message, and a message from the oldest, compressed chunk | every statement plans against ≤ 2 chunks and probes `idx_platform_chat_messages_dedup`; the fresh message is found and flagged, the old one is out of bound: nothing found, no tuple decompressed | green |

## Writing a pin

1. **Run the production SQL.** When the statement is assembled at run time, call the public builder production uses (P16: `read_model_channel_sql` and its siblings). Otherwise read the statement out of its source file with `source_fn_sql(SOURCE, "function", "fragment")` or `source_const(SOURCE, "CONST")`, using `include_str!` on the file. If the file lives outside `apps/api`, also add it to the target's `compile_data` in `apps/api/BUILD.bazel` and to `exports_files` in its own package. A rewritten statement then fails the pin loudly instead of silently testing stale SQL. A statement assembled with a `QueryBuilder` is exposed by its crate as a `push_*` builder function instead (P12: `lo_events::push_list_events_count` / `push_list_events_page`); the pin starts a builder with `explain("")` and pushes the production statement, binds included.
2. **Pick the plan production gets.** sqlx runs statements as prepared statements, and after a few executions Postgres may switch to the generic plan. Postgres keeps using custom plans while they are cheaper on average, so production runs both shapes. If a parameter decides the plan (for example `$4 IS NULL OR …`), pin the generic plan with `SET LOCAL plan_cache_mode = force_generic_plan` + `PREPARE` + `EXPLAIN … EXECUTE`, and pin the custom plan (`force_custom_plan`) too for every parameter value that needs the part under test. A custom plan with a NULL parameter can legitimately drop the join you meant to test, so that case is not a pin.
3. **Keep the data unchanged.** Run mutating statements inside a transaction and roll it back.
4. **Assert counters with the `Plan` helpers:** `executed_kinds()`, `sum("Batches pruned by bloom")`, `shared_buffers()`, `scanned_relations()`. TimescaleDB nests a `DeferredChunkAppend` child under `Plan` rather than `Plans`, and a compressed chunk's batches are scanned as `<chunk>_compressed`. The helpers handle both.
5. **Cover the happy path and the failure cases:** a hit and a miss, a replay or repeat (idempotency), an unknown id.
6. **If the fix is still pending**, mark the test `#[ignore = "ZAF-…: reason"]` and remove the ignore in the PR that ships the fix. Add the pin to the `large_profile_report` list.

---

## Developer Guide / Stream History: adding a platform

Source: https://docs.lumio.vision/developer-guide/stream-history-platforms

# Stream History: adding a platform

Stream History records each stream **session** (a session may span several
simultaneous platform broadcasts = multistream) and its aggregate metrics. It is
built platform-neutral: a platform is **data, not schema**. Adding a new platform
(Kick was the last one) is a small, bounded change - never a migration, and
never a change to the sampler, finalizer, API, or charts.

This guide describes the backend adapter layer (`apps/api/src/services/history/`)
and the exact steps to add a platform.

## Design principle: platform is data, not schema

- **Database** (`apps/api/tsdb_migrations`): the three history tables
  (`channel_history`, `channel_history_streams`, `channel_history_stats`) use
  `platform TEXT` everywhere - no SQL enum, no per-platform columns. Anything
  platform-specific lives in the JSONB `platform_metrics` with namespaced keys.
- **Backend**: one `HistoryPlatformAdapter` per platform, held in a registry the
  sampler/finalizer iterate over. There is no `match platform` outside the
  adapters. An event whose `platform:` prefix has no adapter is logged and
  ignored - never a panic, never data loss.

## The adapter trait

`apps/api/src/services/history/platforms/mod.rs`:

```rust
pub trait HistoryPlatformAdapter: Send + Sync {
    /// Platform key, matching the `platform:` prefix of its event types.
    fn platform(&self) -> &'static str;

    /// Whether this platform drives `channel_status` (and can start a session).
    fn drives_sessions(&self) -> bool;

    /// Map one `platform_event_logs` event onto normalized metric deltas.
    fn classify(&self, event: &PlatformEventRow) -> Vec<MetricDelta>;

    /// Platform-specific live values for the 60s sample (default: none).
    fn sample_metrics(&self, status: &ChannelStatusSnapshot) -> serde_json::Value;
}
```

`classify` returns a list of `MetricDelta`, each a single normalized
contribution the finalizer folds into the session aggregates:

| `MetricDelta` | Meaning |
|---|---|
| `Follower` | A new follower, or the platform's follower equivalent |
| `PaidSub` | A new **paid** subscription / membership (not a gift, not Twitch Prime) |
| `GiftedSubs(n)` | `n` gifted subs / memberships |
| `Donation { cents, currency }` | A **genuine viewer donation** (e.g. a StreamElements tip) in integer cents of its own currency - no FX conversion. Platform-native monetization (bits, Super Chats) is **not** a donation - see below |
| `PlatformCounter { key, by }` | Increment a namespaced counter in `platform_metrics` (e.g. Twitch `bits`, YouTube `superchats`) |

### Normalization conventions

- **Follower-equivalent** - the platform's "new follower" signal. Twitch and Kick
  use their `follower` event. YouTube has no real new-subscriber event
  (`youtube:subscribe` is a repurposed video-upload signal), so its follower
  equivalent is derived from a channel `subscriberCount` delta, not from
  `classify`.
- **Paid-sub-equivalent** - new *paid* recurring support. Twitch and Kick paid
  subs/resubs and YouTube new memberships count; Twitch Prime does **not** (a
  platform counter only); gifts are `GiftedSubs`. A resub (`twitch:resub`,
  `kick:resub`) additionally increments the `resubs` platform counter.
- **Currency** - donation amounts are normalized to integer cents of the event's
  own currency. Virtual currencies (Twitch bits, Kick KICKs) are platform
  counters, not donations.
- **Bits / Super Chats / Super Stickers are a distinct monetization category, not
  donations** (ZAF-583 §5 field-visibility ruling (a), founder 2026-08-20). Twitch
  `cheer` (bits) and YouTube `superchat` / `supersticker` emit only namespaced
  `PlatformCounter`s - a count (`bits`, `superchats`, `superstickers`) plus, for
  Super Chats/Stickers, an account-only `*_amount_cents` total - and **never** a
  `Donation`. They must never fold into `donations_total_cents`: donations stay
  never-public, whereas these categories are public as **counts only, never
  identities**. Kick's `kick:kicks` belongs to the same category: one
  `PlatformCounter { key: "kicks", by: <amount> }`, never a `Donation`.
- **Donations are StreamElements tips only.** `streamelements:tip` is the only
  event that emits a `Donation`; every report/email/export surface labels the
  metric "Donations (StreamElements)" so it is not confused with bits or Super
  Chats (ZAF-745). Sessions finalized before the ZAF-601 fix (2026-08-21) folded
  Super Chat/Sticker money into donations; a boot-time re-fold backfill
  (`backfill::backfill_monetization_split`) re-derives them from the retained
  event log and rewrites the tips-only total (idempotent, best-effort).
- **Raids** - an **incoming** raid is a `PlatformCounter` pair: `raids` (count) +
  `raid_viewers` (incoming audience). Twitch (`twitch:raid`, `viewers` in raw) and
  **not** counted. Kick's webhook catalogue exposes no host/raid event, so Kick
  contributes none. Raids are not monetization - never a `Donation` (ZAF-745).
- **Platform-aware terminology** follows the scope of the number. A Twitch-only or Kick-only scope says **Followers / Subs** (de: **Follower / Subs**). A YouTube-only scope says **Subscribers / Members** (de: **Abonnenten / Mitglieder**), with `≈` on rounded YouTube subscriber values. A mixed scope says **Followers & Subscribers / Subs & Members** (de: **Follower & Abonnenten / Subs & Mitglieder**); the per-platform breakdown keeps each native term. Apply the same rule after a platform filter, even when the underlying session is a multistream. Do not call paid subs “Abo” in German: it collides with YouTube's free Abonnenten. The Twitch tier chart covers Twitch tiers only; YouTube members sit separately.
- **Gift tiers and bundle counting** - Twitch gift tiers (`gift_subs_t1/t2/t3`) are priced separately. A community gift consists of a header and recipient rows tied by `community_gift_id`; the classifier counts the header and skips bundled recipient rows, so N gifts count N times, not 2N. A targeted gift without that id counts normally. The boot backfill corrects `gifted_subs`, `twitch.gift_subs`, and the platform breakdown while event logs remain retained; older frozen sessions without those logs keep the assumed tier-1 note. The `channel.subscribe` EventSub recipient signal is not stored as a `PaidSub`, so `new_paid_subs` does not double-count it.
- **Twitch and Kick ads** - `twitch:ad_break` and `kick:ad_break` yield `ad_breaks`, `ad_breaks_automatic`, and `ad_seconds`. Finalization freezes the break list and viewer spots. Estimated gross impressions are viewers at break start × `ceil(duration_seconds / 30)`; the editable ad-free share applies at read time. Missing CPM leaves an unpriced `cpm_missing` line. Kick's feed comes from the ad-break status poller, while YouTube has no ad-break feed.
- **Super Chat currencies** - YouTube Super Chats and Stickers accumulate `superchats_amount_by_currency` / `superstickers_amount_by_currency`. Their legacy combined `*_amount_cents` fields remain for compatibility but can mix currencies. Conversion and totals use the per-currency values; old mixed rows are labelled `mixed_currencies` rather than given a false exchange rate.

### Kick

The Kick adapter reads the canonical top-level fields the Kick webhook receiver
adds at ingest (`lo_kick_api::normalize_event`, see
[Webhooks](../features/webhooks.md#kick)):

| Event | Deltas |
|---|---|
| `kick:follower` | `Follower` |
| `kick:subscribe` | `PaidSub` |
| `kick:resub` | `PaidSub` + `PlatformCounter { key: "resubs", by: 1 }` |
| `kick:gift` | `GiftedSubs(n)` + `PlatformCounter { key: "gift_subs", by: n }`, where `n` = `giftCount` (the number of giftees; a gift to 5 viewers counts 5). A row stored raw without canonical fields falls back to counting `giftees`, then to 1 |
| `kick:kicks` | `PlatformCounter { key: "kicks", by: kicks }` (nothing when the amount is 0) |
| `kick:reward`, `kick:reward_status`, `kick:stream_*` | none |

The separate Kick ad poller (`services/kick_ads.rs`) calls `GET /public/v1/ads/ad-break-status` only when a Kick stream is live and the stored grant includes `ads:read`, plus one final call. The first live call is due five minutes after stream start. Subsequent calls use half of `limits.period_seconds`, clamped to 5–60 minutes (five minutes when the provider gives no window). A Redis lock permits one poller per session. Provider 429/5xx and transport errors use exponential backoff and `Retry-After`; after three failures polling stops for that stream. A 403 stops immediately and removes `ads:read` from the stored grant. Each newly observed break becomes a `kick:ad_break` event with `duration_seconds`, `source`, `status`, `started_at` and `ad_break_id`; the event is not a webhook. The poller uses `get_fresh_connection_token` and records each outgoing call in `platform_api_requests_total`.

`drives_sessions` is `true`. Kick's live status runs through the same
`channel_status` service as Twitch (`services/kick_live_status.rs`): the
`livestream.status.updated` webhook calls `set_online` / `set_offline`, the
Kick worker's start reconcile and the 60-s poll while live
(`workers/kick_live_status.rs`) correct a missed webhook. `set_online` fires
the `on_platform_online` hook, so a Kick-only stream opens its own session;
alongside Twitch or YouTube it adds a `kick` stream row to the same session
and promotes it to `multi`. The poll writes the viewer count into the Redis
status snapshot, and the 60-s sampler turns it into the Kick stream's peak and
average viewers. The Kick `broadcast_id` is the stream start time
(`started_at` in the webhook, `stream.start_time` in the API), normalised to
UTC seconds.

## The registry

`HistoryAdapterRegistry::with_builtins()` seeds every adapter. Built-ins today:
`twitch`, `youtube`, `streamelements`, `kick`. Twitch, YouTube and Kick drive
sessions; StreamElements has `drives_sessions = false` (its events are counted
inside a session another platform started).

```rust
pub fn with_builtins() -> Self {
    let mut reg = Self::new();
    reg.register(Box::new(twitch::TwitchAdapter));
    reg.register(Box::new(youtube::YouTubeAdapter));
    reg.register(Box::new(streamelements::StreamElementsAdapter));
    reg.register(Box::new(kick::KickAdapter));
    reg
}
```

## Session lifecycle

`apps/api/src/services/history/session.rs` hooks into the channel-status service
(`set_online` / `set_offline` / `set_broadcast_offline`), so every online/offline
transition - from the workers and from startup recovery - feeds history exactly
once. History is analytics: the hooks are best-effort and never fail the live
status path.

- **online** - find or open the account's session; attach this platform's stream
  row. A reconnect within the 5-minute grace window continues the same stream
  (no duplicate); a second distinct platform promotes the session to `multi`.
- **offline** - end the matching stream row(s). The session stays open through
  its grace window.
- **grace close / orphan recovery** - the grace window is derived from TSDB
  (`max(stream.ended_at) + 5min < now`), so correctness never depends on Redis.
  Startup recovery closes sessions left open by a restart mid-stream-end.

## Channel identity (frozen at open)

Each `channel_history_streams` row carries the streaming channel's identity,
**frozen at stream open** so a recorded session is channel-attributable without a
live JOIN back to the main-DB `channel_connections` (a separate Postgres instance
that is gone once the account is dissolved). Three nullable columns:

| Column | Source | Meaning |
|---|---|---|
| `platform_channel_id` | `channel_connections.platform_channel_id` | stable platform channel id - the join key for the channel page |
| `channel_login` | `channel_connections.channel_name` | handle / slug as-of-session (the URL spelling) |
| `channel_display_name` | - (no source today) | display name as-of-session; always `NULL` for now |

Capture rules:

- **Resolved once, at the online transition** in `channel_status::set_online`,
  from the same `connections::get_connection(pool, account_id, platform)` lookup
  the startup verifiers use, and threaded into the session hook.
- **Written exactly once** by `db::create_stream`. `db::reopen_stream` (a
  grace-window reconnect) deliberately does **not** touch these columns - the
  stream keeps the identity captured when it first opened, so a later handle
  rename never rewrites history.
- **Honest `NULL`, never guessed** - a momentarily-unreadable connection writes
  `NULL` rather than a placeholder, and never blocks the (best-effort) status
  path. `channel_connections` exposes a single `channel_name` (a handle/login/slug
  on every platform, never a display name), so it maps to `channel_login` only;
  `channel_display_name` has no source and stays `NULL`.
- **Public addressability** - a partial-unique index on `(platform, broadcast_id)
  WHERE broadcast_id IS NOT NULL` makes the platform-native broadcast id the URL
  key; `(platform, platform_channel_id, started_at DESC)` lists a channel's
  streams newest-first.

Legacy rows recorded before this capture landed are filled by an idempotent
startup backfill (`services::history::backfill::backfill_stream_identity`) that
reads the current `channel_connections` and `UPDATE`s rows whose
`platform_channel_id` is still `NULL`; the rest stay `NULL` (unresolvable, never
guessed). It logs the coverage ratio (`filled/total`) on every boot.

## Provenance (`source`)

Each `channel_history_streams` row also carries a **provenance** flag recording
*how* the row was discovered - the basis for the public "Lumio channel" badge on
the future stats surface:

| `source` | Meaning |
|---|---|
| `first_party` | Recorded from a **connected Lumio channel** (the default, and the only writer today). This value **is** the public "Lumio channel" badge. |
| `external_crawler` | Materialized by the future crawler-discovery path. No writer yet - that writer ships with the crawler issue. |

- **`source TEXT NOT NULL DEFAULT 'first_party'`.** The constant default is
  retroactively correct for every existing row: all pre-crawler data is, by
  definition, first-party, so the column is added with **no backfill**.
- **Write path unchanged.** The first-party path (`db::create_stream`) simply
  inherits the column default; the only non-default writer (`'external_crawler'`)
  belongs to the crawler-discovery path, not the recording path here.

## Sampler & finalizer

One global worker (`apps/api/src/workers/history_sampler.rs`) on a 60-second tick
runs both jobs. It knows no platform names - it iterates the registry.

- **Sampler** - for every open session it writes one `channel_history_stats`
  sample per live platform: the viewer count and live values come from the Redis
  status snapshot (see below), platform-specific values from the adapter's
  `sample_metrics`. Cumulative counters (messages / followers / subs / donations)
  are counted **incrementally since the last sample** and added onto the interim
  totals held in a per-session Redis sampler-state key, so per-tick cost stays
  constant on a marathon stream instead of re-counting from session start.
- **Finalizer** - once the grace window closes a session, it computes the
  aggregates **once** and persists them, flipping `finalized = true`:
  - messages / unique + top-10 chatters from `platform_chat_messages`, each
    entry `{ user_id, name, platform, avatar_url, count }` - `avatar_url` is a
    representative avatar taken from the chatter's messages and is `null` when
    the platform's ingestion captured none;
  - followers, paid subs, gifted subs, Twitch tier breakdown + bits, Kick
    `kicks` / `resubs` / `gift_subs`, YouTube
    memberships / superchats / superstickers, incoming raids (`raids` +
    `raid_viewers`, Twitch), and donations - all via `classify`;
  - donations are kept **per currency** (no FX conversion): the denormalized
    `donations_total_cents` / `donations_currency` columns hold the dominant
    currency for the list preview, the full map lives in
    `platform_metrics.donations_by_currency`. **Bits and Super Chats / Super
    Stickers are excluded from all of these** - they are their own category
    (counts + account-only `*_amount_cents`) under `platform_metrics.twitch` /
    `platform_metrics.youtube`, never donations (§5 ruling (a); see Normalization
    conventions);
  - emote count + top-10 from the messages' `emotes` JSON, each entry
    `{ emote, provider, url, count }` - `url` is a representative image URL
    lifted from the stored emote objects. All supported chat platforms can appear here:
    Twitch builds the `static-cdn.jtvnw.net` URL from the fragment's emote id,
    YouTube resolves it from the InnerTube emote cache, and **Kick** builds
    `https://files.kick.com/emotes/{id}/fullsize` from the `[emote:ID:NAME]`
    marker Kick puts in the message `content` (ZAF-1622), so every Kick entry
    carries a `name` and a `url`.
    A `top_emotes` entry that is still missing a `url` (e.g. a report finalized
    before URLs existed) is resolved from the
    catalog **at read time** in `service::build_report_for` /`build_export`
    (`lo_chat::resolve_emote_urls`, keyed on `(provider, name)`); an entry that
    already carries a `url` keeps its frozen snapshot. The resolution is
    best-effort and fail-open - an unavailable catalog degrades to the shorthand
    plus a provider icon, never a failed report - and it covers the CSV/JSON
    exports and the public share page, which reuse the report builder. The summary
    e-mail uses report data but does not display emote counts or top-emote lists.
    Emote counts are **per-platform, not cross-platform,
    comparable** (ZAF-570): both aggregates read the same `emotes` array, so
    `emote_total` (`SUM(jsonb_array_length)`) and `top_emotes` (`COUNT(*)` over
    `jsonb_array_elements`) never disagree *within* a channel. Across platforms the
    magnitudes differ in spirit because the writers count differently: Twitch and
    **Kick** ingest store **one entry per emote occurrence** (Twitch: one per `emote`
    fragment; Kick: one per `[emote:ID:NAME]` marker, so `Kappa Kappa` → 2), while
    the YouTube enricher **dedupes to one entry per shortcode per message**
    (`enrich_message_emotes_from_sets`, matched by name, so `Kappa Kappa` → 1).
    Stored Kick rows were rewritten to the per-occurrence shape by the TimescaleDB
    migration `20260930000001_kick_chat_emote_markup_backfill`; the frozen totals
    of Kick reports finalised before it are **not** recomputed and keep their
    deduped counts. The YouTube asymmetry is deliberately **not normalised**: the
    deduped shape is exactly what the chat renderer consumes, and rewriting that
    writer would retroactively change already-frozen report totals. Per-platform
    ranking and trends stay correct; only absolute totals are not directly
    comparable between YouTube and Twitch/Kick;
  - cross-platform peak/avg viewers from the samples.
  A running (not-yet-finalized) session's aggregates are computed on the fly with
  the same code, cached briefly in Redis.

### YouTube follower equivalent

YouTube has no real new-subscriber event, so the follower count comes from the
channel `subscriberCount`: the sampler captures it at session start and the
finalizer re-reads it at close (two Data-API calls per session, or zero via
InnerTube). The delta is added to `new_followers` and marked approximate in
`platform_metrics.youtube` (`followers_approx`), because YouTube rounds public
subscriber counts to three significant figures. `youtube:subscribe` is a
repurposed upload signal and is ignored for follower counting.

### channel_status slim-down

Live counters (viewer count, YouTube likes/views) now live in the Redis status
snapshot and the 60-second history sample, **not** in per-poll Postgres writes.
`channel_status` is written only on real state transitions (online / offline /
upcoming / `live_chat_id` / title / category change). The dashboard endpoints
(`channelStatus` GraphQL query and `GET /v1/channel-status`) overlay the live
counters from the Redis snapshot, falling back to the latest history sample when
the cache is cold - so they never show a frozen value. See
[Channel status](./channel-status).

## Steps to add a platform

1. **Emit events** in the platform worker under the `platform:action` convention
   (e.g. `kick:follower`) into `platform_event_logs` - this is the ingest side.
2. **Add an adapter** `apps/api/src/services/history/platforms/<platform>.rs`
   implementing `HistoryPlatformAdapter`. Map its events in `classify`; expose
   any live values in `sample_metrics`. Set `drives_sessions` - `false` until the
   platform also drives `channel_status`.
3. **Register it** in `HistoryAdapterRegistry::with_builtins()`.
4. **Unit-test `classify`** with representative payloads (positive and unknown-
   action cases), following the existing adapter tests.
5. **Frontend** (when the UI ships): add metric-descriptor entries + icon + i18n
   (`en` + `de`) for any new `platform_metrics` keys; unknown keys render with a
   generic fallback.

To make a platform a **session driver** later, wire its `channel_status`
online/offline events and flip `drives_sessions` to `true` - a pure adapter
change, no migration and no schema change.

## Retention

There is **no** retention sweep on the stream-history tables (`channel_history`,
`channel_history_streams`, `channel_history_stats`). Only chat *messages* are
pruned, by the `chat_retention` worker (gated on the `chat_retention` toggle).
Stream history is durable product value and is retained indefinitely - this is a
deliberate decision, not an oversight: the aggregates and viewer curves are the
whole point of the feature, and the future public stats surface assumes an
open-ended history of (opt-in) sessions. If a history retention policy is ever
introduced it must be an explicit, separately-gated decision.

---

## Developer Guide / Stream History: storage, rollups & retention

Source: https://docs.lumio.vision/developer-guide/stream-history-storage

# Stream History: storage, rollups & retention

Stream History stores each stream in **three layers** in TimescaleDB. Knowing
which layer answers which read - and how long each layer lives - is the
difference between a query that scans a year of raw samples and one that reads a
pre-computed series. This page is the map (ZAF-681, the product side of the
ZAF-672 observability decision).

For rules that govern new TimescaleDB tables, aggregates, compression, and
retention, see the [data design standard](./data-design.md).

## The three layers

### Shared Chat session data

The TimescaleDB migration `20261023200000_shared_chat_session_history` adds
four nullable columns without an index or data rewrite:

| Column | Purpose |
|--------|---------|
| `channel_history.shared_chat_at` | First session moment with Shared Chat; supports the With/Without filter, including a live session. |
| `channel_history.partner_messages` | Marker and count for separating old frozen own-channel chat totals from partner messages. |
| `channel_history_streams.shared_chat_timeline` | Event-exact start/end, host and per-channel participation spans; frozen with `shared_chat_sources` at finalization. |
| `channel_history_streams.shared_chat_insights` | Frozen partner chat figures and keyword/link/command lists. |

While a stream is live, `services/history/shared_chat_timeline.rs` derives the
timeline from the four `twitch:shared_chat_*` rows in `platform_event_logs`.
The finalizer freezes it in the same update as `shared_chat_sources`, before
event retention can remove those rows. A channel that leaves and rejoins has
two spans. For older streams without transition events, the sample buckets
give approximate boundaries (± one minute). The boot backfill of partner
messages skips crawled and erased sessions. It checks retention for every
candidate before it writes anything: a stream whose chat log is pruned
(fewer rows than its stored totals, an empty log included) is left untouched,
so both markers — `partner_messages` and `bot_messages` — stay NULL. It keeps
its older mixed total and is marked as including partner chat.

`db::channel_history::OWN_CHANNEL_SQL` is the shared predicate for every
**My channel** message count, including retained-data checks and backfills.
Partner messages do not enter own totals. **Whole session** uses partner
counts and insights frozen at finalization. Partner keyword, link and command
lists retain only the term and count: no viewer identities, poster lists or
occurrences, and therefore no partner-list viewer-erasure path. Own-channel
insights keep their existing poster details and erasure handling. Partner
Subs, Bits and gifts are display events, never revenue in either view.

| Data | Live read | Finalized read |
|------|-----------|----------------|
| Session transitions | Derived from stored `platform_event_logs` events | Frozen `shared_chat_timeline` |
| Partner viewers and messages | Newest 60-second sample plus server session state | Frozen per-channel aggregates and insights |
| Older streams without events | Minute-sample reconstruction | Minute-sample fallback; no invented event-exact boundaries |

| Layer | Table / view | Grain | Written by | Read for |
|-------|--------------|-------|------------|----------|
| **Summary** | `channel_history`, `channel_history_streams` | one row per session / per broadcast | the finalizer (`history_sampler.rs`) once a session closes; for crawled sessions the crawler itself | list previews, channel-page aggregates |
| **Raw samples** | `channel_history_stats` (hypertable) | one 60s sample per `(session, platform)` | the sampler, every 60s per open first-party session; the crawler's stats poller for crawled sessions | the **detail curve** of one stream |
| **Rollups** | `channel_history_stats_5m`, `channel_history_stats_1h` (continuous aggregates) | one bucket per `(5m or 1h, session, platform)` | TimescaleDB refresh policies | **long / cross-session ranges** |

### Running first-party history reads

For a first-party session that is not finalized and started within the last 48
hours, `service::list_sessions` and `service::build_report_from` overlay the
stored summary **in memory**. The finalizer remains the only writer of
`channel_history` and `channel_history_streams`. The list uses one batched
`live_overlay_samples` query for eligible sessions on its page; the report
folds the raw samples it already loaded. Per-minute viewer sums give running
peak and average viewers. The newest sample per platform gives cumulative
messages, followers, paid Subs, gifted Subs and the platform breakdown.
Duration runs from the session start. A session without samples marks these
values unavailable.

Unique chatters, per-platform chatters, bot-message count, emote and GIF counts
and top lists are derived from the retained chat log with the finalizer's
counting rules. That read has a three-second budget and a cache with a 60-second
soft age and 120-second expiry. Chatter suppression is applied after every
cache read. If the derivation or suppression check cannot finish, the affected
values are unavailable rather than a meaningful zero. Chat sampling uses a
30-second watermark for late messages, events and tips; a displayed chat
counter can therefore trail incoming chat by about 90 seconds in total.
YouTube subscriber gain is calculated after the stream from the subscriber
count at its start and end.

The overlay is shared by GraphQL and REST list and report reads, dashboard
`latestSession`, and authorized report share links. It does not affect the
summary email, report and list exports, milestone calculations, overview KPI
totals or public Stats reads: those use stored finalized values. An open
session older than 48 hours also keeps its stored values because its sample
counters may no longer be reliable.

Crawled sessions (nil-UUID account, `source = 'external_crawler'`) share these
tables but not the first-party workers. The API's sampler, grace close, startup
orphan recovery and finalizer all skip the nil-UUID account; the crawler opens,
samples, closes and freezes those sessions itself (see
[the crawler's session lifecycle](./public-stats-crawler.md#session-lifecycle)).
Before that split the sampler overwrote crawler samples with empty ones and every
API deploy ended the crawled streams that were live.

### Boot backfills

At startup, before the platform workers start, the API runs a set of one-shot,
idempotent backfills over finalized `channel_history` rows
(`services::history::backfill`): `backfill_monetization_split`,
`backfill_revenue_counters` (gift tiers, ad-break list),
`backfill_currency_amounts`, `backfill_member_levels` and
`backfill_bot_messages`. Each one re-derives a figure from the retained event
or chat log and only picks rows that still lack it.

All of them skip crawled sessions (`account_id = CRAWLER_ACCOUNT_ID`, the nil
UUID; one constant in `db::channel_history`). The crawler stores no event or
chat log for its sessions and freezes `total_messages` from its IRC aggregates,
so a crawled row could never be re-derived. Without the filter it would stay a
`backfill_bot_messages` candidate (counted as `not_retained`) on every boot,
and the boot would grow with every crawled session. The `scanned` figure in the
backfill log lines counts first-party sessions only.

### Raw samples - the detail curve

`channel_history_stats` is the raw time series: `viewer_count` plus the
cumulative counters (`messages_total`, `followers_total`, `subs_total`,
`donations_total_cents`) and per-platform `platform_metrics`, sampled every 60s
while a session is live. For **one** stream's page this is exactly the right
resolution, so the detail readers stay on it:

- `db::public_stats_read::list_stream_viewer_curve` - the public stream-page
  viewer curve for a single `(session, platform)`.
- `db::channel_history_reports::list_stats` - the report charts for a session.
- `db::channel_history::{session_peak_avg_viewers, stream_peak_avg_viewers, …}` - per-session finalizer aggregates.

None of these span beyond a session, so none were changed.

### List sparklines

`viewer_sparkline` on `GET /v1/history?include=sparkline` (or GraphQL `channelHistory.sessions.viewerSparkline`) produces at most 32 combined-viewer points for each visible session in one page query. Each session reads exactly one tier, in this order: raw samples while they exist; after they age out (90 days), `channel_history_stats_5m`; after that ages out too (12 months), `channel_history_stats_1h`. The rollup tiers sum the per-platform bucket peak across platforms. All three tiers are in the same single page query (`db::channel_history_reports::viewer_sparklines`). Live sessions bucket through the current time. With no samples or rollup points the field is `null`.

The dashboard's per-platform viewer series of the latest session (`db::channel_history_reports::viewer_series`, GraphQL `latestSession.viewerSeries`) uses the same three tiers, without summing platforms.

### Rollups - the pre-computed series for long ranges

The ZAF-594 public Stats app spans a **year** across thousands of channels, and
the ZAF-595 crawler adds tens of thousands of foreign channels
(`source = 'external_crawler'`). Scanning raw 60s samples over those ranges is
exactly the pattern we avoid on the Prometheus side with recording rules
(ZAF-675 §4). So two [continuous aggregates](https://docs.timescale.com/use-timescale/latest/continuous-aggregates/)
roll the raw samples up:

- **`channel_history_stats_5m`** - 5-minute buckets, refreshed every 15 min
  (leaving the last 10 min to the raw detail curve). Multi-day / multi-week reads.
  Dropped after **12 months** (see [Retention](#retention)).
- **`channel_history_stats_1h`** - 1-hour buckets, refreshed hourly. Month /
  quarter / year reads. Kept, and built from the raw table (not from `_5m`), so
  the `_5m` drop does not affect it.

Each bucket keeps `viewer_sum` + `viewer_samples` (so a read that re-aggregates
across sessions gets an **exact** sample-weighted average, not an average of
averages), `peak_viewers` / `min_viewers`, and the `max()` of each cumulative
counter (== the value at the last sample of the bucket). Both are
`materialized_only` - a read only ever touches pre-computed buckets, never the
raw table.

For the dashboard's latest-session chart, `viewer_series` keeps each platform's
maximum viewer count in up to 60 equal session-span buckets. `viewer_total`
uses the same bucket times and only the selected platforms. While raw samples
exist, it sums viewer counts from the **same minute** across those platforms,
then keeps the highest concurrent sum in each bucket. Adding the separate
`viewer_series` maxima would overstate the audience when the platforms peaked
at different minutes. The total has no point for a bucket without samples.
After raw samples expire, the 5-minute and then 1-hour rollups supply the curve
by summing their stored per-platform peaks at each rollup time; those older
total points are an approximation because the original minute-level alignment
is no longer available.

The cross-session read primitive is
`db::public_stats_read::list_account_viewer_curve(account_id, platform, from, to, resolution)`.
It picks the 5m or 1h aggregate and returns a downsampled curve. A 5m request
whose `from` lies before the 5m retention window (12 months) reads the 1h
aggregate for the whole range (`effective_resolution`), so it never returns a
silently partial 5-minute curve. A gated test
(`apps/api/tests/tsdb_channel_history_aggregates.rs`, run under
`RUN_TSDB_MIGRATION_TEST`) proves a long range returns downsampled buckets whose
plan scans the aggregate's materialization hypertable - not raw
`channel_history_stats`.

In an agent run, use the injected TimescaleDB test URL for that suite:
`DATABASE_URL="$TEST_TSDB_DATABASE_URL" RUN_TSDB_MIGRATION_TEST=1 cargo test -p lumio-api --test tsdb_channel_history_aggregates`.

## Migrations

The aggregates ship in `apps/api/tsdb_migrations/20260823000010_channel_history_continuous_aggregates.{up,down}.sql`.
Creating (and dropping) a continuous aggregate **cannot run inside a
transaction**, so the migration opts out of sqlx's transaction wrapper with a
`-- no-transaction` first line (sqlx 0.9). The `.down.sql` drops both views,
which also removes their refresh-policy jobs.

## Chunks, compression and sample ids

- **Raw samples:** `channel_history_stats` uses **1-day chunks** and compresses
  a chunk 7 days after its range ends (`segmentby session_id`). With the old
  7-day default one chunk held ~83 GB at 30 000 live crawled channels. Chunks
  written before `20261012100000` keep their 7-day size until retention drops
  them.
- **Rollups:** `channel_history_stats_5m` compresses after 7 days and
  `channel_history_stats_1h` after 30 days - never inside their refresh window
  (`start_offset` 2 days / 30 days). Both segment by `session_id` and order by
  `bucket`.
- **Sample ids:** `id` defaults to `uuidv7()` (PostgreSQL 18), so inserts into
  the `(id, time)` primary-key index are time-ordered. Both writers (API sampler,
  crawler) leave `id` to the default.
- **Account index:** `idx_channel_history_stats_account_first_party
  (account_id, time DESC)` is partial and skips crawler samples (nil
  `account_id`). A query that looks samples up by account must repeat
  `account_id <> '00000000-0000-0000-0000-000000000000'::uuid` literally (as
  `latest_sample_for` does), otherwise a generic plan cannot use the index.

`apps/api/tests/tsdb_chunk_intervals_compression.rs` (gated by
`RUN_TSDB_MIGRATION_TEST`) pins all four.

## Deletion

Deleting a report (`deleteChannelHistory` / `DELETE /v1/history/reports/{id}`,
`db::channel_history_reports::delete_session`) and deleting a channel's whole
history on dissolution or operator delete
(`db::channel_history::delete_all_account_history`) remove the rows of all
three layers: the session, its streams, raw samples and milestones, **and** the
matching rows of `channel_history_stats_5m` and `_1h`. The crawler's opt-out
erasure (`apps/crawler-twitch/src/optout/erase.rs`) does the same for the
crawled sessions of an opted-out channel. Each path is one transaction, so a
failure deletes nothing.

Deleting the raw rows alone would leave the rollup rows in place: the refresh
policies only recompute their recent window (`_5m` 2 days, `_1h` 30 days), and
`_1h` has no retention. So `lo_database::viewer_curve::delete_viewer_curve_rows`
(re-exported as `db::channel_history::delete_viewer_curve_rows`; the crawler
cannot call `apps/api`) deletes them where they are stored, in the aggregates'
materialisation hypertables (by `account_id` for a channel, by
`session_id = ANY(…)` + `account_id` for one report or the sessions of an
opted-out crawled channel). The hypertable names are read at run time from
`timescaledb_information.continuous_aggregates`; a missing aggregate is an
error, never a skipped delete. The transaction lifts
`timescaledb.max_tuples_decompressed_per_dml_transaction`, because the rows sit
in compressed chunks and a large channel exceeds the default cap of 100,000
decompressed tuples. Bloom pruning on `account_id` / the `session_id` index
keep the delete to the affected batches (about 1 ms, ZAF-2661).

Sessions deleted before this path existed left their rollup rows behind. The
one-off TimescaleDB migration `20261022100000_viewer_curve_orphan_cleanup`
removes them: it collects the `session_id`s of both rollups that have no
`channel_history` row (buckets of the last day excluded, they go with the next
refresh), then deletes them from the materialisation hypertables with
`session_id = ANY(…)`, the batch-pruned path on the `session_id`-segmented
compressed chunks. It never refreshes, compresses or drops, fails on a missing
aggregate, writes the counts to the migration log and deletes nothing on a
second run.

**Never call `refresh_continuous_aggregate` on `channel_history_stats_5m`/`_1h`
over a range older than 90 days, neither in a migration nor by hand; raw
samples are gone there and the refresh erases every channel's buckets.** A
raw-row delete logs invalidations for its range, and the policies leave those
older than their own window in the log, so a manual refresh of an old range
would act on them.

The tests: `tsdb_viewer_curve_erasure.rs` (materialised and compressed rows of
both rollups, account and session delete, a foreign session, no return after a
refresh) and `tsdb_crawler_optout_curve_erasure.rs` (the crawler's real opt-out
transaction on sessions older than both refresh windows; another channel's rows
stay) under `RUN_TSDB_MIGRATION_TEST`.

## Retention

Two very different retention questions live here, and they are answered
differently.

- **1-hour rollup: kept, no retention drop.** The published privacy policy
  (`apps/web/content/{en,de}/legal/privacy.mdx`, §"Stream history (broadcast
  statistics)") keeps the **viewer-count curve for as long as the channel
  exists**. `channel_history_stats_1h` **is** that long-lived pre-computed
  curve, so it carries **no** retention policy. Its rows go only with a deleted
  report or a deleted channel (see [Deletion](#deletion)).

- **5-minute rollup: dropped after 12 months.** Continuous aggregates are not
  compressed, and at crawl scale `channel_history_stats_5m` grows by ~570 GB a
  year (ZAF-2180 capacity model). Migration `20261012110000` adds
  `add_retention_policy('channel_history_stats_5m', drop_after => INTERVAL '12 months')`.
  Legal decided the window on **ZAF-2189** (founder-accepted), on the condition
  that the `_1h` read fallback ships with it (see [List sparklines](#list-sparklines)
  and `list_account_viewer_curve` above). Stream history older than 12 months
  therefore reads at 1-hour resolution. The policy is safe on the aggregate: its
  refresh policy only recomputes the last 2 days, so a refresh never
  re-materialises a dropped range. It is table-wide (`_5m` has no `source`
  column), so first-party and `external_crawler` buckets share the window.
  `_5m` materialises forward from 2026-08-23 (`WITH NO DATA`), so the first
  drop is around 2027-08-23.

- **Raw 60s samples: dropped after 90 days.** The raw hypertable carries a
  TimescaleDB retention policy - `add_retention_policy('channel_history_stats',
  INTERVAL '90 days')`, migration `20260824000001` - that drops each chunk once
  its whole time range is older than 90 days. This is lawful precisely because
  the rollups above preserve the promised **viewer-count curve**: `max`
  (peaks survive), `min`, an exact sample-weighted average
  (`SUM(viewer_sum)/SUM(viewer_samples)`), and the cumulative counters
  (`max()` of the monotonic-in-session totals). Dropping the 60s cadence - which
  the privacy policy never published - therefore loses no promised information
  and is Art. 5(1)(c)/(e) DSGVO data-minimisation-positive. Legal & Compliance
  signed off on the 90-day window on **ZAF-689** (founder-approved 2026-08-24),
  the same align-with-Legal-**before**-you-set-a-window gate ZAF-648/653 applied
  to the GDPR-bound hypertables (`audit_events`, `platform_event_logs`). The
  policy is table-wide, so it covers first-party **and**
  `source = 'external_crawler'` (ZAF-595) rows identically - both are
  de-identified aggregate reach data under the same window. Raw samples are
  still compressed after 7 days (independent compression policy); retention then
  drops the chunk outright once it ages past 90 days.

The 1-hour rollup is the long-lived preserved curve; the 5-minute rollup is
the 12-month working resolution; the raw samples are the short-lived (90-day)
detail curve. Both migrations are reversible with no public
surface, and the one-way-door raw-retention window was set only **after** Legal
signed off - the same decouple-the-reversible-migration-from-the-approval-gate
discipline the audit and telemetry retention work used. The retention migration
is numbered after the rollup migration (`20260823000010`), so the preserving
aggregate is always materialising before any raw chunk can age out.

The tests: `tsdb_channel_history_retention.rs` (raw, 90 days) and
`tsdb_channel_history_rollup_retention.rs` (`_5m` drops an aged bucket, `_1h`
has no policy and keeps the hour) under `RUN_TSDB_MIGRATION_TEST`; the
raw → 5m → 1h read fallback in `history_overview.rs`.

---

## Developer Guide / Bot Modules

Source: https://docs.lumio.vision/developer-guide/bot-modules

# Bot Modules

Bot modules are extensions that handle chat messages, platform events, and timed actions. All bot modules -- built-in and community -- run as handler-based server functions inside V8 isolate sandboxes via the Bot Module Worker.

> **One execution model:**
> There is no native Rust `BotModule` trait or module registry crate. The built-in modules -- Link Protection, Spam Protection, Word Filter, Timed Messages -- live in `extensions/system/` and run through the same V8 execution model as third-party bot modules. See [Extensions](../features/extensions.md) for the full list.

## Architecture

```
Chat message
  │
  Platform bot (twitch / youtube / kick / discord)
    ├─ Holds the account's compiled trigger set in memory
    ├─ Matches the message against commands / keywords / regex patterns
    ├─ command match  → min_role + cooldown gate → sync HTTP POST /v1/execute
    │                    on the Worker (500 ms deadline); the bot posts the reply,
    │                    then the handler's actions
    ├─ keyword/pattern → Redis publish to lumio:botmod:msg:{platform}:{account_id}
    └─ has_moderate install (twitch / kick / youtube only) → spawned
       POST /v1/execute type "moderate" (hard 500 ms, fail-open); the bot posts
       the decision's actions

Stream event  → API publishes lumio:events:{account_id}
Timer slot    → Worker's own TimerEngine
  │
  Bot Module Worker
    ├─ /v1/execute (commands, moderation), the chat-trigger listener
    │  (keyword/pattern), the event-trigger listener and the timer scheduler
    │  all run through MessageRouter
    └─ Executes the handler in a V8 isolate
         ├─ Handler receives ctx (auth, config, user, db, cache, secrets, fetch, defer)
         ├─ Returns { reply?, actions[] }
         ├─ Command reply → HTTP response to the bot;
         │  keyword/pattern/event/timer reply → lumio:bot:action:{platform}:{account_id}
         └─ actions[] → POST /v1/internal/bot-modules/{install_id}/actions on the API
            (after the reply, at most once) → shared extension action dispatcher
```

## Bot Module Worker

The Bot Module Worker (`apps/bot-module-worker/`, library in `crates/lo-bot-module-worker/`) is a standalone Actix Web service on port 8090. **The Worker does no chat trigger matching** -- the bots own the chat trigger set and the matching; the Worker runs the handler it is told to run, over HTTP for commands and moderation and over Redis for keyword/pattern triggers. Stream events and timers do not pass through the bots: the Worker matches events against its install registry and schedules timers itself.

**Chat-trigger listener** (`crates/lo-bot-module-worker/src/chat_triggers.rs`, ZAF-1913). With a `[redis]` section the Worker `psubscribe`s `lumio:botmod:msg:*` and runs each `AsyncTriggerMessage` through `MessageRouter::handle_chat_trigger`:

- Only `keyword` and `pattern` triggers are accepted; the install must belong to the account in the channel name (a message naming another account's install is refused like an unknown install).
- A handler that is also a command keeps its `min_role`: the router re-checks it against `command_min_roles` on this path as on `/v1/execute`, so a keyword message cannot run a command handler below its role. Keyword and pattern handlers themselves have no minimum.
- Every Worker replica receives every publish, so a message is claimed first (`SET NX` on `lumio:botmod:msg_claim:{install}:{type}:{handler}:{message_id}`, 120 s); only the claiming replica runs it. A message without a platform message id is skipped.
- At most `chat_triggers.max_in_flight` (default 32) handlers run at once; a message arriving while all slots are busy is dropped with a warning. Each run has the router's 10 s deadline.
- A non-empty `reply` goes back to the chat it came from on `lumio:bot:action:{platform}:{account_id}`: `chat_message` for Twitch, Kick and YouTube; `post_message` with the originating text channel for Discord (the Discord bot checks the channel belongs to the account's guild). Handler `actions` are posted to the API after the reply (see [Handler actions](#handler-actions)).

Configuration: [Installation → Bot Module Worker chat triggers](../getting-started/installation.md#bot-module-worker-chat-triggers).

**Event-trigger listener** (`crates/lo-bot-module-worker/src/event_triggers.rs`, ZAF-2398). With a `[redis]` section and `[event_triggers] enabled` (default `true`) the Worker `psubscribe`s `lumio:events:*`, the channel the API publishes every stream event on (the same one the WebSocket server forwards to widgets):

- The account is taken from the channel name, never from the payload; a payload whose `account_id` names another account is dropped. Only payloads with an `id` and a `type` are events - other shapes on the channel are ignored.
- Matching is an in-memory lookup of the installs whose `events` (manifest `triggers.events`) contain the event type; an event no install subscribes to costs no Redis round-trip. Disabled and killed installs are skipped.
- Each `(install, event)` pair is claimed with `SET NX` on `lumio:botmod:evt_claim:{install_id}:{event_id}` (120 s), so one replica runs it.
- At most `[event_triggers] max_in_flight` (default 32) handlers run at once; a delivery beyond that is dropped with a warning.
- The `event()` handler receives the event payload unchanged. A reply goes to `lumio:bot:action:{platform}:{account_id}` for the event's platform (Twitch, Kick, YouTube); Discord events carry no channel, so their replies are dropped. Actions follow the reply.

**Timer scheduler** (`crates/lo-bot-module-worker/src/timer.rs`, `timer_scheduler.rs`, ZAF-2398). With `[redis]`, `[sync]` and `[timers] enabled` (default `true`) the Worker runs every timer of the handler feed's `timers` list:

- Every replica schedules every timer. A timer fires at the slot boundaries of a deterministic per-`(install, timer)` phase (`timer_phase`, SHA-256 of install id + timer name, modulo the interval), so all replicas aim at the same slot and firings spread across the interval.
- Each firing claims `lumio:botmod:timer_claim:{install_id}:{timer}:{slot}` with `SET NX` (TTL = interval), so exactly one replica runs it; there is no leader to fail over. Timer names that are not `[A-Za-z0-9_-]{1,64}` are hashed in the key.
- At most once per slot; a missed slot is skipped, not caught up. At most `[timers] max_in_flight` (default 32) timer handlers run at once; a firing beyond that is skipped.
- The engine is reconciled on every registry change (snapshot poll, trigger-sync refresh, kill switch): new timers start, removed, disabled and killed installs stop, and a changed interval restarts the timer. A bundle update needs no restart - each firing reads the current bundle.
- A reply goes to every chat platform of the install except Discord.
- **`onlyWhenLive`.** An install whose `install_config` has `onlyWhenLive: true` (the Timed Messages system module) runs only while at least one of its chat platforms is live per the API's channel-status cache `lumio:channel_status:{account_id}:{platform}` (`is_online: true`), and replies only on the live platforms. The cache is read only for such installs, once per firing.

**Live registry updates** (`crates/lo-bot-module-worker/src/registry_sync.rs`). Because events and timers bypass the bots, the Worker follows the same channels the bots do: `lumio:botmod:trigger_sync:{account_id}` refetches that account from the handler feed (`?account_id=`) and replaces its installs; `lumio:botmod:kill:{account_id}` sets or clears the kill flag on the account's installs at once. The Worker enforces `enabled` and the kill switch itself on every path. A lost publish is covered by the full snapshot poll.

### Viewer input (chat commands and channel point rewards)

Viewers reach an extension only through chat commands and channel point rewards (Twitch and Kick). Lumio has no viewer page and no viewer identity; the manifest targets are `editor` and `layer`, and the manifest validator rejects `interactive`.

- **Chat command** (`!vote 2`): the platform bot matches the command trigger, enforces `min_role` and the cooldowns, and calls the Worker's `/v1/execute`, which runs the extension's `command("vote", async (ctx, args) => …)` handler (`args = ["2"]`, `ctx.user` = the sender).
- **Channel point reward**: the API publishes the redemption as `twitch:reward` / `kick:reward` on `lumio:events:{account_id}`; the event-trigger listener runs the `event("twitch:reward", …)` / `event("kick:reward", …)` handlers of every install that lists the type in manifest `triggers.events`. The account comes from the channel, never the payload; each `(install, event)` runs once (`SET NX` claim); per install at most 50 event and timer runs per minute (`RateLimitCategory::EventHandler`); at most 32 event handlers in flight per Worker. The handler gets the stored event row: for `twitch:reward`, `raw` is the EventSub redemption (`user_name`, `user_input`, `reward { id, title, cost, prompt }`); for `kick:reward`, `raw` carries `user_id`, `user_login`, `user_name`, `status`, `user_input` and `reward { id, title, cost, prompt }`.
- **Result to the surfaces**: both handlers write `ctx.db` (`await ctx.db.insert("votes", { option })`) and call `ctx.realtime.push("poll:votes", { option })` (topic `^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$`, payload ≤ 16 KiB, ≤ 32 pushes per run, ≤ 300 pushes and ≤ 1 MiB of published messages per install and minute; a handler that throws publishes nothing). After a successful run the Worker publishes the pushes, the API relays them to the WebSocket channel `extension_install:{install_id}`, and the editor panel and the layer overlay receive them with the SDK hook `useRealtime("poll:votes", cb)`.

`crates/lo-bot-module-worker/src/viewer_input_tests.rs` covers the chat vote and both reward events end to end. Developer-facing guide: [Viewer Input](https://developers.lumio.vision/guides/viewer-input).

### Handler actions

A handler result's `actions` (`[{ action, params }]`) are never executed by the Worker or the bots. They are posted to the API's internal endpoint `POST /v1/internal/bot-modules/{install_id}/actions` (`crates/lo-bot-module-worker/src/actions.rs`, System key with `bots:internal`, base URL and key from `[sync] api_base_url` / `system_key`; without them actions are dropped with a warning):

- **After the reply**, on a spawned task, so the handler budget is unchanged. The bots post command and moderate actions; the Worker posts keyword, pattern, event and timer actions.
- **At most once** - no retry on a timeout or `5xx`, because a retried `chat:ban` is not idempotent at the platform.
- The API (`apps/api/src/services/bot_module_actions.rs`) takes the account from the install row, never from the request, and answers `404` unless the install is a live, enabled bot module of a non-suspended extension whose channel is not in its dissolution grace period and whose account kill switch is off.
- Each action runs through the **same** dispatcher and manifest-permission gate as widget and app actions (`services::extension_actions`): declared permission, plan feature (`chat:*` → `feature:multichat`, `obs:*` → `feature:obs_remote`, `spotify:*` → `feature:music`), params validation. A refusal before dispatch returns `error_code: "denied"` with the widget path's message.
- **Rate cap:** `[extensions] bot_module_action_rate_per_minute` (default 120) actions per install and minute, counted in `lumio:botmod:act_rl:{install_id}:{epoch_minute}` (TTL 120 s). Over the cap → `rate_limited`; Redis unavailable → `rate_limit_unavailable` (fail-closed).
- **Install log:** every outcome is written to `extension_install_logs` (`info` / `warn`), at most one row per second and install per API process; after the cap is hit only the first refused action of the minute is logged. Rows carry the action name and, for `chat:*`, `platform` / `user_id` / `message_id` - never message text or other params.
- **Audit:** `chat:ban`, `chat:unban` and `chat:timeout` emit `account:extension_moderation` with `source: "bot_module"` (empty origin - a service-to-service call). A bot module's `chat:delete` is not audited (`extension_chat::is_audited`); it is recorded in the install log only.
- **Delete lookback:** after the platform deletes the message, a bot module's `chat:delete` flags it in Lumio's chat history and quotes its text in the moderation log only if it is at most **6 hours** old (`extension_chat::BOT_MODULE_DELETE_LOOKBACK_HOURS`). The lookup and the soft-delete (`lo_chat::get_message_text` / `soft_delete_platform_message`) filter on `platform` and that `created_at` bound, so each per-message delete plans against the newest chat chunks only, never the whole retention window (volume pin P17). An older message is deleted on the platform and logged without text, but stays unflagged in the history. Widget, app and dashboard deletes have no lookback.

Wire format and response: [REST API → internal bot-module actions](../api-reference/rest-api.md).

### Moderation (`defineModerate`)

The Twitch, Kick and YouTube bots run moderate handlers (`crates/lo-bot-module-worker/src/moderate.rs`, shared by the bots):

- For every chat message of an account with a `has_moderate` install on that platform, the bot spawns one `POST /v1/execute` (`type: "moderate"`, `function_name: "moderate"`) per install with a hard **500 ms** client timeout. A timeout, error or saturation lets the message through (fail-open); chat is never blocked.
- At most 16 moderate calls per account are in flight per bot process; a saturated account skips moderation for that message.
- Messages from the broadcaster and moderators are not moderated.
- The Discord bot does not call moderate handlers: no chat action supports Discord (the dispatcher's chat platforms are `twitch`, `kick`, `youtube`), so every decision would be refused.

The decision maps to actions, which the bot posts with `trigger_type: "moderate"`:

| Decision | Action |
|----------|--------|
| `allow` | none |
| `delete` | `chat:delete { platform, message_id }` |
| `timeout` | `chat:timeout { platform, user_id, duration_secs, reason? }` (`duration`, default 600) |
| `ban` | `chat:ban { platform, user_id, reason? }` |
| `warn` | `chat:send { platform, message }` (`message`, else `reason`; nothing if both are empty) |

The module's manifest must declare the matching permission for a decision to run. An `allow` writes no install-log row; a decision or an error writes at most one row per second and install, without message text.

**HTTP surface:**

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/v1/execute` | POST | `Authorization: SystemKey <key>` (constant-time compared) | Execute a `command` or `moderate` handler and return `{ reply, actions }` |
| `/v1/server-functions/execute` | POST | `Authorization: SystemKey <key>` (constant-time compared) | Run a handler server function (`query()` / `mutation()` / `action()`) for the API and return `{ data, realtime }` (ZAF-2542, ZAF-2543) |
| `/health` | GET | none | Health check |

`/v1/server-functions/execute` serves extensions of any category, not only bot modules: the API resolves and authorises the call, then sends the install, the definition's category, the caller's `args`, `ctx.auth` (`userId`, `role`), the install config and the published `server.js` of the version the install runs. The worker does not consult its `InstallRegistry` for it. It runs the export named `functionName` (it must be a `query()` / `mutation()` / `action()` definition of that category; no fallback to another export) as `handler(ctx, args)` with a 5 s / 256 MB isolate, `ctx.*` bound to the worker host and scoped to the install, deny-all egress and the per-install `Query` / `Mutation` / `Action` invocation limit. That limit fails closed for server functions: a configured Redis that does not answer refuses the call (`429 RATE_LIMITED`), while chat, event and timer handlers keep failing open. Every call also needs a slot of the server-function gate, `[server_functions] max_in_flight` (default 16) per replica and `max_in_flight_per_account` (default 4); a call that finds none is refused with `429 RATE_LIMITED` at once, never queued, so outside callers cannot crowd out the chat, event and timer handlers on the same worker. A JavaScript error returns only its first line (no stack trace); any other failure (the isolate host, the result, the bundle wrapper) returns the fixed message `Handler execution failed` and is logged on the worker, because its text can name internal paths; timeout and memory limit are reported from the watchdog and heap-limit flags, never from the error text. Answers: `200 { data, realtime }` (`realtime` = the handler's `ctx.realtime.push` calls, unpublished: the API validates and publishes them); `429 RATE_LIMITED`, `504 HANDLER_TIMEOUT`, `422 HANDLER_MEMORY_LIMIT` / `HANDLER_ERROR` as `{ code, message }`. The body limit of this route is 8 MiB. Server-function calls write no `extension_install_logs` / `extension_errors` rows.

The Worker refuses to start if `worker.system_key` is shorter than 16 characters -- an empty key would let an empty `SystemKey ` header through.

**Bot-side lifecycle:**

1. On connect, the bot fetches the account's trigger config from the API: `GET /v1/internal/bot-modules/{account_id}/triggers` (System key carrying `bots:internal`). The response is `{ installs: [...], killed: bool }`. `installs` lists only **enabled** installs of extensions that are not **suspended**; `killed` is the account's stored kill switch (`account_extension_kill_switch`, default `false`).
2. `compile_triggers()` pre-compiles the regex patterns into `AccountExtensionTriggers`, keyed by account in an in-memory store.
3. Every chat message is matched against that store in-process (no network hop).
4. A **command** match becomes a `SyncExecuteRequest` sent to the Worker's `POST /v1/execute` (URL and deadline from the bot's `[worker]` config -- `url`, `timeout_ms = 500`). The returned `reply` is sanitised and sent to chat, then the returned `actions` are posted to the API (`trigger_type: "command"`); the match is exclusive (the bot stops after it).
5. A **keyword** or **pattern** match becomes an `AsyncTriggerMessage` published to `lumio:botmod:msg:{platform}:{account_id}`, where the Worker's chat-trigger listener runs it. These matches are non-exclusive -- the bot keeps evaluating the remaining installs.

All four bots follow these steps. Command triggers pass the shared `lo_bot_commands::access::authorize` gate (`min_role`, then cooldowns) before the request is sent; a denied command is consumed silently. On Discord the prefix-message handler runs `extension_triggers::plan_dispatch` after dynamic commands; the sender's role comes from the guild (owner = `broadcaster`, a role with *Manage Messages* = `moderator`, everyone else `viewer`).

**Trigger refresh:** the bots `psubscribe` to `lumio:botmod:trigger_sync:*` and `lumio:botmod:kill:*`. A message on the trigger-sync channel makes the bot re-fetch and recompile that account's trigger set; the kill channel sets or clears the account's extension kill switch. Both only update in-memory state, so every running instance applies them before the leader filter (`leader.is_leader()`), which gates only the side-effecting `lumio:bot:action:*` messages.

**Kill switch on every reload path:** every path that loads an account's triggers - startup, a channel joined after startup (the Twitch/Kick channel poll, a YouTube channel's first chat session, a Discord `GuildCreate`) and a trigger sync - applies the feed's `killed` flag together with the triggers through the shared `lo_bot_module_worker::kill_switch::apply_trigger_config`. The flag is applied first and in both directions (`true` kills, `false` re-enables), so a reload never brings an account's triggers back while its switch is set.

The API publishes `lumio:botmod:trigger_sync:{account_id}` from `apps/api/src/services/bot_module_trigger_sync.rs` whenever the trigger feed's answer changes, on both protocols and for `bot_module` extensions only:

| Change | GraphQL | REST | Accounts reloaded |
|--------|---------|------|-------------------|
| Install | `installExtension` | `POST /v1/extension-installs` | the installing account |
| Uninstall | `uninstallExtension` | `DELETE /v1/extension-installs/{id}` | the uninstalling account |
| Per-install config (incl. `config.triggers` overrides) | `configureExtension` | `PATCH /v1/extension-installs/{id}` | the configuring account |
| Admin suspension | `suspendExtension` | `POST /v1/admin/extensions/{id}/suspend` | every account with the module installed |
| Default system extensions installed for a new account | `createAccount` | `POST /v1/accounts` (and Stripe checkout account creation) | the new account |

The publish is best-effort: a failure is logged and never fails the mutation, and a restarted bot reads the feed fresh. Turning extensions off for an account is the kill switch (`lumio:botmod:kill:*`), not a trigger sync. `pin_version` and `set_auto_update` change neither feed (both read `extension_installs.version_id`) and publish nothing. The Bot Module Worker follows the same channel to refresh its install registry.

**API-side trigger resolution** (`apps/api/src/routes/bot_module_extensions.rs`): the feed joins `extension_installs → extensions → extension_versions` for every `category = 'bot_module'` install and, per install, resolves the effective trigger set by layering optional per-install overrides from `extension_installs.config.triggers` over the version manifest's `triggers` (COALESCE: config wins field-by-field, manifest is the default). Commands, keyword substrings and regex patterns come from the manifest; `has_moderate` is set when the manifest declares `triggers.moderation = true` (the system moderation modules). The body is returned raw, without an `ApiResponse` envelope, because the bots deserialize it directly into `TriggerConfigResponse`. `killed` is read from `account_extension_kill_switch`, so a bot that restarts after the switch was set starts killed; the pub/sub channel carries live changes on top.

Each trigger carries a `handler` string, which is the `function_name` the bot sends to `/v1/execute`; the Worker looks it up in `InstallRegistry.handler_code`. The naming contract (the registry population must key `handler_code` identically) is: **command → command name, keyword → keyword text, pattern → regex source**, and a moderation handler is invoked with `type: "moderate"`.

**Registry population (handler-bundle feed).** The Worker's `InstallRegistry` is filled from a separate internal feed: `GET /v1/internal/bot-modules/handlers` (System key carrying `bots:internal`), resolved in `apps/api/src/routes/internal_extension_handlers.rs`. Where the trigger feed above delivers only trigger *metadata*, this feed delivers, per install, the executable handler bundle (the compiled `server.js` downloaded from storage) plus trusted context - `account_id`, `extension_id`, the installed `version`, `install_config`, `enabled`, `platforms`, `has_moderate`, the list of valid `handlers`, `events` (manifest `triggers.events`), `timers` (`[{ name, interval_secs }]`) and `killed` (the account's kill switch). `timers` covers the SDK form `triggers.timers[{ name, interval }]` (entries under 60 s or without a name are skipped) and the legacy `triggers.timer: true` form - one timer named `"timer"` whose interval is the install's `intervalSeconds` setting, clamped to 60..86400, default 300. The Automation Worker has the analogous `GET /v1/internal/automation-nodes/handlers` (which additionally carries `node_type`). Both accept optional `account_id` / `install_id` query params so the worker sync-loop can do a full initial load and then incremental refresh on install / uninstall / update. `handler_code` is `null` when the bundle cannot be resolved (missing file or storage unavailable); the install is still reported so the worker keeps full context. The Bot Module Worker requests the bot-module feed with `bundles=by_version`: each install then carries its `version_id` and `handler_code: null`, and every distinct bundle travels once in a top-level `bundles` map keyed by `version_id`. A version's bundle never changes, so N installs of one version cost one bundle in the body and one storage download.

**Worker sync-loop.** The worker actually pulls this feed at runtime (`crates/lo-{bot-module,automation}-worker/src/sync.rs`): on startup the `SyncClient` GETs the full cross-account snapshot and calls `InstallRegistry::load_snapshot`, then re-syncs the full snapshot every `poll_interval_secs`. The Bot Module Worker's re-sync is conditional: it sends the previous snapshot's `ETag` as `If-None-Match`, and the API answers `304 Not Modified` while no install's metadata has changed. It compares before it downloads any bundle, so an unchanged poll touches neither storage nor the registry. The API withholds the `ETag` while a bundle is unresolvable, so the next poll retries the download. A failed fetch is logged and the last-good registry is kept (fail-open), so a brief API outage never stops the worker. The loop runs only when the `[sync]` config section is fully set - `enabled` (default `true`), `api_base_url`, `system_key` (the Bearer key presented to the feed), and `poll_interval_secs` (Bot Module Worker default `300`, Automation Worker `30`). For the Bot Module Worker the poll is a safety net: with a `[redis]` section it applies `lumio:botmod:trigger_sync:*` and the kill switch live. Without `[redis]` the poll is the only refresh path and runs at most every 30 s. An unconfigured worker starts with an empty registry (every request short-circuits) rather than crashing. The bot-module conversion maps every advertised `handlers` name to the single shared `server.js` bundle (`InstalledBotModule.handler_code: HashMap<name, bundle>`); disabled installs and installs with an unresolvable bundle are kept so requests short-circuit cleanly.

### Redis Channels

Channel names are built by `crates/lo-cache/src/pubsub.rs`:

| Channel | Direction | Purpose |
|---------|-----------|---------|
| `lumio:botmod:msg:{platform}:{account_id}` | bots → Worker | Keyword/pattern trigger matches, run by the Worker's chat-trigger listener |
| `lumio:botmod:msg_claim:{install_id}:{type}:{handler}:{message_id}` | Worker (key) | Claims one message for one replica (`SET NX`, 120 s) |
| `lumio:bot:action:{platform}:{account_id}` | Worker → bots | Keyword/pattern/event/timer handler replies (`chat_message`; `post_message` on Discord for keyword/pattern) |
| `lumio:events:{account_id}` | API → Worker (and WebSocket) | Stream events, run by the Worker's event-trigger listener |
| `lumio:botmod:evt_claim:{install_id}:{event_id}` | Worker (key) | Claims one event for one install and replica (`SET NX`, 120 s) |
| `lumio:botmod:timer_claim:{install_id}:{timer}:{slot}` | Worker (key) | Claims one timer slot for one replica (`SET NX`, TTL = interval) |
| `lumio:channel_status:{account_id}:{platform}` | API (key), read by Worker | Live status for `onlyWhenLive` timers |
| `lumio:botmod:act_rl:{install_id}:{epoch_minute}` | API (key) | Per-install action rate counter (TTL 120 s) |
| `lumio:botmod:trigger_sync:{account_id}` | API → bots, Worker | Trigger set / install registry invalidation (install, uninstall, per-install config, admin suspension, new account) |
| `lumio:botmod:kill:{account_id}` | API → bots, Worker | Extension kill switch |
| `lumio:botmod:reload:{account_id}` | API → | Bot module reload |

### V8 Execution

Extension bot module handlers execute inside the same V8 isolate sandbox used by all extension server functions (`crates/lo-extensions-v8/`). The handler context (`ctx`) includes:

The `ctx` object is assembled in the wrapper (`build_module_wrapper` in `crates/lo-extensions-v8/src/module_executor.rs`). `auth`, `config` and `user` are inlined as plain JavaScript objects. `db`, `cache`, `secrets`, `fetch` and `defer` come from `globalThis.__lumio_host`, which `JS_HOST_PREAMBLE` (`crates/lo-extensions-v8/src/ops/bridge.rs`) installs **before** the sandbox hardening removes `Deno`. The preamble captures the single op `op_ext_call(kind, payload)`; the op validates the call, counts it against the per-run caps (`OpLimits`: 25 db / 50 cache / 10 secret / 10 fetch / 5 defer) and runs the embedder's `ExtensionHost` future on the embedder's Tokio runtime, bounded by the phase deadline. Errors come back as a JSON envelope that the preamble rethrows as `Error`. Without a host binding (server-function and automation paths today) the members fall back to inert stubs.

| Property | Description |
|----------|-------------|
| `ctx.auth` | Caller identity (userId, accountId) |
| `ctx.config` | Validated install config from `extension_installs.config` |
| `ctx.user` | Chat user who triggered the handler (`id`, `name`, `displayName`, `platform`, `role`, `isMod`, `isVip`, `isSub`) -- `null` outside chat contexts. `name` is the **login / @handle** and `displayName` is the **display name**; on Twitch the two differ for localized names (login `pocom_2026` vs display `こさむん`). Built-in template commands expose the same split as `{user_login}` / `{user}`, and the command→automation trigger publishes both as `user.login` / `user.name`. |
| `ctx.cache` | One Redis hash per install, `lumio:ext:cache:{install_id}` (`lo_cache::ext_cache`): ≤ 256 fields × 4 KiB, field TTL via `HEXPIRE` (default 1 h, max 24 h), Lua scripts for `set` / `increment`. Writes fail closed while Redis `used_memory` > 75 % of `maxmemory` (sampled every 10 s). `UNLINK` on uninstall (REST + GraphQL), and right after the commit for every install removed by an account delete (channel dissolution, admin delete) or a draft extension delete. Best-effort: a Redis failure is logged and the field TTLs bound the data |
| `ctx.fetch` | `ops::fetch::execute_fetch` with the manifest `egress` allow-list from the handler feed: HTTPS, global-unicast only (DNS pinned), no redirects, 5 s per request, 1 MiB (sync) / 10 MiB (async) body |
| `ctx.defer()` | Up to 5 jobs, run in the same isolate **after** the handler result went back to the router, under a shared 10 s budget (`DEFER_BUDGET`); only after a successful handler; not persisted |
| `ctx.db` | `lo_extensions_runtime::data::execute` on the extensions database (`[extensions.database]`, a DML login, 5 connections per replica): the install's account scope, enforced by row-level security as well as by the statement, typed binds, 200 ms (sync) / 2 s (async) statement timeout, per-install `Query` / `StorageWrite` limits shared with the API server functions (writes fail closed without Redis). Tables come from the version's `data_schema`, provisioned at approval. Without a URL it throws `ctx.db is unavailable` |
| `ctx.realtime` | `push(topic, payload)` collects messages in the isolate (topic 1-64 chars of `[A-Za-z0-9_.:-]`, payload ≤ 16 KiB, ≤ 32 per run; a bad push throws). After a successful run the executor hands them to `WorkerHost::publish_realtime`, which publishes them off the reply path on `lumio:extension_install:{install_id}` under the shared per-install caps of 300 pushes and 1 MiB of serialized `{ topic, payload }` messages per minute (`lo_extensions_runtime::realtime`, Redis keys `ext-fn:{install_id}:realtime` and `ext-fn:{install_id}:realtime-bytes`). One Lua call admits the longest prefix of the batch both caps still hold and raises both counters by exactly that (`INCRBY`), and the admitted pushes go out in one pipelined round trip. The byte cap protects the API's event relay, which reads every install's channel over one pub/sub connection that Redis would drop on an output-buffer overflow (`client-output-buffer-limit pubsub`); the API relays them to WebSocket `extension_install:{install_id}`. A failed run publishes nothing; without Redis the pushes are dropped |
| `ctx.secrets` | `get(key)` → the extension's owner-scope secret (`extension_secrets` row with `account_id IS NULL`) or `null`. The extension comes from the install registry, never from handler input; the installing account plays no part, so every install of an extension reads the same value. See *Secrets path* below |

**Secrets path.** The worker never holds the API's `auth.token_encryption_key`, the master key for every OAuth token, because it runs untrusted handler code. Instead `GET /v1/internal/bot-modules/extensions/{extension_id}/secrets` (system key with `bots:internal`, `Cache-Control: no-store`) decrypts each owner-scope value and **re-wraps** it under an independent key shared only by the API (`[extensions] bot_module_secrets_key`) and the worker (`[sync] secrets_key`): AES-256-GCM, format `w1.{nonce}.{ct}`, extension id + key name bound as associated data, so a wrapped value never opens under another extension or key name, and an at-rest `v1`/`v2` ciphertext never opens as a wrapped one. `lo_bot_module_worker::secrets::SecretsStore` caches the wrapped map per extension for **60 s** and unwraps one value per `ctx.secrets.get`; plaintext is never cached or logged. A fill is single-flight per extension: concurrent calls of one extension share one feed request, and a slow fill for one extension never delays another extension's reads. A call that has to wait for a fill gives up after 1 s (`SECRETS_FETCH_TIMEOUT`, the call is on the per-message path) and throws `ctx.secrets is unavailable`. Consequences: a changed or deleted secret reaches handlers within 60 s; a failed feed call or a key mismatch throws `ctx.secrets is unavailable` (nothing stale is served past the TTL); an empty `secrets_key` (or no `[sync] api_base_url` / `system_key`) turns `ctx.secrets` off with the same error. To rotate the wrap key, restart the API and every worker with the new value together; nothing is re-encrypted at rest. Crypto lives in `lo_extensions_v8::ops::secrets` (`wrap_secret` / `unwrap_secret`).

`WorkerHost` (`crates/lo-bot-module-worker/src/host.rs`) implements `ExtensionHost` and enforces the per-install per-minute `RateLimitCategory` limits in Redis (`ext-fn:{install_id}:{suffix}`): every command (60), keyword/pattern (100) and event (50) run, every cache op (200) and every deferred job (10). Moderate and timer runs are not limited. A Redis error admits a handler run (its per-run caps still bound it) but fails a cache op or deferred job closed. Without `[redis]` the worker runs an offline host: `ctx.cache` and `ctx.defer()` fail closed, `ctx.fetch` works.

The isolate defaults are 256 MB heap and a 10 s timeout (`IsolateConfig::default()` in `crates/lo-extensions-v8/src/isolate.rs`), with no filesystem access and no dynamic code evaluation. Bot module handlers run tighter: the executor is called with a **500 ms** timeout for sync command/moderate handlers, keeping the bot inside its own HTTP deadline.

**Bundle evaluation (`module_executor`).** The registry holds the real compiled `server.js` - an esbuild **ESM** module with `export default` / named exports and external `@zaflun/lumio-sdk` imports, not a bare `async (ctx, args) => …` expression. `crates/lo-extensions-v8/src/module_executor.rs` (`execute_bundle_handler`, or `execute_bundle_handler_with_host` with a host binding) evaluates it: it rewrites esbuild's regular output (hoisted imports + one trailing `export{…}`) onto the classic-script isolate path, binding the stripped SDK imports to an in-isolate shim of the pure `command` / `keyword` / `defineModerate` / `defineAutomationAction` / … tagging helpers, then selects the export the request targets (by `__trigger` for the low-level tagged handlers, by `__type` for the `define*` definitions, falling back to `default`) and invokes it with the calling convention its category expects. The shim adds no host authority - the isolate boundary is unchanged. The routers (`MessageRouter`, `NodeRouter`) call this via `execute_bot_module_bundle` / `execute_automation_node_bundle`; the older bare-expression `execute_*_handler` path is retained only for inline unit fixtures.

### Trigger Matching Flow

Matching happens in the bot (`apps/{platform}-bot/src/extension_triggers.rs`), not in the Worker:

```
1. Chat message arrives on the bot's platform connection
2. Bot iterates the account's installs, skipping installs whose
   `platforms` list excludes the current platform
3. match_triggers() checks, in this fixed order, and returns the FIRST hit:
   a. command  → message starts with the bot prefix and the first word
                 equals a command name or alias (case-insensitive)
   b. keyword  → lowercased message contains the keyword
   c. pattern  → compiled regex finds a match
4. Command  → access gate: sender role ≥ min_role, then the cooldown slots
              (lo_bot_commands::access, same as dynamic commands); denied →
              ignored silently, bot stops
              → sync POST /v1/execute; reply sent through the platform
              transport wrapper (sanitised there); bot stops
   Keyword  → Redis publish to the Worker; bot continues to the next install
   Pattern  → Redis publish to the Worker; bot continues to the next install
```

On Discord, steps 2-4 are `extension_triggers::plan_dispatch`, which returns the
sync requests and Redis publishes for `handlers/events.rs` to send.

Disabled triggers are skipped, and a pattern whose regex fails to compile is dropped at compile time with a warning rather than failing the install.

### Enforcement points

| Check | Where | On failure |
|-------|-------|-----------|
| `min_role` + cooldowns of a command trigger | bot, `extension_triggers::authorize_command` → `lo_bot_commands::access::authorize` (the gate dynamic commands use) | ignored silently; cooldown is armed only when the gate passes |
| `min_role` again | worker, `MessageRouter::handle_sync_request` (`command_min_roles` from the handler feed, resolved like the trigger feed) | empty response; a handler with no known `min_role` is refused |
| `min_role` of a command handler named by a keyword/pattern message | worker, `MessageRouter::handle_async_trigger` (same `command_min_roles` lookup) | nothing runs, nothing is sent |
| Keyword/pattern message bound to its channel | worker, `MessageRouter::handle_chat_trigger`: type is `keyword`/`pattern`, install belongs to the channel's account | refused, nothing is sent |
| Outbound text (reply, automation message, command response) | the platform transport wrapper: `lo-twitch-irc` send/reply, kick/youtube `send_*_message`, discord-bot `send.rs` → `lo_chat_outbound::sanitize` | control chars and line breaks become spaces (Discord keeps `\n`), leading `/` / `.` removed, capped at the platform maximum |
| Shared-connection throughput (Twitch) | `TwitchIrcClient` token bucket | a send that would wait more than 2 s is dropped with `RateLimited` |

The sender role is the bot's mapping of platform badges (`TriggerUser.role`); an
unknown role string counts as `everyone`, an unknown `min_role` as `broadcaster`.

### Key Files

| Path | Description |
|------|-------------|
| `apps/bot-module-worker/src/main.rs` | Worker binary: config load, system-key guard, HTTP server |
| `crates/lo-bot-module-worker/src/sync_handler.rs` | `POST /v1/execute` + `GET /health` handlers, constant-time key check |
| `crates/lo-bot-module-worker/src/router.rs` | `MessageRouter` -- sync and async dispatch into the executor |
| `crates/lo-bot-module-worker/src/chat_triggers.rs` | Chat-trigger listener: `lumio:botmod:msg:*` → router → reply on `lumio:bot:action:*` |
| `crates/lo-bot-module-worker/src/executor.rs` | `execute_bot_module_handler` -- V8 execution wrapper |
| `crates/lo-bot-module-worker/src/types.rs` | Wire types (`SyncExecuteRequest`, `AsyncTriggerMessage`, trigger configs) |
| `crates/lo-bot-module-worker/src/config.rs` | `InstallRegistry` -- in-memory installs and handler code |
| `crates/lo-bot-module-worker/src/sanitizer.rs` | Redacts UUIDs, mentions, tokens and IPv4 from developer-visible output |
| `crates/lo-bot-module-worker/src/event_triggers.rs` | Event-trigger listener: `lumio:events:*` → `event()` handlers |
| `crates/lo-bot-module-worker/src/timer.rs` | `TimerEngine` -- per-install interval timers, deterministic phase and slot |
| `crates/lo-bot-module-worker/src/timer_scheduler.rs` | Reconciles timers with the registry, slot claims, `onlyWhenLive` |
| `crates/lo-bot-module-worker/src/registry_sync.rs` | Live registry updates from `trigger_sync` and kill channels |
| `crates/lo-bot-module-worker/src/actions.rs` | Posts handler-result actions to the API (shared by Worker and bots) |
| `crates/lo-bot-module-worker/src/moderate.rs` | Moderate call (500 ms, fail-open, per-account cap) and decision → action mapping, used by the bots |
| `apps/api/src/services/bot_module_actions.rs` | Internal actions endpoint logic: runnable-install check, rate cap, install log |
| `crates/lo-extensions-v8/src/executor.rs` | Handler wrapper, `ctx` construction, `HandlerCategory` |
| `crates/lo-extensions-v8/src/isolate.rs` | Isolate limits and script execution |
| `apps/{platform}-bot/src/extension_triggers.rs` | Trigger compilation, matching and the `min_role`/cooldown gate on the bot side |
| `crates/lo-bot-commands/src/access.rs` | Shared access gate (`min_role`, cooldown slots) for dynamic commands and extension command triggers |
| `crates/lo-chat-outbound/` | Outbound sanitiser, token bucket and keyed cooldown shared by all bots |
| `apps/api/src/routes/internal_extension_handlers.rs` | Handler feed for the worker (incl. `command_min_roles`, `events`, `timers`, `killed`) and the internal actions endpoint |
| `apps/api/src/routes/bot_module_extensions.rs` | `GET /v1/internal/bot-modules/{account_id}/triggers` |
| `apps/api/src/services/bot_module_trigger_sync.rs` | Publishes `lumio:botmod:trigger_sync:{account_id}` on install, uninstall, configure, suspension and new-account default installs |
| `apps/api/src/routes/bot_modules.rs` | Built-in module config REST (`bot-modules:read` / `bot-modules:edit`) |

## Security Headers

The Extension Supervisor and Runtime apps serve HTTP security headers via `_headers` files (Cloudflare Pages, and Workers Static Assets for the per-extension Runtime hosts). Each app **generates** its `dist/_headers` at build time from the same origin lists it compiles into its bundle, so the CSP and the runtime `postMessage` allowlist always describe the same origins:

- **Supervisor** (`apps/extension-supervisor/tsup.config.ts`): `frame-src` restricts which origins can be iframed (the Runtime: each runtime origin template as a host wildcard such as `https://*.runtime.ext.lumio.vision`, plus the legacy shared Runtime origins during the rollout). `frame-ancestors` restricts who can embed the Supervisor (the webapp).
- **Runtime** (`apps/extension-runtime/tsup.config.ts`): `worker-src 'self'` allows only the Worker served from the page's own origin. `frame-ancestors` restricts embedding to Supervisor origins only. `connect-src` allows Sentry error reporting.

Because the lists are per-environment, a build only advertises the origins of the environment it is built for - the production build's `frame-ancestors` names only `supervisor.ext.lumio.vision`, the staging build only `lumio.supervisor.staging.zaflun.dev`.

### Origins

Every extension runs in its own Runtime origin, `<label>.<runtime host>`, where the label is the extension UUID as 32 lowercase hex characters (`@zaflun/lumio-protocol/origin`). Production uses `https://{label}.runtime.ext.lumio.vision`, prod preview and staging `https://{label}.lumio.ext.{prod,staging}.zaflun.dev`, local dev `http://{label}.localhost:3201`. The Supervisor loads an extension only from the origin bound to its `extensionId`, so the browser keeps the client-side state of two extensions apart. The full table, the legacy shared origins and the hosting setup are in [Extension Supervisor](./extension-supervisor.md#domain-setup).

When adding a new environment domain, update the origin and template defaults in both `tsup.config.ts` files (and the matching `ALLOWED_*_ORIGINS` / `EXTENSION_RUNTIME_ORIGIN_TEMPLATES` / `LEGACY_RUNTIME_ORIGINS` in `.github/workflows/deploy-extension-apps.yml`) alongside DNS, the CF Pages configuration and the route in `apps/extension-runtime/wrangler.jsonc`. There is no committed `_headers` file to edit.

## Config Validation

Extension config values are validated server-side against the extension's `config_schema` before writing to `extension_installs.config`. The validator is `validate_config_values()` in `crates/lo-extensions/src/config_validator.rs`.

Field types accepted in a `config_schema` (`VALID_CONFIG_TYPES`): `string`, `number`, `boolean`, `color`, `select`, `textarea`, `slider`, `font`, `icon`, `image`, `sound`, `multiselect`, `group`, `divider`, `info`, `channel`, `designer`, `presets`. A field may also carry `min` / `max` / `step`, `options`, `placeholder`, `rows`, `unit`, `collapsed`, nested `fields` (for `group`), and a `visible_when` condition.

The validator produces a `Vec<ConfigValidationError>` covering:

| Error | Condition |
|-------|-----------|
| `UnknownKey` | A submitted key is not in the schema |
| `RequiredFieldMissing` | A `required` field is absent or `null` |
| `TypeMismatch` | Value type does not match the declared field type |
| `InvalidSelectValue` | `select` value not in the declared `options` |
| `InvalidMultiselectValue` | A `multiselect` entry not in the declared `options` |
| `InvalidColorFormat` | `color` value is not `#RRGGBB` hex |
| `OutOfRange` | `slider` value outside `[min, max]` |

`group`, `divider` and `info` fields are presentational and carry no value check.

Both GraphQL (`configureExtension` mutation) and REST (`PATCH /v1/extension-installs/{id}`) call the same validator, so the two protocols reject identically. The stored config is passed to V8 handlers via `ctx.config`.

---

## Developer Guide / Automation

Source: https://docs.lumio.vision/developer-guide/automation

# Automation

Configure the automation engine and template variables.

## Overview

The automation engine allows you to create rules that trigger actions based on streaming events. Rules are evaluated in real-time and can execute chat commands, overlay updates, or API calls.

## Permissions

Automations use six dedicated permissions:

| Permission | Description |
|-----------|-------------|
| `automations:read` | View automations and their configuration |
| `automations:create` | Create new automations |
| `automations:edit` | Edit automation metadata, nodes, edges |
| `automations:delete` | Delete automations |
| `automations:execute` | Manually trigger and start/stop automations |

## Template Variables

The template engine supports 60+ variables across multiple categories. Variables are wrapped in `{{doubleCurlyBraces}}` and resolved at execution time.

For the full variable reference, see:
- **User guide**: [Automation Templates](../user-guide/automation-templates.md)
- **Developer guide**: [Automation Template Engine](./automation-templates.md)

### Quick Reference

| Category | Example | Permission |
|----------|---------|-----------|
| Channel | `{{channelName}}`, `{{platform}}` | None |
| Bot | `{{botName}}`, `{{commandPrefix}}` | None |
| Time | `{{date}}`, `{{time}}`, `{{timezone}}` | None |
| User | `{{username}}`, `{{displayName}}` | `chat:userinfo` |
| Stream | `{{streamTitle}}`, `{{category}}`, `{{viewerCount}}` | `events:read` |
| Events | `{{followerName}}`, `{{cheerAmount}}`, `{{subTier}}` | `events:read` |
| Spotify | `{{songName}}`, `{{songArtist}}`, `{{isPlaying}}` | `spotify:read` |

## Rule Configuration

Rules consist of:

1. **Trigger** -- The event type that activates the rule
2. **Conditions** -- Optional filters (minimum amount, specific platform, etc.)
3. **Actions** -- What to do when triggered (send message, update overlay, etc.)

## REST API

The automation CRUD surface lives under `/v1/automations`; the extension-node surface lives under `/v1/automation`. See the [REST API reference](../api-reference/rest-api.md) for full details.

| Method | Path | Permission |
|--------|------|-----------|
| `GET` | `/v1/automations` | `automations:read` |
| `POST` | `/v1/automations` | `automations:create` |
| `GET` | `/v1/automations/{id}` | `automations:read` |
| `PATCH` | `/v1/automations/{id}` | `automations:edit` |
| `DELETE` | `/v1/automations/{id}` | `automations:delete` |
| `PUT` | `/v1/automations/{id}/nodes` | `automations:edit` |
| `PUT` | `/v1/automations/{id}/edges` | `automations:edit` |
| `POST` | `/v1/automations/{id}/execute` | `automations:execute` |
| `GET` | `/v1/automation/extension-nodes` | `automations:read` + `feature:automation_node_extensions` |
| `GET` | `/v1/automation/webhooks/{install_id}/{automation_id}` | `automations:read` + `feature:automation_node_extensions` |
| `POST` | `/v1/automation/webhooks/{extension_id}/{install_id}` | `X-Webhook-Secret` header (no session auth) |

There is no `automations:history` permission: no execution-history surface exists, so the former account permission of that name was removed in ZAF-1094 (it gated nothing).

The GraphQL counterpart mirrors CRUD (`automations`, `automation`, `createAutomation`, `updateAutomation`, `deleteAutomation`, `saveAutomationNodes`, `saveAutomationEdges`, `executeAutomation`) plus `installedAutomationNodes` and `automationWebhookUrl`.

## Extension Node Integration

The automation engine supports extension-provided nodes alongside built-in nodes. Extension nodes use the `ext:{short_id}` prefix in `automation_nodes.node_type`.

### Dispatch flow

When the executor (`crates/lo-automation/src/executor.rs`) encounters a `node_type` starting with `ext:`:

1. Look up `extension_installs` by short_id
2. Load `automation_node_configs` for schemas and node type
3. For **action** nodes: call `dispatcher.execute_extension_node(ext_id, inst_id, "action", &node.config, &input)`, collect output
4. For **logic** nodes: call the same with `"logic"`, parse the branch, follow that output handle
5. For **trigger** nodes: skip (triggers are entry points, not walked during execution)

`Dispatcher::execute_extension_node` is a trait method. The API's implementation in `apps/api/src/dispatch.rs` (`RedisActionDispatcher`) issues a synchronous HTTP `POST` to the Automation Worker's `/execute/action` or `/execute/logic` (SystemKey auth), returning the handler `output` for action nodes and `{ "branch": … }` for logic nodes. It fails closed - an `AutomationError::DispatchError` - when the endpoint is unconfigured, when the worker reports a handler error, or on any transport/status error. The endpoint is configured under `[automation_worker]` (`url` + `system_key`, `LUMIO__AUTOMATION_WORKER__*`); an empty `system_key` disables extension-node dispatch. The Worker resolves the trusted install context (`account_id` / `extension_id` / `install_config`) from its own registry keyed by `install_id` and ignores those request-body fields.

### Automation Worker

The Automation Worker (`apps/automation-worker/`, library in `crates/lo-automation-worker/`) is a standalone Actix Web service on port 8091 (`AUTOMATION_WORKER__WORKER__PORT`) that executes extension node handlers in V8 isolates. Same architecture as the Bot Module Worker.

| Endpoint | Method | Timeout | Purpose |
|----------|--------|---------|---------|
| `/execute/action` | POST | 5 s (`ACTION_TIMEOUT_MS`) | Execute an action node handler |
| `/execute/logic` | POST | 2 s (`LOGIC_TIMEOUT_MS`) | Execute a logic node handler |
| `/execute/trigger/poll` | POST | 5 s (`TRIGGER_POLL_TIMEOUT_MS`) | Poll a trigger handler |
| `/webhooks/{extension_id}/{install_id}` | POST | 1 s (`TRIGGER_WEBHOOK_TIMEOUT_MS`) | Receive external webhook |
| `/health` | GET | -- | Health check |

The timeouts are constants in `crates/lo-automation-worker/src/router.rs`.

### Trigger registration

- **Webhook.** `automation_webhook_registrations` stores one `webhook_secret` per (install, automation). `automationWebhookUrl(installId, automationId)` - REST: `GET /v1/automation/webhooks/{install_id}/{automation_id}` - returns the registration's URL (`{public_url}/v1/automation/webhooks/{extension_id}/{install_id}`) and secret. Inbound webhooks hit `POST /v1/automation/webhooks/{extension_id}/{install_id}` and are authenticated by an `X-Webhook-Secret` header compared in constant time against the stored secret - no session auth. The upsert helper (`db::automation_nodes::upsert_webhook_registration`) has no caller yet, so registrations are not created automatically on enable.
- **Polling.** `poll_interval_seconds` is validated to the range **10–300** in three places that must stay in sync: the manifest validator (`crates/lo-extensions/src/manifest_validator.rs`), the config schema (`packages/extension-types/src/config.ts`, mirrored in `apps/web/src/app/api/schemas/lumio-config/route.ts`), and a `CHECK` constraint on `automation_node_configs`. `PollingEngine` in `crates/lo-automation-worker/src/polling.rs` is currently a stub: `start()` logs and returns without spawning any interval tasks.

### Database tables

| Table | Purpose |
|-------|---------|
| `automation_node_configs` | Extension node metadata (schemas, trigger mode, icon, color) |
| `automation_webhook_registrations` | Webhook URL registrations with secrets |

### Feature flag

`feature:automation_node_extensions` (category: `feature`) gates store installation and the Builder toolbar section. Free tier: disabled. Pro tier: enabled.

---

## Developer Guide / Automation Template Engine

Source: https://docs.lumio.vision/developer-guide/automation-templates

# Automation Template Engine

This guide documents the internals of the automation template engine in `crates/lo-automation/src/template.rs`.

## Architecture

The template engine resolves `{{variableName}}` placeholders in strings against a `TemplateContext`. Variables are organized into typed categories (structs), each optionally gated by a permission.

### Core Components

Public API:

- **`TemplateContext`** -- Holds all variable categories and the permissions of the executing user/account. `TemplateContext::to_json()` serialises the whole context for passing to extension handlers.
- **`parse(template, context)`** -- The main entry point. Replaces `{{variables}}` with values from the context.
- **`extract_variables(template)`** -- Returns all variable names found in a template string.
- **`required_permissions(template)`** -- Returns the set of permissions needed to fully resolve the template.

Crate-private helpers used by the above:

- **`resolve_variable(path, ctx)`** -- Dispatches dotted paths (`var.*`, `event.*`, `discord.*`) and delegates single-segment names.
- **`resolve_simple_variable(name, ctx)`** -- The single-segment lookup table.
- **`permission_for_variable(var)`** / **`permission_for_simple_variable(name)`** -- The permission lookup mirror of the two resolvers.
- **`has_perm(permissions, perm)`** -- The gating predicate.

## TemplateContext

```rust
pub struct TemplateContext {
    pub channel: Option<ChannelVars>,
    pub user: Option<UserVars>,
    pub stream: Option<StreamVars>,
    pub event: Option<EventVars>,
    pub sub: Option<SubVars>,
    pub tip: Option<TipVars>,
    pub spotify: Option<SpotifyVars>,
    pub channel_status: Option<ChannelStatusVars>,
    pub cheer: Option<CheerVars>,
    pub raid: Option<RaidVars>,
    pub redemption: Option<RedemptionVars>,
    pub hype_train: Option<HypeTrainVars>,
    pub poll: Option<PollVars>,
    pub prediction: Option<PredictionVars>,
    pub shopify: Option<ShopifyVars>,
    pub obs: Option<ObsVars>,
    pub discord: Option<DiscordVars>,
    pub bot: Option<BotVars>,
    pub time: Option<TimeVars>,
    pub custom: HashMap<String, String>,
    pub permissions: Vec<String>,
}
```

Each `Option<*Vars>` field is populated only when the relevant data is available. The `permissions` field holds the executing user's permissions -- an empty list means full access (owner/system context).

## Adding a New Variable

### 1. Define the variable struct

Add a new struct to `template.rs`:

```rust
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct MyNewVars {
    pub field_one: Option<String>,
    pub field_two: Option<String>,
}
```

### 2. Add the field to TemplateContext

```rust
pub struct TemplateContext {
    // ... existing fields ...
    pub my_new: Option<MyNewVars>,
}
```

### 3. Add resolution in `resolve_simple_variable`

Map camelCase template variable names to struct fields:

```rust
fn resolve_simple_variable(name: &str, ctx: &TemplateContext) -> Option<String> {
    match name {
        // ... existing matches ...

        // MyNew (requires my:permission)
        "fieldOne" if has_perm(&ctx.permissions, "my:permission") => {
            ctx.my_new.as_ref()?.field_one.clone()
        }
        "fieldTwo" if has_perm(&ctx.permissions, "my:permission") => {
            ctx.my_new.as_ref()?.field_two.clone()
        }

        _ => None,
    }
}
```

### 4. Add permission mapping in `permission_for_simple_variable`

```rust
fn permission_for_simple_variable(name: &str) -> Option<&'static str> {
    match name {
        // ... existing matches ...

        // MyNew
        "fieldOne" | "fieldTwo" => Some("my:permission"),

        _ => None,
    }
}
```

### 5. Add dotted path support (if needed)

For variables accessed via `{{myNew.fieldOne}}`, add a match arm in `resolve_variable`:

```rust
["myNew", "fieldOne"] if has_perm(&ctx.permissions, "my:permission") => {
    ctx.my_new.as_ref()?.field_one.clone()
}
```

## Permission Gating

Every variable can be optionally gated by a permission string. The gating works through two mechanisms:

### Resolution-time gating

In `resolve_simple_variable` and `resolve_variable`, each match arm uses a guard clause:

```rust
"songName" if has_perm(&ctx.permissions, "spotify:read") => { ... }
```

The `has_perm` helper returns `true` if:
- The permissions list is empty (owner/system context, full access), **or**
- The permissions list contains the required permission string.

If the guard fails, the variable is not matched and falls through to `None`, which the parser converts to an empty string (for known variables) or leaves as-is (for unknown variables).

### Static analysis via `required_permissions`

The `required_permissions(template)` function statically analyzes a template to determine which permissions are needed:

```rust
let perms = required_permissions("Now playing: {{songName}} by {{songArtist}}");
// Returns: ["spotify:read"]
```

This is used at automation save time to warn users about missing permissions. It calls `permission_for_variable` for each extracted variable name, collecting unique permission strings.

### Current permission mapping

| Permission | Variable Groups |
|-----------|----------------|
| None | Channel, Bot, Time, Shopify, OBS, Discord, Custom (`var.*`) |
| `chat:userinfo` | User (`username`, `displayName`, `avatarUrl`, `userId`) |
| `events:read` | Stream, Channel Status, Sub, Cheer, Raid, Redemption, Follower, Tip, Hype Train, Poll, Prediction, Event (`event.*`) |
| `spotify:read` | Spotify (`songName`, `songArtist`, etc.) |

## Variable Resolution Order

1. The `parse` function finds all `{{variable}}` patterns via regex.
2. For each match, `resolve_variable` is called.
3. Dotted paths (`event.type`, `discord.serverName`, `var.myVar`) are handled first via prefix matching.
4. Single-segment names are delegated to `resolve_simple_variable`.
5. If resolution returns `None`:
   - If the variable is a known permission-gated variable (checked via `permission_for_variable`), it resolves to an empty string (permission denied or data not populated).
   - Otherwise, the `{{variable}}` placeholder is left unchanged in the output.

## Testing

The template engine has comprehensive tests in the same file. When adding new variables, add corresponding tests:

```rust
#[test]
fn test_my_new_variable() {
    let ctx = TemplateContext {
        my_new: Some(MyNewVars {
            field_one: Some("hello".to_string()),
            ..Default::default()
        }),
        ..Default::default()
    };
    assert_eq!(parse("Value: {{fieldOne}}", &ctx), "Value: hello");
}
```

---

## Developer Guide / Plugins (removed)

Source: https://docs.lumio.vision/developer-guide/plugins

# Plugins (removed)

> **Migration complete:**
> The plugin system (`lo-plugins` crate, `PluginRegistry`, `GET /v1/plugins` endpoints) has been removed. All built-in widgets and bot modules are now **system extensions** in the Extension Store.

## What changed

| Before | After |
|--------|-------|
| `crates/lo-plugins/` - Rust crate with trait-based plugin system | Removed |
| `crates/lo-bot-modules/` - native Rust bot module implementations | Removed (replaced by V8 system extensions) |
| `shared/plugins/` - TypeScript plugin registry | Removed |
| `GET /v1/plugins` - plugin discovery endpoint | Removed |
| `PluginRegistry` in API startup | Removed |
| Hardcoded `WidgetType` enum | Deprecated (use `extension_id`) |

## Where things moved

- **Built-in widgets and bot modules** are now system extensions. See [Extensions](../features/extensions.md).
- **Platform metadata** is served by `GET /v1/platforms/metadata` (hardcoded in Rust, no DB query).
- **Event types** remain in TypeScript/Rust enums (`shared/types/src/event.ts`, `crates/lo-events/`).
- **Automation nodes** are served by `GET /v1/automation/extension-nodes`.

---

## Developer Guide / Copyright Manager

Source: https://docs.lumio.vision/developer-guide/copyright-detection

# Copyright Manager

Copyright Manager classifies a song as **safe**, **blocked**, **reported**, or **unknown** when a client requests a status lookup. It also provides account song lists, community reports, and an operator moderation queue. No automatic background copyright check runs.

## Architecture

There is no standalone `lo-copyright` crate - copyright is implemented entirely inside the API app. The moving parts are:

| Layer | Path |
|-------|------|
| REST handlers | `apps/api/src/routes/copyright.rs` |
| GraphQL resolvers | `apps/api/src/graphql/copyright.rs` |
| DB access + business logic | `apps/api/src/db/copyright.rs` |
| Inactive live-checking worker implementation | `apps/api/src/workers/copyright.rs` |
| Curated-playlist → Spotify sync worker | `apps/api/src/workers/playlist_sync.rs` |
| Spotify integration (metadata + playlist import) | `crates/lo-spotify-api` |
| Feature flag gate | `feature:copyright_detection` (checked via `require_feature` in every handler) |
| Permissions | `copyright:read`, `copyright:edit`, `copyright:delete`, `copyright:vote`, `copyright:report`, `copyright:recommend`, `copyright:moderate` |

Every request path runs the same sequence: `require_permission` → `require_feature` → `db::copyright::*`. That keeps RBAC and plan-gating consistent across REST and GraphQL, as required by the GraphQL ↔ REST parity rule.

Which permission gates what:

| Surface | Permission |
|---------|-----------|
| `check`, list safe/blocked songs, list playlist syncs, list vote candidates | `copyright:read` |
| Add a safe/blocked song, import a playlist | `copyright:edit` |
| Delete a safe/blocked song or a playlist sync | `copyright:delete` |
| Cast a vote | `copyright:vote` |
| Approve / dismiss a vote candidate | `copyright:moderate` (**admin scope**) |

`copyright:read`, `copyright:edit` and `copyright:delete` also exist as **global** (system-scope) permissions with the same strings. The admin-side surfaces that read or write the account-less global tables - all-status report review (`adminReports`), curated-playlist management (`create`/`update`/`delete`/`add`/`remove`/`syncCuratedPlaylist`), and community-list moderation (`approveReport`/`dismissReport` and their REST twins `POST /v1/copyright/vote-candidates/{track_id}/approve`·`/dismiss`) - are enforced through the admin-only `AdminPermissionGuard` / `require_admin_permission`, so an account-scope grant does **not** reach them (ZAF-734, ZAF-742). `copyright:moderate` is an **admin-only** permission (moved out of account scope in ZAF-742): it writes the account-less global safe/blocked catalogue, so it is a platform-operator action, seeded to the `system_admin` admin role and not assignable to any tenant role. The account-scope resolvers in the table above (own safe/blocked lists, playlist syncs, `check`, vote candidates) keep the account-OR `PermissionGuard`.

## Lookup pipeline

`db::copyright::check_song_status` is the single entry point for "is this track OK to play?". `GET /v1/copyright/check` (REST) and `checkSong` (GraphQL) call it on demand. The copyright worker implementation also calls it, but no production path starts that worker.

The precedence is **by list, not by identifier**. Three queries run in order and the first non-empty one wins:

1. `copyright_safe_songs` → `Safe`
2. `copyright_blocked_songs` → `Blocked`
3. pending `copyright_reports` → `Reported`
4. nothing matched → `Unknown`

Safe therefore beats blocked: an explicit safe entry (yours or a global one) shadows a blocked entry for the same track.

Within each query all three identifiers are matched with `OR` in a single SQL statement, not as a fallback chain:

- `spotify_track_id` - when supplied
- `isrc` - International Standard Recording Code, stable across re-releases; when supplied. Spotify removed `external_ids` from track objects for Development Mode apps (every account Spotify app) in its February 2026 Web API changes, so tracks imported from a Spotify playlist usually have no ISRC and match on `spotify_track_id` or name + artist instead.
- `LOWER(song_name) = LOWER($4) AND LOWER(artist) = LOWER($5)` - always evaluated

Each query covers both **account-scoped rows** (`account_id = $1`) and **global rows** (`account_id IS NULL`). The return value is:

```rust
pub enum SongStatus { Safe, Blocked, Reported, Unknown }
```

`Reported` means at least one pending copyright report exists and no safe or blocked list entry took precedence.

## Data model

PostgreSQL tables (migrations in `apps/api/migrations/`):

| Table | Purpose | Scope |
|-------|---------|-------|
| `copyright_safe_songs` | Known-safe tracks (whitelist). | Per-account **or** global (`account_id IS NULL`). |
| `copyright_blocked_songs` | Known-copyrighted tracks (blacklist). | Per-account **or** global. |
| `copyright_reports` | Individual community votes (one row per user per track per report type). Formerly `copyright_votes`. | Global. |
| `copyright_playlist_syncs` | Imported Spotify playlists whose tracks are auto-added to safe-songs. | Per-account. |
| `copyright_curated_playlists` · `copyright_curated_playlist_tracks` | Admin-curated global safe catalogue, synced out to Spotify. | Global. |
| `copyright_abuse_reports` | Reports of abuse of the voting system itself. | Global. |

Every safe/blocked row carries a `source` string (`manual`, `playlist`, `community_vote`, …) and, for playlist imports, a `source_ref` pointing at the `copyright_playlist_syncs` row. Community submissions alone do not write either global list; an operator must approve a candidate.

## Community voting flow

Users with `copyright:vote` can submit a vote on any song via `POST /v1/copyright/vote` (`castVote` mutation):

```json
{
  "spotify_track_id": "3n3Ppam7vgaVa1iaRUc9Lp",
  "song_name": "Song Title",
  "artist": "Artist Name",
  "vote_type": "copyright" | "safe",
  "category": "dmca" | "sync_license" | ...,
  "recommendation_category": "lofi" | "electronic" | ...,
  "vod_url": "https://...",
  "vod_timestamp": "01:23:45",
  "message": "optional note"
}
```

A vote is stored as a `copyright_reports` row with `report_type = 'copyright'` (flagging as unsafe) or `report_type = 'recommendation'` (endorsing as safe).

The submission creates a moderation candidate and leaves the song in the `Reported` state unless a safe or blocked list entry already takes precedence. Vote counts do not add a song to the global blocked or safe list or dismiss its reports. Only an operator with the admin-scope `copyright:moderate` permission can approve or dismiss a candidate.

## Admin recommendation queue

`GET /v1/copyright/vote-candidates` and GraphQL `voteCandidates` share one query: a candidate is a track with at least one `pending` report. Confirmed and dismissed reports (already moderated via `approveReport` / `dismissReport`) neither make a track a candidate nor count towards its tallies. Both return a row per candidate with pending-only counters:

```json
{
  "spotify_track_id": "…",
  "song_name": "…",
  "artist": "…",
  "copyright_votes": 2,
  "safe_votes": 1,
  "total_votes": 3
}
```

Admins act on each candidate via:

- `POST /v1/copyright/vote-candidates/{track_id}/approve` - accepts the majority verdict: if `copyright_votes > safe_votes` the track is added to the **global** blocked list, otherwise to the global safe list, both with `source = 'community_vote'`. `dismiss_reports` then deletes the track's pending reports.
- `POST /v1/copyright/vote-candidates/{track_id}/dismiss` - deletes the track's pending reports, returning it to `Unknown` unless a list entry applies. Confirmed and dismissed reports stay. A track without pending reports returns `404`.

Both endpoints require the **admin-scope** `copyright:moderate` (checked against `admin_permissions` only, via `require_admin_permission` on REST and `AdminPermissionGuard` on GraphQL). Moderating a candidate writes the account-less **global** catalogue, so it is a platform-operator action - not reachable by a tenant Owner/Administrator (ZAF-742).

Approvals emit `copyright:moderation_approved`; dismissals emit `copyright:moderation_dismissed` only when a report was actually dismissed. REST and GraphQL emit the same system-scoped audit types after the write. The actor is the operator; `account_id` is null. Metadata contains `spotify_track_id`, `list` (`blocked`, `safe`, or null), `source`, and `decision` (`approved` or `dismissed`), without song title, artist, or reporter identity. See [Audit Events](./audit-events.md).

## Playlist import (safe-list bootstrap)

Streamers can seed their account-scoped safe list from a Spotify playlist:

```
POST /v1/copyright/import-playlist { "spotify_playlist_id": "<id>" }
```

The handler pulls tracks via `lo_spotify_api::SpotifyClient::get_playlist_tracks` (up to 100), upserts them into `copyright_safe_songs` with `source = 'playlist'`, and writes a `copyright_playlist_syncs` row recording the playlist name, track count, and `last_synced_at`. `GET /v1/copyright/playlist-syncs` / `DELETE /v1/copyright/playlist-syncs/{id}` manage existing syncs; deletion also removes every safe-song entry sourced from that sync (see `db::copyright::delete_playlist_sync`).

Auto-sync (re-importing an account's playlist periodically to pick up new tracks the curator adds) is modelled in the `copyright_playlist_syncs.auto_sync` column and tracked by `last_synced_at`, but no worker acts on it today - account playlist syncs are re-run on demand.

The background worker that does exist, `apps/api/src/workers/playlist_sync.rs`, works the other direction and on a different object: every 5 minutes (after a 30 s startup delay) it pushes the **admin-curated** global playlists out to Spotify, reconciling each `curated_playlists` track list against the Spotify playlist using system-level Spotify credentials from `integration_configs`.

## Live checking worker status

No background copyright check runs. `WorkerManager::start_copyright_worker` exists in `apps/api/src/workers/manager.rs`, but nothing calls it. The implementation in `apps/api/src/workers/copyright.rs` would poll the current Spotify track if started:

- It decides whether the account is live by reading the YouTube worker's Redis cache at `lumio:youtube:active_streams:{account_id}` - it never calls the YouTube API itself.
- A check runs when a broadcast is active **or** when the worker is in `proactive_mode`.
- Poll interval: **30 s** while a broadcast is active (`ACTIVE_CHECK_INTERVAL_SECS`), **60 s** otherwise (`NO_BROADCAST_POLL_INTERVAL_SECS`).
- The Spotify token is re-fetched every poll via `crate::oauth::get_fresh_connection_token` - never refreshed inline.
- It emits one of three event types: `copyright:warning`, `copyright:blocked`, `copyright:clear`.

## Integration with the Music feature

The inactive worker does **not** annotate `spotify:track` events with a status field. Its code defines the following events, but it currently emits none because the worker is never started:

| Situation | Event emitted | Extra behaviour |
|-----------|---------------|-----------------|
| Track is on a blocked list | `copyright:blocked` | - |
| Track is `Unknown` **and** a YouTube restriction was detected | `copyright:warning` | Auto-learn: the track is added to the **account's** blocked list |
| Track is `Safe` **and** a YouTube restriction was detected | `copyright:clear` | Signals a likely false positive |
| Anything else | none | - |

Every payload carries `{ song_name, artist, spotify_track_id, restriction_detected }`.

The on-demand status lookup does not mute audio or emit these events. See [Spotify](/features/spotify) for the running Now Playing worker.

## GraphQL surface

`apps/api/src/graphql/copyright.rs` covers the REST surface under different names, and adds several capabilities that have no REST counterpart today. Match the names carefully - they are not a mechanical rename of the REST paths.

| REST | GraphQL |
|------|---------|
| `GET /v1/copyright/check` | `checkSong(spotifyTrackId, isrc, title, artist)` |
| `GET/POST /v1/copyright/safe-songs`, `DELETE .../{id}` | `safeSongs`, `addSafeSong`, `deleteSafeSong` |
| `GET/POST /v1/copyright/blocked-songs`, `DELETE .../{id}` | `blockedSongs`, `addBlockedSong`, `deleteBlockedSong` |
| `POST /v1/copyright/import-playlist` | `importPlaylist(spotifyPlaylistId)` |
| `GET /v1/copyright/playlist-syncs`, `DELETE .../{id}` | `playlistSyncs`, `deletePlaylistSync` |
| `POST /v1/copyright/vote` | `createCopyrightReport` (flag) / `createSafeRecommendation` (endorse) |
| `GET /v1/copyright/vote-candidates` | `voteCandidates` |
| `POST /v1/copyright/vote-candidates/{track_id}/approve` · `/dismiss` | `approveReport(id, addToPlaylistId)` · `dismissReport(id)` - note these take a **report id**, not a track id |

The GraphQL surface also includes:

- **Report evidence:** `confirmCopyrightReport(reportId, input)` adds evidence to an existing report.
- **Admin review:** `adminReports(status, reportType, limit, offset)`.
- **Curated playlists:** `createCuratedPlaylist`, `updateCuratedPlaylist`, `deleteCuratedPlaylist`, `addToCuratedPlaylist`, `removeFromCuratedPlaylist`, `syncCuratedPlaylist`, `curatedPlaylistTracks` - the admin-curated global safe catalogue.
- **Preview-then-import:** `previewPlaylist(spotifyPlaylistId)` fetches the tracks, checks each one, and caches the result in Redis for 10 minutes; `importSelectedSongs(input)` then imports only the chosen tracks from that cache.
- **Public (unauthenticated) reads:** `publicSafeSongs`, `publicBlockedSongs`, `publicReports`, `publicSystemPlaylists`, `publicSystemPlaylist`, `publicSong`, `publicSongSitemap`, `publicSongStatus`. `publicReports` returns the **PII-free** `PublicCopyrightReport` projection - song name, artist, Spotify track id, report type, category, confirmation count and timestamp only. It never exposes the reporter's identity (`voterId`), free-text `message`, or VOD evidence (`vodUrl`/`vodTimestamp`); those are reachable only on the authenticated admin path (`adminReports`).

  The marketing `/music/*` pages use server-side GraphQL reads; browser refreshes use the `/api/copyright/*` proxy, never a direct browser GraphQL call. Song and playlist detail pages call `publicSong(id)` and `publicSystemPlaylist(id)` once per request through `serverGqlSSR()`; page and metadata share the result. Sitemap and public plan reads use the anonymous `anonymousGql()` helper inside the Next data cache, with no visitor credentials. The song and playlist reads have public REST twins in `routes/songs.rs` (`/v1/songs`, `/v1/songs/check`, `/v1/songs/sitemap`, `/v1/songs/{id}`) and `routes/playlists.rs` (`/v1/playlists`, `/v1/playlists/{id}`), listed in [Copyright → Public REST endpoints](../features/copyright.md#public-rest-endpoints). Both protocols run the same fail-closed `feature:copyright_detection` check: `FeatureGuard` on GraphQL, `require_feature(…, auth.account_id())` with `OptionalAuth` on REST. `routes/songs.rs` registers `/songs/check` and `/songs/sitemap` before `/songs/{id}`, whose `Path<Uuid>` would otherwise match them. `publicSongSitemap` is keyset-paged on `id` (page ≤ 5,000, `account_id IS NULL` on both list branches, `lastmod` = `created_at`); the included lists are the server constants `SONG_SITEMAP_INCLUDE_SAFE` / `SONG_SITEMAP_INCLUDE_BLOCKED` in `db/copyright.rs`.
- **`recentlyPlayedSongs(days, limit)`** - TimescaleDB `spotify:track` events cross-referenced against the copyright database.

Where a capability exists on both protocols, inputs, permission strings, feature-flag guards, and error messages must stay identical - do not change one side without the other in the same PR.

## Key files

- `apps/api/src/routes/copyright.rs` - all REST handlers: 14 operations across 12 paths.
- `apps/api/src/graphql/copyright.rs` - GraphQL queries + mutations.
- `apps/api/src/db/copyright.rs` - `SongStatus`, `check_song_status`, `add_safe_song` / `add_blocked_song`, playlist import, report counters.
- `apps/api/migrations/` - `copyright_*` table migrations (search for `copyright_safe_songs`).
- `crates/lo-spotify-api` - Spotify API client used for playlist imports and track metadata.

---

## Developer Guide / Feature Flags (Developer Guide)

Source: https://docs.lumio.vision/developer-guide/feature-flags

# Feature Flags (Developer Guide)

This guide covers the feature-flag system from a developer perspective: the flag taxonomy, resolution order, backend service, and frontend primitives used to gate pages, actions, and UI elements.

## Flag Taxonomy

Every flag key is prefixed with its category. Use the correct category - misclassified flags cause the wrong resolution logic to be applied and may show up in incorrect admin UI sections.

| Category | Use for | Examples |
|----------|---------|---------|
| `feature:*` | Dashboard pages and major feature areas | `feature:bots`, `feature:music` |
| `widget:*` | Overlay widgets only (render inside a broadcast overlay) | `widget:chat_box`, `widget:event_list`, `widget:obs_browser_source` |
| `integration:*` | Third-party tool integrations (modal entries) | `integration:shopify`, `integration:obs_websocket` |
| `platform:{x}` | Streaming platform master kill-switch | `platform:twitch`, `platform:youtube` |
| `platform:{x}:{type}` | Platform sub-flag for connection type | `platform:twitch:login`, `platform:kick:channel` |
| `system:*` | User-scope system controls; resolved by `AccountCreationService`, not `FeatureService` | `system:account_creation` |
| `bot_module:*` | Individual bot moderation modules | `bot_module:link_protection` |

### Key rules

- `feature:*` flags gate **pages and dashboard features** - never use `widget:*` flags for this purpose.
- `integration:*` flags gate **integrations modal entries**, not streaming platform connections.
- `system:*` flags are **user-scoped** - they include a per-user override layer that other categories lack. Do not resolve `system:*` flags through `get_feature_statuses` (it filters them out of the global snapshot); use `can_user_create_account()`.

## Resolution Chain

### Account-scope flags (`feature:*`, `widget:*`, `integration:*`, `platform:*`, `bot_module:*`)

Resolution stops at the first layer that returns `enabled = false`:

1. **`GLOBAL_OFF`** - the flag is disabled globally (admin kill-switch in the `feature_flags` table, served from `FeatureService`'s in-process `global_cache`).
2. **`PLAN_LOCKED`** - the account's plan does not include this feature (`plan_features` table).
3. **`ACCOUNT_OVERRIDE`** - an explicit per-account override has disabled this feature (`account_features` table).
4. **Enabled** - none of the above applied; `reason` is `null`.

Fail-closed rules to keep in mind:

- A key that is **not in the global cache** resolves to `false` in `is_enabled()` (`resolve_enabled` returns `false` for `None`), so a flag referenced in code but never seeded is off.
- The pricing-card query (`PRICING_FEATURES_SQL` in `apps/api/src/db/plans.rs`) uses `COALESCE(pf.enabled, false)` - a flag with **no** `plan_features` row shows as not-included for that plan.
- `get_feature_statuses` / `build_resolved_features`, by contrast, fall back to the flag's `default_for_accounts` column when neither a plan row nor an account row exists. Seed the paired `plan_features` rows rather than relying on that default.

`FeatureService::get_feature_statuses(account_id, plan_id) -> anyhow::Result<Vec<FeatureStatus>>` returns the statuses for all non-`system:` flags. It filters `system:` keys out of the global snapshot - user-scope flags are merged in by the caller.

### User-scope flags (`system:account_creation`)

Resolved by `can_user_create_account()` in `apps/api/src/services/account_creation.rs`:

1. **`USER_OVERRIDE`** - the `users.account_creation_override` column is explicitly `true` (allow) or `false` (deny). A `deny` override here blocks the user regardless of global state; an `allow` override grants access regardless of global state.
2. **`GLOBAL_OFF`** - if no per-user override is set and the global `system:account_creation` flag is disabled.
3. **Enabled** - no override, global flag is on.

Cache keys (both TTL 3600 s, `TTL_SECS`):

| Key | Holds |
|-----|-------|
| `lumio:system:account_creation_enabled` | The global flag value |
| `lumio:user:{user_id}:account_creation_override` | The per-user override |

Both entries are invalidated when the flag or the override changes.

### `FeatureStatus` struct

```rust
pub struct FeatureStatus {
    pub key: String,
    pub enabled: bool,
    pub reason: Option<FeatureDisabledReason>,
}

pub enum FeatureDisabledReason {
    GlobalOff,
    PlanLocked,
    AccountOverride,
    UserOverride,
}
```

The two protocols spell the same enum differently, each following its own convention:

| Protocol | Type | Wire values |
|----------|------|-------------|
| GraphQL | `FeatureDisabledReasonGql` | `GLOBAL_OFF`, `PLAN_LOCKED`, `ACCOUNT_OVERRIDE`, `USER_OVERRIDE` |
| REST | `FeatureDisabledReasonRest` | `global_off`, `plan_locked`, `account_override`, `user_override` |

> **Caution:**
> Never use a raw `reason` as an i18n key or compare it against a literal. The
> `featureGate.*` message keys are snake\_case, so a GraphQL-sourced `GLOBAL_OFF`
> renders the untranslated key instead of a message. Run every wire value through
> `normalizeFeatureReason()` first - `FeatureProvider`, `resolveReason()` and
> `<FeatureDisabledPage>` already do. Unknown values collapse to `null`, never to a
> wrong key.
> 
> `normalizeFeatureReason` lives in **`apps/web/src/lib/feature-reason.ts`**, which
> carries no `"use client"` directive, so server components can import it directly.
> `feature-context.tsx` re-exports `FeatureDisabledReason`, `FeatureStatus` and
> `FeatureStatusInput` as **types only** - importing the function through that
> client module from a server component crosses the client/server boundary and
> fails at request time. Server code imports from `@/lib/feature-reason`.

## Backend Service

### `FeatureService` (account-scope)

Located at `apps/api/src/services/feature_service.rs`. Constructor: `FeatureService::new(db: PgPool, redis: RedisClient)`.

Key methods:

| Method | Description |
|--------|-------------|
| `is_enabled(feature_key, account_id: Option<Uuid>)` | Boolean check for a single flag key. Unknown key → `false`. Passing `None` yields the global default (no Redis lookup) |
| `is_enabled_global(feature_key)` | Global-only check straight from the in-memory cache, no DB or Redis hit |
| `get_enabled_features(account_id)` | Sorted `Vec<String>` of the flag keys `is_enabled(key, Some(account_id))` would allow; both share `resolve_enabled` |
| `get_feature_statuses(account_id, plan_id)` | `Vec<FeatureStatus>` with a reason for every non-`system:` flag |
| `compute_me_feature_statuses(user_id, active_account_id)` | Merges account-scope statuses with the user-scope `system:account_creation` status; the canonical list behind both `Me.featureStatuses` and `GET /v1/users/me` |
| `is_provider_enabled` / `get_enabled_providers` / `get_enabled_platforms` / `get_streaming_platforms` | Platform-flag helpers over the same cache |
| `refresh_global_cache()` | Reloads `feature_flags` into the in-memory cache; a background worker calls it every 5 minutes |
| `invalidate_account_cache(account_id)` / `invalidate_plan_accounts_cache(plan_id)` | Drop the resolved-feature Redis entries after an override or plan change |

The resolved per-account map is cached in Redis under `lumio:account_features:{account_id}` with a 1-hour TTL; precedence is global defaults < plan defaults < account overrides (`merge_resolved_features`).

### Server-side enforcement coverage

The client-side route gate is a UX layer, **not** the security boundary - a
disabled flag must be rejected by the API on a direct call. Each user-facing
`feature:*` key is enforced identically on both protocols: GraphQL via
`FeatureGuard::new("{key}")` (composed with the resolver's `PermissionGuard` via
`.and(...)`) and REST via `require_feature(&state.feature_service, "{key}", account_id)`.
Both surface the same fail-closed error (`Feature '{key}' is not available`,
HTTP `403`). This table is the audited map; keep it in step with the resolvers
so the two protocols never drift apart.

| Feature key | GraphQL resolver | REST route | Enforced (GraphQL / REST) |
|-------------|------------------|-----------|---------------------------|
| `feature:multichat` | `chat.rs`, `youtube_memberships.rs` | `chat.rs` | ✅ / ✅ |
| `feature:chat-viewer-list` | `chat.rs` (`chatters`) | `chat.rs` (`GET /v1/chat/chatters`) + WS `chatters:*` (`channel_feature_for`) | ✅ / ✅ |
| `feature:automation` | `automations.rs` | `automations.rs` | ✅ / ✅ |
| `feature:obs_remote` | `obs.rs` | `obs_remote.rs`, `obs_integration.rs` | ✅ / ✅ |
| `feature:copyright_detection` | `copyright.rs` | `copyright.rs` | ✅ / ✅ |
| `feature:streamelements` | `se_tokens.rs` | `se_tokens.rs` | ✅ / ✅ |
| `feature:music` | `spotify.rs` | `spotify.rs` | ✅ / ✅ |
| `feature:bots` | `bot_connections.rs` | `bot_connections.rs` | ✅ / ✅ |
| `feature:bot_modules` | `bot_modules.rs` | `bot_modules.rs` (umbrella + per-module `bot_module:{name}`) | ✅ / ✅ |
| `feature:bot_commands` | `bot_commands.rs` | `bot_commands_crud.rs` | ✅ / ✅ |
| `feature:connections` | `connections.rs` | `connections.rs` | ✅ / ✅ |
| `feature:rewards` | `rewards.rs` | *(no REST surface - GraphQL-only)* | ✅ / n/a |
| `feature:overlay_folders` | `overlay_folders.rs` | `overlay_folders.rs` | ✅ / ✅ |
| `feature:overlay_access` | `overlays.rs` | `overlays.rs` | ✅ / ✅ |
| `feature:overlay_sharing` | `overlays.rs` | `overlays.rs` | ✅ / ✅ |
| `feature:widgets` | `widgets.rs` | `widgets.rs` | ✅ / ✅ |
| `feature:sounds` | `sounds.rs` | `sounds.rs` | ✅ / ✅ |
| `feature:extensions` | `extension_store.rs`, `extension_access.rs` | `extension_*.rs` | ✅ / ✅ |
| `feature:extension_development` | `developer_*.rs`, `bot_module_extensions.rs` | `developer_*.rs`, `bot_module_extensions.rs` | ✅ / ✅ |
| `feature:multi_account` | `accounts.rs` (inline `is_enabled`) | `accounts.rs` (inline `is_enabled`) | ✅ / ✅ |
| `feature:advanced_overlays` | *(UI-only)* | *(UI-only)* | n/a - gates overlay-editor capabilities in the webapp SSR (`overlays/{id}/editor`), no dedicated resolver |
| `feature:custom_bot` | `bot_connections.rs` (`authorize_bot`) | `bot_connections.rs` (`authorize` + shared `complete_bot_connection` choke) | ✅ / ✅ |
| `feature:extension_paid` | `extension_store.rs` (`install_extension`, when `pricing_type != "free"`) | `extension_store.rs` (`install_extension`), `extension_purchases.rs` (`create_purchase`) | ✅ / ✅ |
| `feature:apikeys` | `tokens.rs`, `service_keys.rs` (**create/edit only**) | `tokens.rs`, `service_keys.rs` (**create/edit only**) | ✅ / ✅ (create/edit) |

`feature:advanced_overlays` has no dedicated API surface - the base overlay
resolvers already gate on `feature:overlays`/`feature:overlay_*`, and the flag
only toggles editor capabilities in the webapp. `feature:custom_bot` (a paid
unlock - "connect your own bot account", i.e. OAuth a per-account
`bot_type = "custom"` identity) is enforced at the custom-bot **connect**
surface: GraphQL `authorize_bot` and REST `authorize` fail fast, and the shared
`complete_bot_connection` choke that every OAuth exchange path funnels through —
including the unified callback, which carries no plan context of its own - is the
authoritative gate. It gates only custom-bot connects, never global-bot
operations (`toggle_bot_for_platform` / `rejoin_bot` / `delete_bot_connection`).
`feature:extension_paid` (a paid unlock layered on top of the `feature:extensions`
umbrella) is enforced at the paid-extension **acquisition** points: the REST
`create_purchase` route (`POST /v1/extension-purchases`) gates on it
unconditionally (purchase is inherently paid, and there is no GraphQL twin - a
deliberate single-protocol gate), while both `install_extension` paths (GraphQL
and REST) gate on it only when the resolved extension `pricing_type != "free"`,
so free extensions install unaffected. The Stripe `checkout.session.completed`
webhook auto-install is intentionally **not** gated - it is a server-side
post-payment callback, not a user request, and a gate there would wrongly reject
a legitimate completed purchase. Its account default is `default_for_accounts =
true`; the free plan is denied by its explicit `plan_features (enabled = false)`
row (`20260517000002_plan_features_extension_platform`).

`feature:apikeys` (a Pro-plan unlock, ZAF-1173) is enforced **only on the
lifecycle-mutating actions** of both API keys (`lm_usr_*`) and account service
keys (`lm_svc_*`): `create_*` and `update_*` gate on it, `list_*`/`delete_*` do
**not**. The read/delete carve-out is deliberate and load-bearing - flipping the
flag off (a downgrade) must never strip a user of the ability to **list and
revoke** a live credential, so only creating and renaming are locked. The same
carve-out holds on both protocols (parity), and the free plan is denied by its
explicit `plan_features (enabled = false)` row plus `default_for_accounts = false`
(`20260909000001_apikeys_pro_only`). A source tripwire
(`apps/api/tests/apikeys_pro_plan_gate.rs`) locks this split so read/delete cannot
silently drift back behind the gate.

On the frontend the API Keys **sidebar entry follows `feature:apikeys`
unconditionally** (ZAF-1222/ZAF-1242) - a disabled flag hides it, including a
`plan_locked` downgrade. The route stays reachable by direct URL and renders the
locked list (revoke enabled, create/edit disabled); the discovery path for a
downgraded user is a notice on the Subscription page that appears only when the
account still holds live keys. Do not re-add an ungated nav entry - the earlier
ZAF-1173 carve-out left a dead sidebar link for every Free/planless account.

### Account creation (user-scope)

Located at `apps/api/src/services/account_creation.rs`. This is a plain module of free functions - there is no `AccountCreationService` type.

| Function | Description |
|----------|-------------|
| `can_user_create_account(db, redis, user_id)` | Returns `anyhow::Result<CreationDecision>`, where `CreationDecision { allowed: bool, reason: Option<FeatureDisabledReason> }` |
| `invalidate_global_flag(redis)` | Invalidates the global flag cache entry |
| `invalidate_user_override(redis, user_id)` | Invalidates the per-user cache entry |

`can_user_create_account` is called in both the `createAccount` GraphQL mutation and the `POST /v1/accounts` REST handler to enforce the same gate on both protocols.

### Cache invalidation

When the `system:account_creation` feature flag is toggled via `PATCH /v1/admin/feature-flags/{id}` or the GraphQL `updateFeatureFlag` mutation, `invalidate_global_flag()` is called. When `PATCH /v1/admin/users/{id}` updates `account_creation_override`, `invalidate_user_override()` is called.

## GraphQL API

### `me { featureStatuses }`

Returns merged account-scope + user-scope statuses for the current user. Available on `MeResult` in `me { ... }` queries.

### `accountFeatures { enabledFeatures featureStatuses }`

Returns account-scope-only statuses (no `system:*`) for the caller's active account. Works with popout-token auth.

### `enabledFeatures` vs `featureStatuses`

The two fields come from different sources:

- `featureStatuses` is resolved fresh from the database on every query and carries a disabled reason per flag.
- `enabledFeatures` is the list of keys the API guards allow for the account. It walks every flag in the global cache and decides each one with the same `resolve_enabled()` core that `is_enabled()` uses — and with it every `FeatureGuard`, REST `require_feature` and WebSocket gate. Per-account values come from the cached map `lumio:account_features:{account_id}` (1-hour TTL).

A flag seeded after that map was built is missing from the map. Both `is_enabled()` and `enabledFeatures` then fall back to the flag's `default_for_accounts`, so a freshly seeded default-on flag shows up in `enabledFeatures` as soon as the global cache picks it up (at startup, or within the 5-minute refresh) — the same moment the guards allow it. A key left in the cached map after its flag was deleted is dropped (unknown key, fail closed), and a global kill switch hides a flag even if the cached map still says `true`.

The two fields can still disagree while a cached map is stale for a reason other than a new flag — for example a plan-feature change that skipped `invalidate_plan_accounts_cache()`. `enabledFeatures` then matches what the guards enforce, and `featureStatuses` shows the database state.

UI gating that must match the dashboard's `FeatureProvider` derives its list from `featureStatuses`, using `enabledFeatureKeys()` in `apps/web/src/lib/feature-reason.ts`. The chat popout (`/popout/chat`) does this in both auth modes.

### `adminUpdateUserAccountCreationOverride(userId: UUID!, override: AccountCreationOverride!): AdminUser!`

Admin mutation to set a per-user override; it returns the updated `AdminUser`, not a boolean. `AccountCreationOverride` enum: `DEFAULT`, `ALLOW`, `DENY`.

## REST API

| Endpoint | Description |
|----------|-------------|
| `GET /v1/users/me` | Includes `feature_statuses[]` in the response |
| `GET /v1/accounts/{id}/enabled-features` | Enabled flag keys for an account |
| `GET /v1/accounts/{id}/feature-statuses` | Full status list with reason for an account |
| `GET /v1/features/enabled` | Global check for a single key (`?key=...`); reachable without an account |
| `PATCH /v1/admin/users/{id}` | Set `account_creation_override` - body value is the string `"default"`, `"allow"` or `"deny"` |
| `GET /v1/admin/feature-flags` · `GET /v1/admin/feature-flags/detail` | Admin flag registry |
| `PATCH /v1/admin/feature-flags/{id}` · `PUT /v1/admin/feature-flags/{id}/detail` | Toggle / edit a flag |
| `PUT /v1/admin/plans/{id}/features` | Set a plan's `plan_features` rows |
| `GET`/`PUT /v1/admin/accounts/{id}/features` · `DELETE /v1/admin/accounts/{id}/features/{feature_id}` | Per-account overrides (`account_features`) |

See [REST API reference](../api-reference/rest-api.md#feature-flags--status) for response shapes.

## Frontend Primitives (Webapp)

All primitives live in `apps/web/src/`.

### `FeatureProvider`

Context provider (`contexts/feature-context.tsx`) that supplies feature data to the component tree. Mount it in the app shell layout with the flags loaded from the server.

### `useFeature(key: string): boolean`

Returns `true` if the given feature key is enabled for the current account. Returns `false` while statuses are not loaded.

### `useFeatureStatus(key: string)`

Returns `{ enabled: boolean; reason: FeatureDisabledReason | null; isLoaded: boolean }`. Use this when you need a reason-aware disabled state (e.g. an upgrade prompt for `plan_locked`). An unknown key on a loaded context yields `{ enabled: false, reason: "global_off", isLoaded: true }`.

### Other hooks

| Hook | Returns |
|------|---------|
| `useFeatures()` | `string[]` of enabled keys |
| `useFeatureStatuses()` | The raw `Map<string, FeatureStatus>` |
| `useIsFeatureEnabled()` | A `(key) => boolean` predicate usable inside loops/filters without breaking the rules of hooks. **Fails open** while statuses are unloaded, so a nav bar does not empty itself during an API hiccup |

### `<FeatureGate flag={string} mode={...}>`

Declarative gate component (`components/feature-gate.tsx`). The prop is **`flag`**, not `key` or `featureKey`.

| `mode` prop | Behaviour when the feature is disabled |
|-------------|----------------------------------------|
| `page` (**default**) | Renders `<FeatureDisabledPage reason={reason ?? "global_off"} />` |
| `hide` | Renders nothing |
| `alert` | Renders the children (the section handles its own messaging) |

While the context is not loaded - API unreachable or SSR failed - every mode renders the children, so an outage never masquerades as "disabled".

```tsx
<FeatureGate flag="feature:music" mode="page">
  <MusicDashboard />
</FeatureGate>
```

### `<FeatureDisabledPage reason={...}>`

Full-page disabled state (`components/feature-disabled-page.tsx`). Renders a different message per reason:

- `plan_locked` - upgrade CTA
- `global_off` - "Feature unavailable" message (admin-controlled)
- `account_override` - "Feature disabled for your account"
- No reason / fallback - generic disabled page

### Server-side route gate (`<FeatureRouteGate>`)

Hiding a sidebar entry does **not** close a route - a direct link still renders
the page. Close the whole segment from its `layout.tsx`, so every nested route
(`/dashboard/widgets/{id}/designer` as well as `/dashboard/widgets`) is covered
by one gate:

```tsx
// apps/web/src/app/(main)/(app)/dashboard/widgets/layout.tsx
import type { ReactNode } from "react";
import { FeatureRouteGate } from "@/components/feature-route-gate";

export default function WidgetsLayout({ children }: { children: ReactNode }) {
  return <FeatureRouteGate feature="feature:widgets">{children}</FeatureRouteGate>;
}
```

`FeatureRouteGate` (`components/feature-route-gate.tsx`) calls `checkFeatureSSR`
(`lib/feature-status.ts`), which reads the JWT from cookies and queries
`me { enabledFeatures featureStatuses }` over GraphQL - never use `shared/api`
REST functions in SSR pages. The fetch is request-memoised, so a nested page may
add a stricter check of its own for free: `/dashboard/overlays` gates on
`feature:overlays` in the layout, while `overlays/{id}/editor/page.tsx`
additionally requires `feature:advanced_overlays`.

The gate **fails open** when the API is unreachable (`api_unreachable`): an
outage must not look like "your administrator disabled this". The API enforces
every flag independently via `FeatureGuard` / `require_feature`, so the route
gate is a UX layer, not the security boundary.

`apps/web/__tests__/feature-route-gates.test.ts` asserts that every nav item
declaring a `feature` is covered by a layout gate, so a new route cannot ship
without one.

## Adding a New Feature Flag - Checklist

1. Register the flag. Two seed paths exist and both are in use:
   - a tuple `(category, key, label)` in `seed_default_feature_flags()` (`apps/api/src/db/admin.rs`), applied at startup; or
   - an `INSERT INTO feature_flags` in a migration under `apps/api/migrations/` (this is where `description` and `default_for_accounts` get set).
2. Add a migration that inserts `plan_features` rows for **all** existing plans. A flag with no `plan_features` row reads as not-included on the pricing card (`COALESCE(pf.enabled, false)`).
3. Add admin translation keys in `apps/admin/messages/{en,de}.json` under `featureFlags.keys."{key}"`.
4. If gating an ordinary webapp page: add `feature: "{key}"` to its nav item in `apps/web/src/app/(main)/(app)/shell.tsx` **and** a `<FeatureRouteGate feature="{key}">` in the route segment's `layout.tsx`. The nav flag only hides the link; the layout gate closes direct links. If gating a settings area, put the feature on its entry in `apps/web/src/lib/settings/sections.ts`: `sectionGate` controls the window list and the `GET /api/settings/sections/[id]` load route. The API remains the security boundary on both protocols.
5. Enforce it on the API. The route gate is UX, not the security boundary: add `FeatureGuard::new("{key}")` to the GraphQL resolvers and the matching `require_feature` check to the REST handlers, so both protocols reject identically.
6. If the flag has cache implications: add an invalidation call in both the `updateFeatureFlag` mutation and the `PATCH /v1/admin/feature-flags/{id}` REST handler.

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/services/feature_service.rs` | `FeatureService` - account-scope flag resolution |
| `apps/api/src/services/account_creation.rs` | `can_user_create_account()` - user-scope `system:account_creation` resolution |
| `apps/api/src/db/admin.rs` | `seed_default_feature_flags()` - flag seed data |
| `apps/api/src/graphql/accounts.rs` | `accountFeatures` GraphQL query |
| `apps/api/src/graphql/auth.rs` | `Me.featureStatuses`, `FeatureStatusGql`, `FeatureDisabledReasonGql` |
| `apps/api/src/graphql/admin.rs` | `adminUpdateUserAccountCreationOverride`, `AccountCreationOverride` enum |
| `apps/api/src/routes/accounts.rs` | REST `GET /accounts/{id}/enabled-features` + `/feature-statuses` |
| `apps/api/src/routes/users.rs` | REST `GET /users/me` with `feature_statuses` field |
| `apps/api/src/routes/admin.rs` | REST `PATCH /admin/users/{id}` with `account_creation_override` |
| `apps/web/src/contexts/feature-context.tsx` | `FeatureProvider`, `useFeature`, `useFeatureStatus`, `normalizeFeatureReason` |
| `apps/web/src/components/feature-gate.tsx` | `<FeatureGate>` with `mode` prop |
| `apps/web/src/components/feature-route-gate.tsx` | `<FeatureRouteGate>` - segment `layout.tsx` route gate |
| `apps/web/src/lib/feature-status.ts` | `checkFeatureSSR`, `resolveReason` - request-memoised SSR check |
| `apps/web/src/components/feature-disabled-page.tsx` | Reason-aware disabled page |

---

## Developer Guide / Extension Supervisor

Source: https://docs.lumio.vision/developer-guide/extension-supervisor

# Extension Supervisor

The Extension Supervisor is a 3-layer isolation system that sandboxes extension code using cross-origin iframes and a Web Worker. Two minimal static apps - the Supervisor and the Extension Runtime - enforce origin boundaries and message validation between the Lumio host page and untrusted extension bundles.

## Architecture

```
Host (lumio.vision)
  └─ Supervisor iframe  (supervisor.ext.lumio.vision)
       └─ Extension Runtime iframe  (<label>.runtime.ext.lumio.vision)
            └─ Web Worker  (lumio-runtime.js + extension bundle)
```

Each layer runs on a distinct origin. The browser's same-origin policy ensures no layer can access another layer's DOM, cookies, or JavaScript globals. All communication travels via `postMessage`.

### Why three layers

| Layer | Origin | Purpose |
|-------|--------|---------|
| Host | `lumio.vision` | Renders the real DOM; owns overlay/widget/editor pages |
| Supervisor | `supervisor.ext.lumio.vision` | Validates messages against an allowlist; proxies approved messages |
| Extension Runtime | `<label>.runtime.ext.lumio.vision` (one origin per extension) | Hosts the Web Worker; blocks browser storage |
| Web Worker | (spawned by Runtime) | Runs extension code with no DOM access |

A two-layer design (Host → Runtime → Worker) would let extension code send arbitrary JSON-RPC methods to the Host if the Runtime were compromised. The Supervisor layer is the enforcement point that makes the allowlist tamper-resistant - it runs on a different origin the extension code cannot reach.

## Domain setup

| Environment | Host | Supervisor | Extension Runtime |
|-------------|------|------------|-------------------|
| Production (tag `20*`) | `lumio.vision` | `supervisor.ext.lumio.vision` | `runtime.ext.lumio.vision` |
| Prod preview (`main`) | `lumio.web.prod.zaflun.dev` | `lumio.supervisor.prod.zaflun.dev` | `lumio.ext.prod.zaflun.dev` |
| Staging (`next`) | `lumio.web.staging.zaflun.dev` | `lumio.supervisor.staging.zaflun.dev` | `lumio.ext.staging.zaflun.dev` |
| Local dev | `http://localhost:4000` | `http://localhost:3200` | `http://localhost:3201` |

The Extension Runtime column is the shared base host of each environment. Extensions load from per-extension label hosts below it (next section); the base host itself is only the legacy origin during the rollout. These are the origin lists baked into each build; see the `tsup.config.ts` of both apps (defaults) and the `ALLOWED_*` env vars in `.github/workflows/deploy-extension-apps.yml` (per-environment overrides). Hosting per environment is described in [Hosting](#hosting).

### Per-extension runtime origins

Every extension gets its own Extension Runtime origin, `<label>.<runtime host>`, where the label is the extension's UUID as 32 lowercase hex characters. The builds carry one template per environment (`EXTENSION_RUNTIME_ORIGIN_TEMPLATES`):

| Environment | Runtime origin template |
|-------------|-------------------------|
| Production | `https://{label}.runtime.ext.lumio.vision` |
| Prod preview | `https://{label}.lumio.ext.prod.zaflun.dev` |
| Staging | `https://{label}.lumio.ext.staging.zaflun.dev` |
| Local dev | `http://{label}.localhost:3201` |

`@zaflun/lumio-protocol/origin` is the single source for the label and the origin: `extensionRuntimeLabel(extensionId)`, `extensionRuntimeOrigin(extensionId, template)` and `extensionRuntimeOriginLabel(origin, template)`. Each returns `null` for a non-canonical id (uppercase, missing hyphens, not a UUID) or an invalid template, and an invalid template fails the app build.

During the rollout both apps still accept the shared Runtime origins in the table above as a **legacy rule** (`ALLOWED_RUNTIME_ORIGINS` in the Supervisor, `LEGACY_RUNTIME_ORIGINS` in the Runtime). The legacy rule has no per-extension binding and is removed once every host loads extensions from their own origin.

## Hosting

Both apps are TypeScript bundled with **tsup** into a single IIFE (`dist/supervisor.global.js`, `dist/runtime.global.js`) alongside the checked-in `index.html` and `style.css`. The Runtime's `dist/` also carries the extension Worker, `dist/lumio-runtime.js`: its `build` script first runs `build:worker`, which builds the SDK's dependencies (`@zaflun/lumio-protocol`, `@zaflun/lumio-extension-types`) and then `@zaflun/lumio-sdk`'s `build:runtime` (`packages/sdk/tsup.runtime.ts`, entry `src/runtime/worker-entry.ts`), and copies the resulting `lumio-runtime.global.js` into `dist/` under the name the Host requests. The deploy workflow at `.github/workflows/deploy-extension-apps.yml` runs `pnpm install --frozen-lockfile`, builds with `pnpm --filter @lumio/extension-{supervisor,runtime} build` and deletes any `*.map` files. It also runs on changes under `packages/sdk`, `packages/protocol` and `packages/extension-types`, because the Worker bundle inlines all three.

### Supervisor and shared Runtime host: Cloudflare Pages

The Supervisor `dist/` and the Runtime `dist/` are deployed to separate CF Pages projects. The Runtime Pages project serves the shared base host from the [Domain setup](#domain-setup) table (the legacy origin) until the rollout ends.

| Branch/Tag | Supervisor project | Runtime project |
|------------|-------------------|-----------------|
| `next` | `lumio-extension-supervisor-staging` | `lumio-extension-runtime-staging` |
| `main` | `lumio-extension-supervisor-prod` | `lumio-extension-runtime-prod` |
| `20*` tags | `lumio-extension-supervisor` | `lumio-extension-runtime` |

### Per-extension Runtime hosts: Workers Static Assets

The label hosts are served by one assets-only Cloudflare Worker per environment, configured in `apps/extension-runtime/wrangler.jsonc` and deployed from the same `dist/` with `wrangler deploy --env <env>` right after the Pages deploy. The Worker has no code, so `_headers` applies to every response and static-asset requests are free.

| Branch/Tag | `wrangler` env | Worker | Route (zone) |
|------------|----------------|--------|--------------|
| `next` | `staging` | `lumio-extension-runtime-staging` | `*.lumio.ext.staging.zaflun.dev/*` (`zaflun.dev`) |
| `main` | `prod-preview` | `lumio-extension-runtime-prod-preview` | `*.lumio.ext.prod.zaflun.dev/*` (`zaflun.dev`) |
| `20*` tags | `production` | `lumio-extension-runtime-prod` | `*.runtime.ext.lumio.vision/*` (`lumio.vision`) |

- One Worker per environment, because `_headers` and the origin lists are baked into each build.
- `assets.not_found_handling` is `"none"`: a missing file answers `404`, never `index.html`. The Host always loads `/`, which stays `index.html`.
- `workers_dev` and `preview_urls` are off, so the label hosts are the only way to reach the Worker.
- A wildcard route matches only hosts below the subtree, never the base host itself, and the production subtree `runtime.ext.lumio.vision` sits next to `supervisor.ext.lumio.vision`, not above it. The route therefore never catches the Supervisor or the shared Pages host.
- Each environment needs a proxied wildcard DNS record without an origin (for example `AAAA *.lumio.ext.staging.zaflun.dev` → `100::`) and an edge certificate for the wildcard: `*.lumio.ext.staging.zaflun.dev` and `*.lumio.ext.prod.zaflun.dev` in an Advanced Certificate on `zaflun.dev`; `runtime.ext.lumio.vision` and `*.runtime.ext.lumio.vision` need Advanced Certificate Manager on `lumio.vision`, because Universal SSL covers only one level below the apex.
- The `CF_API_TOKEN` secret needs **Account · Workers Scripts · Edit**, **Zone · Workers Routes · Edit** and **Zone · Zone · Read** on `zaflun.dev` and `lumio.vision`, in addition to the Pages permissions.

### Smoke checks

After each Runtime deploy, a smoke-check step fails the job unless the Worker bundle is served as JavaScript:

- `/lumio-runtime.js` on the Pages deployment URL (and, on staging, on `https://lumio.ext.staging.zaflun.dev`) must report `application/javascript` or `text/javascript`. Without the file, the Pages SPA fallback answers `200 text/html` with `index.html`, `new Worker()` fails and no extension runs.
- On staging, the fixed test label host `https://00000000000000000000000000000001.lumio.ext.staging.zaflun.dev` must answer `/lumio-runtime.js` with `200` JavaScript whose CSP contains `'unsafe-eval'` and no `frame-ancestors` (the `!` detach worked), `/` with `200 text/html` whose CSP contains `frame-ancestors` and the Supervisor origin, and `/does-not-exist.js` with `404`.

The prod-preview and production label hosts and the public production hosts are not checked yet because they do not resolve.

The workflow uses `secrets.CF_API_TOKEN` and `secrets.CF_ACCOUNT_ID` (same secrets as all other CF Pages workflows), plus `SENTRY_DSN_SUPERVISOR` / `SENTRY_DSN_RUNTIME`.

## Security headers

Neither app has a committed `_headers` file. Each `tsup.config.ts` **generates** `dist/_headers` in its `onSuccess` hook from the same origin arrays it compiles into the bundle via `define`, so the CSP and the runtime `postMessage` allowlist can never drift apart. Both emit `X-Content-Type-Options: nosniff` and `Referrer-Policy: no-referrer` plus a CSP:

| App | CSP directives beyond `default-src 'none'` |
|-----|---------------------------------------------|
| Supervisor | `script-src 'self'`, `style-src 'self'`, `img-src 'self'`, `frame-src {runtime origin templates as wildcards, e.g. https://*.runtime.ext.lumio.vision} {legacy runtime origins}`, `connect-src https://sentry.smutje.dev`, `frame-ancestors {host origins}` |
| Runtime | `script-src 'self'`, `style-src 'self'`, `img-src 'self'`, `worker-src 'self'`, `connect-src https://sentry.smutje.dev`, `frame-ancestors {supervisor origins}` |
| Runtime Worker (`/lumio-runtime.js`) | `script-src 'self' 'unsafe-eval'` -- nothing else |

A dedicated Worker takes its CSP from its own script response, not from the page that created it. The Runtime's `_headers` therefore has a second rule for `/lumio-runtime.js` that detaches the page policy (`! Content-Security-Policy`) and sets the Worker policy. The detach is required: Pages and Workers Static Assets join a header that two matching rules set with a comma, which yields two policies that are both enforced. The Worker needs `'unsafe-eval'` because the Host fetches the extension bundle and the Worker entry evaluates it (`(0, eval)(bundleCode)`). The code it evaluates is untrusted by design and is confined by the Worker-global lockdown. `default-src 'none'` blocks `fetch`, `XMLHttpRequest`, `WebSocket` and `importScripts` from foreign origins in extension code, so every request goes through the SDK bridge.

Because the lists are per-environment, a build only advertises the origins of the environment it is built for -- the production Runtime build's `frame-ancestors` names only `supervisor.ext.lumio.vision`, the staging build only `lumio.supervisor.staging.zaflun.dev`.

When adding a new environment domain, update the origin and template defaults in both `tsup.config.ts` files **and** the matching `ALLOWED_*_ORIGINS` / `EXTENSION_RUNTIME_ORIGIN_TEMPLATES` / `LEGACY_RUNTIME_ORIGINS` env vars in `.github/workflows/deploy-extension-apps.yml`, alongside DNS, the CF Pages configuration and the route in `apps/extension-runtime/wrangler.jsonc`.

## Message validation allowlist

The Supervisor (`apps/extension-supervisor/src/supervisor.ts`) defines two sets:

### Worker → Host (extension sends, host receives)

```typescript
const ALLOWED_WORKER_TO_HOST = new Set<string>([
  "ui.render",
  "ui.ready",
  "ui.keyframes",
  "ui.error",
  "storage.set",
  "storage.get",
  "server.query",
  "server.mutation",
  "action.execute",
  "config.update",
  "ui.action",
]);
```

### Host → Worker (host sends, extension receives)

```typescript
const ALLOWED_HOST_TO_WORKER = new Set<string>([
  "lifecycle.init",
  "lifecycle.destroy",
  "event.callback",
  "event.platform",
  "storage.update",
  "theme.change",
  "config.update",
]);
```

Messages with `method` values outside these sets are dropped. A worker → host message that also carries `type: "supervisor"` is dropped too - that type is reserved for the Supervisor's own status messages. JSON-RPC response objects (with `id` but no `method`) bypass method validation - they are replies to explicit requests and must always pass through. A request id is only registered in `pendingRequestIds` **after** the message passes the allowlist, so a rejected host→worker message cannot pre-authorise an unsolicited worker→host "response" carrying that id.

**When adding a new JSON-RPC method to the protocol**, you must also add it to the appropriate allowlist in `apps/extension-supervisor/src/supervisor.ts`. The Supervisor is deployed independently; a deploy of the Supervisor alone is sufficient (no web app deploy needed).

## Security properties

| Property | Mechanism |
|----------|-----------|
| Origin isolation | Three distinct origins; browser same-origin policy blocks cross-frame access |
| Message allowlist | Supervisor drops any method not in the allowlist |
| Origin allowlist | The Supervisor checks `event.origin` against `__ALLOWED_HOST_ORIGINS__` and the Runtime against `__ALLOWED_SUPERVISOR_ORIGINS__`; messages from the Runtime frame must come from the exact origin the Supervisor bound it to |
| Origin binding | The Supervisor loads `extensionUrl` only if its origin equals `extensionRuntimeOrigin(init.extensionId, template)` for a build template, or is a legacy Runtime origin; otherwise it refuses with `EXTENSION_ORIGIN_MISMATCH` (Sentry, code only, plus a `supervisor` error to the host). A `cssUrl` is forwarded only from that same origin |
| Runtime self-check | At startup the Runtime starts a Worker only if `location.origin` is a 32-hex label origin under its own build's template or a legacy Runtime origin; otherwise it reports `INVALID_RUNTIME_ORIGIN` and starts nothing. The `?runtime=` script must be same-origin with the page (`INVALID_RUNTIME_URL`) |
| Storage isolation | Extension Runtime blocks `localStorage`, `sessionStorage`, `indexedDB`, `caches` and `BroadcastChannel` via non-configurable `Object.defineProperty` throwing getters, and neuters `document.cookie` (returns `""`, writes silently dropped) |
| Worker-global lockdown | Before any extension bundle is evaluated, the Worker entry (`packages/sdk/src/runtime/lockdown.ts`) replaces `indexedDB`, `caches`, `BroadcastChannel`, `Worker`, `SharedWorker`, the legacy `webkit*FileSystem*` functions and `navigator.storage` / `navigator.locks` / `navigator.serviceWorker` / `navigator.storageBuckets` with non-configurable throwing getters - on the Worker global and on every prototype that defines them. The extension-author view is in the developer docs (*SDK → Extension sandbox*) |
| Host boundary | The host accepts a message only when `event.source` is its Supervisor iframe **and** `event.origin` is the Supervisor origin, and posts every message (init, `lifecycle.init`, responses, destroy) to that exact origin |
| Supervisor control channel | `type: "supervisor"` messages (`loaded`, `error`, `css`) come only from the Supervisor itself: it drops relayed Runtime messages that carry that type, and the host links a `css` stylesheet only if it is the `cssUrl` the host sent in `init` |
| API CORS | No extension sandbox origin (any host with an `ext` label: runtime, per-extension runtime, Supervisor) is ever honoured as an API CORS origin; `lo_api::cors::effective_allowed_origins` drops such an entry from `cors.allowed_origins` / `LUMIO__CORS__ALLOWED_ORIGINS` and logs an error |
| Worker isolation | Web Worker has no DOM, no `document`, no `window.location` navigation |
| Network isolation | The Worker's CSP (`default-src 'none'`) blocks network requests from extension UI code; extensions use `ctx.fetch()` in server functions (egress allowlist enforced in Rust) |
| Error tracking | Sentry in both frames is consent-gated: it starts only when the host's `init` carries `errorTracking: true`. `ExtensionWorkerManager` sets it only on dashboard hosts (`errorTracking` prop: widget editor, designer) whose user's stored choice grants Functional consent; OBS overlays and widgets never set it, so Sentry stays off there. The Supervisor starts its own Sentry from that flag and passes it to the Runtime as `errorTracking=1` on the Runtime frame URL (any such parameter in `extensionUrl` is dropped first); the Runtime starts Sentry only with that parameter. The decision is read when the frame starts. No Session Replay. See [Error Tracking](./error-tracking.md#extension-supervisor-and-runtime) |
| CSP | Served as an HTTP header from the `dist/_headers` file each app generates at build time (see [Security headers](#security-headers)) |

The per-extension Runtime origin is what keeps Extension A away from Extension B's client-side state. The storage blocks and the Worker-global lockdown stay as defence in depth - they still cover the legacy shared origin during the rollout - and as the SDK contract: extensions keep no client-side storage and use `useExtensionStorage` (backed by Redis, scoped per extension) instead.

## Dev mode setup

### Build both apps

`just dev-supervisor` / `just dev-runtime` serve the already-built `dist/` directories, so build first:

```bash
pnpm --filter @lumio/extension-supervisor build
pnpm --filter @lumio/extension-runtime build
```

Each build runs tsup and copies `index.html` + `style.css` into `dist/`; the Runtime build also builds the SDK Worker and copies it to `dist/lumio-runtime.js`. With no `ALLOWED_*` env vars set, the build bakes in the defaults from `tsup.config.ts`, which already include `http://localhost:3200` / `http://localhost:3201` / `http://localhost:4000`.

### Run both apps

```bash
# Terminal 1
just dev-supervisor   # npx serve apps/extension-supervisor/dist -l 3200 --cors

# Terminal 2
just dev-runtime      # npx serve apps/extension-runtime/dist -l 3201 --cors
```

### Configure the web app

The webapp reads these env vars:

```
LUMIO_SUPERVISOR_URL=http://localhost:3200
LUMIO_EXTENSION_RUNTIME_URL=http://localhost:3201
# LUMIO_EXTENSION_RUNTIME_ORIGIN_TEMPLATE=https://{label}.lumio.ext.staging.zaflun.dev
```

The web server resolves them per request in `apps/web/src/lib/config.ts` (`getSupervisorUrl()`, `getExtensionRuntimeUrl()`, `getExtensionRuntimeOriginTemplate()`, together `getExtensionHostConfig()`). Each name falls back to its `NEXT_PUBLIC_*` twin (`NEXT_PUBLIC_SUPERVISOR_URL`, `NEXT_PUBLIC_EXTENSION_RUNTIME_URL`, `NEXT_PUBLIC_EXTENSION_RUNTIME_ORIGIN_TEMPLATE`), and empty values count as unset. The layouts of the dashboard, the fullscreen editors, overlays/widgets and popouts pass the result to client components through `ExtensionHostConfigProvider` (`apps/web/src/contexts/extension-host-context.tsx`); `ExtensionWorkerManager` reads it with `useExtensionHostConfig()`, never from `process.env`. The CSP `frame-src` takes the supervisor from the same chain. A deployed container therefore picks up a changed value on restart, without a rebuild.

`LUMIO_EXTENSION_RUNTIME_ORIGIN_TEMPLATE` gives every extension its own runtime origin. The Host builds it in `apps/web/src/lib/extension-runtime.ts` with `extensionRuntimeOrigin()` from `@zaflun/lumio-protocol/origin`, the same helper the Supervisor checks `extensionUrl` with: `{label}` becomes the extension id as 32 lowercase hex characters. When the template is set but no origin can be built (invalid template or extension id), the Host does not fall back to the shared origin; `ExtensionWorkerManager` reports `INVALID_RUNTIME_ORIGIN` and loads nothing. When the template is unset, every extension shares `LUMIO_EXTENSION_RUNTIME_URL` - the behaviour from before per-extension origins, kept as the rollback switch while the Supervisor and Runtime still accept the legacy shared origin.

The fallbacks are `http://localhost:3200` / `http://localhost:3201`, **not** the production URLs - a deployed environment that leaves them unset points its extension iframes at localhost. Set them explicitly in every deployed environment, as `LUMIO_*` names in the container env. The `NEXT_PUBLIC_*` fallbacks only take effect when they are present at `next build`, and the release image is built without build args.

### Start the full dev stack

```bash
just stack-up         # PostgreSQL, TimescaleDB, Redis, RabbitMQ, Kafka
just run-api          # Rust API
just dev-web          # Next.js web app
just dev-supervisor   # Extension Supervisor
just dev-runtime      # Extension Runtime
```

## Troubleshooting

### Message not forwarded (blocked by Supervisor)

The Supervisor logs a warning:

```
[Supervisor] Blocked worker→host message: some.unknown.method
[Supervisor] Blocked host→worker message: some.unknown.method
```

Solution: add the method to the appropriate set in `apps/extension-supervisor/src/supervisor.ts`, rebuild, and redeploy the Supervisor.

### Extension iframe does not load

1. Verify `LUMIO_SUPERVISOR_URL`, `LUMIO_EXTENSION_RUNTIME_URL` and `LUMIO_EXTENSION_RUNTIME_ORIGIN_TEMPLATE` are set correctly in the web container's environment. With a template, the Supervisor must have been built with the same template, or it refuses the frame with `EXTENSION_ORIGIN_MISMATCH`.
2. Check that the CF Pages project exists and has the correct custom domain configured, and that the label host resolves and is routed to the environment's Runtime Worker (`curl -sI https://<label>.<runtime host>/` answers `200`).
3. In local dev, confirm `just dev-supervisor` and `just dev-runtime` are running.
4. Check browser DevTools → Console for CORS errors. The static apps must send `Access-Control-Allow-Origin` headers - CF Pages does this by default.

### Worker fails to start

The Extension Runtime sends a `ui.error` JSON-RPC notification when the Worker cannot be created:

```json
{ "jsonrpc": "2.0", "method": "ui.error", "params": { "code": "WORKER_CREATE_FAILED", "message": "..." } }
```

The Host's `ExtensionWorkerManager` surfaces this via the `onError` callback. Common causes:
- The `runtimeUrl` is unreachable or blocked by CSP. The Host builds it as `<runtime origin>/lumio-runtime.js`, where the runtime origin is the extension's own origin from `LUMIO_EXTENSION_RUNTIME_ORIGIN_TEMPLATE` or, without a template, `LUMIO_EXTENSION_RUNTIME_URL`; that bundle is produced by `packages/sdk` (`tsup.runtime.ts`, entry `src/runtime/worker-entry.ts`), copied into the Runtime's `dist/` by its `build` script, and must be served from the Extension Runtime origin as JavaScript. `curl -sI <runtime origin>/lumio-runtime.js` must report `content-type: application/javascript`; `text/html` means the file is missing and Pages served `index.html`; on a label host a missing file answers `404`.
- `BUNDLE_EVAL_FAILED` with a CSP message about `'unsafe-eval'`: the Worker was served with the page policy instead of its own. Check the `/lumio-runtime.js` rule in the generated `dist/_headers`.
- The Worker script fails to parse (syntax error in extension bundle).

Inspect the Extension Runtime iframe's console for more details (use the context switcher in Chrome DevTools).

### Supervisor not ready (lifecycle.init never sent)

`ExtensionWorkerManager` waits for `{ type: "supervisor", status: "loaded" }` before sending `{ type: "init", ... }`. If the Supervisor iframe fails to load at all, the loaded signal is never emitted and the extension stays in a pending state.

Check:
- Network tab in DevTools shows the Supervisor URL loading successfully (HTTP 200).
- No CSP or mixed-content errors block the iframe.

---

## Developer Guide / Web Content-Security-Policy

Source: https://docs.lumio.vision/developer-guide/web-content-security-policy

# Web Content-Security-Policy

The webapp (`apps/web`) sets an **application-level Content-Security-Policy** on
every response as **defense-in-depth on top of** the CSP already applied at the
Cloudflare edge for the production `lumio.vision` surfaces. The app layer does
not trust the edge alone (Zero Trust): if the origin is ever reached without the
edge in front of it, the app still ships a policy.

## Report-Only first

The policy is currently emitted under the **`Content-Security-Policy-Report-Only`**
header, not the enforcing `Content-Security-Policy` header. In Report-Only mode
the browser **blocks nothing**; it only sends a violation report whenever the
policy *would* have blocked a resource. This lets us inventory exactly which
sources real traffic needs - across the dashboard, marketing, auth, overlay,
popout and widget surfaces - before anything is enforced.

Do **not** flip the header to the enforcing name until the reports have been
triaged and the directives calibrated.

## Where it lives

| Concern | File |
|---------|------|
| Directive builder | `apps/web/src/lib/csp.ts` (`buildContentSecurityPolicy()`) |
| Header wiring | `apps/web/src/proxy.ts` (`withCspHeaders()`, request time - every response branch) |
| Report collector (sanitises + forwards) | `apps/web/src/app/api/csp-report/route.ts` |
| Public-route allowlist for the collector | `apps/web/src/proxy.ts` (`PUBLIC_API_PREFIXES`) |
| API ingest (public, fail-open) | `apps/api/src/routes/csp_reports.rs` (`POST /v1/csp-report-ingest`) |
| Persistence (capped aggregate) | `csp_violation_reports` in TimescaleDB (`apps/api/tsdb_migrations/20260904000001_create_csp_violation_reports`) |
| Read surface (admin RBAC) | GraphQL `cspViolationReports` / REST `GET /v1/admin/csp-reports` (`csp-reports:read`) |
| Regression tests | `apps/web/__tests__/csp.test.ts`, `apps/web/__tests__/csp-report-safe-host.test.ts`, `apps/api/tests/csp_reports.rs` |
| Deployed-header smoke gate | `scripts/check-deployed-csp.mjs`, `.github/workflows/deployed-csp-check.yml` |

## Static SVGs under `/passkey-providers/`

The proxy's `config.matcher` skips static `.svg` files, so the request-time policy above never reaches
them. The passkey provider logos come from a community-maintained list, and a logo opened as a
top-level document would otherwise run with no policy on our origin. `apps/web/next.config.ts`
`headers()` therefore sets an **enforcing** policy and `X-Content-Type-Options: nosniff` on
`/passkey-providers/:path*`:

```text
Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox
```

This is the same policy the API sends for SVG extension uploads. `style-src 'unsafe-inline'` lets
the logos that use `<style>` render when opened directly; `<img>` rendering is unaffected. The values
are static, so freezing them at `next build` is harmless. `apps/web/__tests__/next-config-headers.test.ts`
guards the entry.

## Directives

`proxy.ts` calls `buildContentSecurityPolicy()` on **every request**, so the
origin-specific directives come from the container's runtime env, not from the
build. `NEXT_PUBLIC_*` names are inlined at `next build` and the release images
are built without build args, so in a deployed container only the server-side
`LUMIO_*` names (`LUMIO_PUBLIC_API_URL`, `LUMIO_WS_URL`, `LUMIO_ID_URL`,
`LUMIO_APP_URL`, `LUMIO_OVERLAY_URL`, `LUMIO_SUPERVISOR_URL`) actually drive
the policy. The API HTTP and
WebSocket origins fall back to `http://localhost:3000/v1` - see the
`connect-src` table below.

### `connect-src` - API HTTP + WebSocket origins

`connect-src` must allow the origins the browser actually talks to: `'self'`,
the API over HTTP **and** its WebSocket, the ID/app/overlay origins, the
extension supervisor, and the Sentry ingest. The API HTTP and WebSocket
origins are resolved through the **same** helpers the runtime connects with —
`getPublicApiOrigin()` and `getWsOrigin()` in `apps/web/src/lib/config.ts` - so
the origin the app opens a socket to and the origin the policy allows can never
drift apart:

| Origin in `connect-src` | Resolution chain (first match wins) |
|-------------------------|-------------------------------------|
| API HTTP | `LUMIO_PUBLIC_API_URL` → `NEXT_PUBLIC_API_URL` → `LUMIO_API_URL` → `http://localhost:3000/v1` |
| API WebSocket | `LUMIO_WS_URL` (bare host) → derived from the API HTTP origin (`http`→`ws`, `https`→`wss`) |
| ID app | `NEXT_PUBLIC_ID_URL` → `LUMIO_ID_URL` |
| This app | `NEXT_PUBLIC_APP_URL` → `LUMIO_APP_URL` |
| Overlay | `NEXT_PUBLIC_OVERLAY_URL` → `LUMIO_OVERLAY_URL` |
| Extension supervisor | `LUMIO_SUPERVISOR_URL` → `NEXT_PUBLIC_SUPERVISOR_URL` (`getConfiguredSupervisorUrl()`, the same chain the layouts hand to the framing components; unset adds no source) |
| Sentry | `LUMIO_PUBLIC_SENTRY_DSN` → `NEXT_PUBLIC_SENTRY_DSN` (`getBrowserSentryConfig()`, the same getter the root layout hands to the browser SDK; unset adds no source) |

> **Sentry and analytics.** The browser Sentry SDK gets its DSN from the same
> request-time getter as the policy, so the two always agree: a container
> without `LUMIO_PUBLIC_SENTRY_DSN` has an inert browser SDK (no ingest requests)
> and no Sentry origin in `connect-src`; a container with it gets both. The
> server-only `SENTRY_DSN` is used by server/edge Sentry and never needs a
> browser allowance. The webapp mounts no analytics script, so `connect-src`
> and `script-src` carry no analytics host.

> **One resolver, no guessing (ZAF-1194).** The CSP does **not** re-derive these
> origins from its own env-var list; it calls the exact `getPublicApiOrigin()` /
> `getWsOrigin()` helpers the runtime opens sockets with. `LUMIO_API_URL` sits
> **last** in the HTTP chain on purpose: in local dev the API is configured
> through it alone (the documented `.env.example` sets no `NEXT_PUBLIC_API_URL`),
> so it must resolve the origin there - but in staging/prod it is the **internal**
> Docker host, and a public name always wins ahead of it, so the internal host
> never reaches a browser origin or `connect-src`. Two separate derivation paths
> for the same URL were the root cause of the origin dropping out of the policy.

Only the **origin** (scheme+host+port) of these values reaches `connect-src` —
`connect-src` matches on origin, so the `/v1` API-version prefix that
`NEXT_PUBLIC_API_URL` carries (see below) is stripped by `getPublicApiOrigin()`
and never appears in the policy.

The `http://localhost:3000/v1` fallback means a fresh local checkout with no API
env var set at all still gets a correct `connect-src` - matching the WebSocket the
app opens by default. In practice the documented `.env.example` sets
`LUMIO_API_URL=http://localhost:3000/v1` (the local API config), and because that
name is the last link in the HTTP chain above, the origin resolves from the value
the app actually connects to rather than from the hardcoded default.

> **The `/v1` prefix lives in the env, not in code.** `NEXT_PUBLIC_API_URL`
> carries the `/v1` API-version segment (in `.env.example`, in the deployed
> per-environment images, and in the code fallback). WebSocket URLs are built by
> `wsUrlFromApiUrl()` in `apps/web/src/lib/config.ts`, which swaps the scheme and
> appends only the WS-specific `/ws` suffix - so a base already carrying `/v1`
> becomes `…/v1/ws` and is **never** doubled to `/v1/v1/ws`. Every WS hook shares
> that one helper. The lone exception is the bare `LUMIO_WS_URL` host (no path),
> where `getWsUrl()` appends the full `/v1/ws`.

Static third-party allowances that are **not** env-derived:

- **`img-src`** - `*.giphy.com` (Twitch GIFs, see below), the emote CDNs
  (`cdn.7tv.app`, `cdn.betterttv.net`, `cdn.frankerfacez.com`,
  `static-cdn.jtvnw.net`), Twitch cheermotes (`d3aqoihi2n8ty8.cloudfront.net`),
  Kick (`files.kick.com`, `ext.cdn.kick.com`), the platform avatar CDNs
  (`cdn.discordapp.com`, `lh3.googleusercontent.com`, `yt3.ggpht.com` for
  YouTube avatars and member badges, `yt4.ggpht.com` for YouTube chat author
  photos), Spotify album art (`i.scdn.co`), the test-event avatars and album art
  (`api.dicebear.com`, from `apps/web/src/lib/test-events.ts`), plus `data:` /
  `blob:`. `i.ytimg.com` (YouTube video thumbnails) is **not** allowed: no code
  path in the webapp renders a video thumbnail.
- **`frame-src`** - the Cloudflare Turnstile challenge origin
  (`challenges.cloudflare.com`) plus the extension supervisor and overlay
  origins. No Twitch, YouTube or Spotify player host is allowed: the webapp
  frames no player and only links to those sites. No extension runtime origin appears in the
  policy: every extension runs on its own runtime origin, and that frame is
  nested inside the supervisor, so the supervisor's own `frame-src` governs it.
  The webapp never frames, fetches or connects to a runtime origin - it fetches
  the bundle through its own proxy and talks to the extension only through
  `postMessage` to the supervisor.
- **`script-src`** - `'self' 'unsafe-inline'`. Next.js injects inline
  bootstrap/hydration scripts; keeping `'unsafe-inline'` in the Report-Only phase
  means the reports surface genuinely-external loads rather than drowning in
  framework inlines. It does **not** survive the flip: the enforcing policy needs
  a per-request nonce plus `'strict-dynamic'` emitted from `proxy.ts`, and no
  `'unsafe-inline'`.
- **`style-src`** - `'self' 'unsafe-inline'` plus the API origin, which serves
  the self-hosted font stylesheets. `'unsafe-inline'` here is an **accepted
  risk** (see below) and stays when the policy enforces.
- **`font-src`** - `'self' data:` plus the API origin. Web fonts are
  **self-hosted** through the API font proxy and never loaded from Google Fonts
  directly (see below).
- **`media-src`** - left open (`'self' data: blob: https:`) because overlay and
  widget surfaces play user-supplied alert media from arbitrary hosts.

### Fonts are self-hosted

The UI typeface, Roboto, is part of each app's own build: every root layout of
`apps/web`, `apps/admin`, `apps/id` and `apps/stats` loads it with
`next/font/local` from the pinned npm package `@fontsource-variable/roboto`, and
Next.js serves the WOFF2 files from `/_next/static/media/` on the app's origin.
`font-src 'self'` covers them; no app needs a font host in its policy for the UI
typeface (see [Dashboard UI Primitives](./frontend-ui-primitives.md#typeface)).

The overlay root layout (Montserrat) and the extension font picker load fonts
through the API font proxy: `GET /v1/fonts/{family}/css` returns `@font-face`
rules whose `src` points at `GET /v1/fonts/{family}/{weight}.woff2` on the API
origin, and the API fetches each WOFF2 from Google once and serves it from its
own storage. The dashboard font picker reaches the CSS through the same-origin
`/api/fonts/{family}/css` route; the overlay links the API URL directly, because
OBS browser sources carry no session cookie. The browser therefore never
contacts `fonts.googleapis.com` or `fonts.gstatic.com`: the policy needs no
Google host, and no viewer IP reaches Google from a stream overlay. If a family
cannot be loaded, the picker shows its name unstyled; there is no Google
fallback.

### Accepted risk: `style-src 'unsafe-inline'`

The enforcing policy keeps `style-src 'unsafe-inline'` (CIO decision, ZAF-995).
React and Next.js emit inline `style=` attributes throughout the app, so style
nonces are impractical. Style injection cannot execute code; its residual risk is
CSS-based UI redress or attribute exfiltration, which the locked `script-src`,
`connect-src` and `img-src` allowlists bound. `script-src` gets no such
exception.

Baseline lock-downs: `default-src 'self'`, `object-src 'none'`, `base-uri 'self'`,
`frame-ancestors 'self'`, `form-action 'self' <id-origin>`.

> **Hard constraint (ZAF-957):** `img-src` **must** keep `*.giphy.com`. Twitch's
> GIF URLs may not be rewritten or proxied, so a policy that blocks the GIPHY
> host would break the GIF feature the moment it is enforced. The regression test
> pins this.

## Deployed-header smoke gate

The `connect-src` fallbacks above are correct for local dev - and the unit tests
assert them - so no unit test can notice when one of them reaches a real
deploy. Staging once shipped `connect-src 'self' http://localhost:3000
ws://localhost:3000` because its deploy env lacked `LUMIO_PUBLIC_API_URL`
(ZAF-1311 / ZAF-1312). `scripts/check-deployed-csp.mjs` checks the header the
**deployed** origin actually sends:

- It fetches the page and reads `Content-Security-Policy` and
  `Content-Security-Policy-Report-Only` (whichever are present; neither is a
  failure).
- **Fails** if any source-list directive carries a non-public origin:
  `localhost`, a loopback / private / link-local IP, a dot-less internal Docker
  host such as `staging-api:3000`, or a plaintext `http:` / `ws:` origin.
- **Fails** if `connect-src` lacks the environment's public API origin over both
  `https://` and `wss://` (`lumio.api.staging.zaflun.dev` for staging,
  `api.lumio.vision` for production).

```sh
node scripts/check-deployed-csp.mjs --target staging   # after a staging deploy
node scripts/check-deployed-csp.mjs --target prod
node scripts/check-deployed-csp.mjs --url <origin> --expect-api <https://api-origin>
node scripts/check-deployed-csp.mjs --self-test        # synthetic leaks, no network
```

The **Deployed CSP Check** workflow runs it daily against staging and alerts the
security Discord channel when it fails. You can also start it by hand
(`workflow_dispatch`, target `staging` or `prod`) right after a deploy. On PRs
that touch the checker it runs only the self-test, so a broken staging never
blocks an unrelated PR. Production is checked on demand only for now, because
the production web origin does not yet serve the app CSP. When `apps/admin` or
`apps/id` get a CSP, add their origins as targets in the script.

## Violation reports

`report-uri` and `report-to` both point at `/api/csp-report`
(`Reporting-Endpoints: csp="/api/csp-report"`). The collector:

- is **public** (unauthenticated / cross-origin beacons from marketing, overlay
  and widget browsers must reach it - see `PUBLIC_API_PREFIXES`);
- **caps** the accepted body (`16 KiB`) so it can't be used to flood logs;
- **sanitises to two bounded fields** - `violated_directive` and the
  **scheme+host** of `blocked-uri` (`safeHost()`), dropping path, query and
  fragment so a `?token=lm_…` on a widget/popout page - and the path itself, a
  residual viewer-identity leak - can never be stored or logged;
- logs a bounded, host-only summary (`blocked_host`, `violated_directive`,
  `document_host`, `disposition`) at `warn`;
- **forwards** the two sanitised fields to the Rust API
  (`POST /v1/csp-report-ingest`, public) and returns `204`. The forward is
  **fail-open**: a backend failure never changes the `204` the beacon expects.

The API ingest handler (`apps/api/src/routes/csp_reports.rs`) is unauthenticated
(mirrors `abuse-reports`; the anonymous rate-limit bucket on `CF-Connecting-IP`
covers it) and **re-sanitises server-side** (never trust the forwarder):
`violated_directive` is folded to the known CSP directive set (else `<other>`)
and `blocked_host` to `scheme://host` / bare `scheme:` / a CSP keyword (else
`<other>`). It then records the pair into the capped **`csp_violation_reports`**
TimescaleDB aggregate - distinct `(violated_directive, blocked_host)` pairs with
`report_count` + `first_seen`/`last_seen`, hard-capped at **5000 distinct pairs**
(new pairs beyond the cap fold into a single `<capped>` overflow row, so
`blocked_host` - attacker-influenceable on overlay/widget surfaces - cannot
exhaust storage) and pruned on a **rolling ≤30 day** always-on daily job. The
whole path is fail-open (a DB or metric failure still returns `204`).

Because `blocked_host` is host-only (no viewer identity), the rows are **not
personal data**, so the retention job is a flat `DELETE` (contrast
`audit_events`, which is anonymised at 12 months before its rows are deleted
at 24).

**Reading the signal.** Operators with the admin-scope **`csp-reports:read`**
permission query the aggregate through the admin app: GraphQL
`cspViolationReports(limit, orderBy)` (primary) or REST
`GET /v1/admin/csp-reports?limit=…&order_by=…` (twin) - same guard, same fields,
same errors. This is the calibration surface; there is **no** new standing
prod-log or shell grant (CIO least-privilege ruling, ZAF-1050).

**Ops (optional).** The ingest handler also increments
`csp_violations_total{violated_directive}` on the internal `/metrics`
(`violated_directive` is the only label - bounded; the host dimension is
deliberately absent, per the `lo-metrics` cardinality rule). It gives an
at-a-glance breakage rate but is **not** the calibration path (no host).

Threat note: the public ingest lets an attacker POST fake `directive`/`host`
pairs, polluting the calibration signal - **low severity** (a calibration aid,
not a security control), bounded by the rate limit, the 5000-pair cap, the ≤30 d
retention, and host sanitisation. Documented and accepted (ZAF-1051).

## Enforce-flip checklist (later)

1. Triage the collected reports through the query - GraphQL `cspViolationReports`
   or REST `GET /v1/admin/csp-reports` (needs `csp-reports:read`), ordered by
   `report_count` - to see which `(violated_directive, blocked_host)` pairs
   actually fire, and separate the bounded app hosts to allowlist from the
   arbitrary-content overlay/widget hosts. (No raw prod-log grep - that surface
   was the whole reason for ZAF-1050.)
2. Replace `script-src` `'unsafe-inline'` with a per-request nonce plus
   `'strict-dynamic'`, emitted from `proxy.ts` (ZAF-996). `style-src
   'unsafe-inline'` stays (accepted risk, above).
3. Decide the framing policy for overlay/widget embedding before enforcing
   `frame-ancestors`.
4. Rename the header from `Content-Security-Policy-Report-Only` to
   `Content-Security-Policy`.
5. Re-tighten `apps/web/content/{en,de}/legal/security.mdx` once the app-side
   claim is actually true.

Parity: if the CSP is later rolled out to `apps/admin` / `apps/id`, apply the
same Report-Only-first discipline there.

---

## Developer Guide / Extension Sounds

Source: https://docs.lumio.vision/developer-guide/extension-sounds

# Extension Sounds

Extensions can bundle audio files that are automatically added to the user's sound library when the extension is installed. Bundled sounds are managed by the extension developer - users cannot delete or rename them.

The [data design standard](./data-design.md) covers object keys, metadata,
access, and deletion for new stored asset types.

## Declaring sounds

Add a `sounds` array to `lumio.config.json`:

```json
{
  "sounds": [
    { "file": "alert.mp3", "name": "Alert" },
    { "file": "chime.wav", "name": "Chime", "default_volume": 0.8 }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | string | yes | Relative path in `dist/sounds/`. 1-255 characters. No `..`, `\`, or leading `/`. |
| `name` | string | yes | Display name shown in the Sounds Panel. 1-255 characters. |
| `default_volume` | number | no | Default playback volume, 0.0 to 1.0. |

### Supported formats

MP3, WAV, OGG, WebM, M4A, AAC, FLAC.

Place audio files in `dist/sounds/` before running `lumio deploy`.

## Limits

The `sounds` array in `lumio.config.json` is capped at **200 entries** by the schema itself (`packages/extension-types/src/config.ts`) - a longer array fails config validation before any limit lookup happens.

The effective per-extension limit is resolved by `resolve_max_sounds()` in this order, first hit wins:

1. **Per-extension override** - `extensions.max_sounds` (reason `extension_override`)
2. **Per-developer override** - `developer_limit_overrides` row with `limit_key = 'max_sounds_per_extension'` (reason `developer_override`)
3. **Default** - `DEFAULT_MAX_SOUNDS_PER_EXTENSION = 50` (reason `default`)

An admin-set override is validated to `0..=500`.

Two further limits apply alongside the count: `max_sound_file_size` (per file) and `max_sound_storage_bytes` (total across the extension's sounds). The `lumio deploy` CLI pre-flights all three against the resolved values from the API and fails the deploy with a descriptive message before uploading. It also warns on any single sound file over 5 MB. Request a limit increase via the Developer Dashboard or contact support.

System extensions bypass all sound limits (`skip_limits` in `bundled_sounds.rs`).

## Lifecycle

| Event | Behavior |
|-------|----------|
| Extension installed | Sound rows created in the user's library |
| Extension uninstalled | Sound rows removed from the library |
| Extension version updated | Sounds reconciled (old removed, new created) |
| User tries to delete bundled sound | Blocked with error message |
| User tries to rename bundled sound | Blocked with error message |

Bundled sounds do not count against the account's plan sound limit (e.g. Free plan max 10 sounds): a bundled row carries `source_extension_id = {extension_id}`, and the plan-limit queries filter on `source_extension_id IS NULL`.

## How storage works

Sound files are uploaded once during `lumio deploy` to extension storage under `{ext_id}/versions/{ver}/sounds/{file}` (`ExtensionStorageKeys::file_key`). When a user installs the extension, the API creates database rows that reference these storage keys directly. No file duplication occurs - all installs share the same uploaded files.

## Referencing sounds in config

Use a config field of type `sound` to let users select from their sound library (including bundled sounds):

```json
{
  "config_schema": [
    {
      "key": "alertSound",
      "type": "sound",
      "label": "Alert Sound"
    }
  ]
}
```

The SchemaEditor renders a dropdown picker. The stored value is a sound ID (UUID string).

## Key files

| Path | Description |
|------|-------------|
| `packages/extension-types/src/config.ts` | Sound schema definition (`lumioExtensionSoundSchema`) |
| `apps/api/src/services/bundled_sounds.rs` | Install/reconcile logic |
| `apps/api/src/db/developer_extensions.rs` | `resolve_max_sounds` limit resolution |
| `packages/cli/src/commands/deploy.ts` | CLI sound validation and limit check |

---

## Developer Guide / YouTube API Quota

Source: https://docs.lumio.vision/developer-guide/youtube-api-quota

# YouTube API Quota

Lumio uses **InnerTube** - YouTube's own internal API - as the primary transport for chat reception and broadcast discovery. InnerTube costs **0 Data API quota**. The YouTube Data API v3 resolves the `liveChatId` of newly discovered broadcasts, and is also used for chat sending, moderation, channel-info lookup at connection time, and the disabled-by-default REST polling fallback.

The YouTube Data API v3 enforces a daily quota of **10,000 units per project** (resets at midnight Pacific Time).

## Transport Overview

| Transport | Purpose | Quota Cost |
|-----------|---------|------------|
| **InnerTube** (primary) | Chat polling, broadcast discovery, badge/emote enrichment, statistics (likes, views) | **0** |
| **gRPC streamList** (fallback 1) | Chat reception via persistent server-push connection | **0** |
| **REST Data API v3** (fallback 2) | Chat polling when InnerTube and gRPC both fail | **5 units per poll** |

Fallback cascade: InnerTube → gRPC (if `grpc_fallback_enabled`) → REST (if `rest_fallback_enabled`). Each transition triggers after 3 consecutive failures within 60 seconds. Both fallbacks are **disabled by default**.

## Quota Cost Reference

Official costs per YouTube Data API v3 operation:

| Operation | Endpoint | Cost (units) |
|-----------|----------|-------------|
| List broadcasts | `liveBroadcasts.list` | 1 |
| List chat messages | `liveChatMessages.list` | 5 |
| Send chat message | `liveChatMessages.insert` | 200 |
| List channels | `channels.list` | 1 |
| List videos | `videos.list` | 1 |
| Search | `search.list` | 100 |
| List subscriptions | `subscriptions.list` | 1 |
| Transition broadcast | `liveBroadcasts.transition` | 50 |

The default daily limit is **10,000 units**. Higher limits require passing Google's [Quota and Compliance Audit](https://support.google.com/youtube/contact/yt_api_form).

## Quota-Free Operations (InnerTube + gRPC)

These operations cost **0 Data API quota**:

| Operation | Transport | Source |
|-----------|-----------|--------|
| **Chat polling** | InnerTube `get_live_chat` | `crates/lo-youtube-api/src/innertube/mod.rs` |
| **Broadcast discovery** | InnerTube `browse` | `crates/lo-youtube-api/src/innertube/browse.rs` |
| **Badge + emote enrichment** | InnerTube (inline in chat responses) | `crates/lo-youtube-api/src/innertube/parser.rs` |
| **Like count + view count** | InnerTube `updated_metadata` / `player` | `crates/lo-youtube-api/src/innertube/browse.rs` |
| **Like count + view count (fallback)** | Public channel Atom feed `videos.xml` (`media:community`) | `crates/lo-youtube-api/src/webhook.rs` |
| **Chat streaming (fallback)** | gRPC `liveChatMessages.streamList` | `crates/lo-youtube-api/src/streaming.rs` |

InnerTube is unauthenticated - no OAuth token required for chat reception. The channel Atom feed is likewise unauthenticated, but is edge-cached for 15 minutes, so it is fetched at most once per channel per 15 minutes and only for values InnerTube did not deliver. See [Broadcast Statistics](../features/youtube-streaming.md#broadcast-statistics).

### Broadcast Discovery (Quota-Free)

The InnerTube `browse` request reads a channel's public **Streams** tab. Current entries use `lockupViewModel`: a `…_LIVE` badge style identifies a live broadcast, while badge text `Upcoming` identifies a scheduled one. The request pins `hl=en` so the badge text is stable and sets `timeZone=UTC` and `utcOffsetMinutes=0` so the `Scheduled for …` time can be parsed as UTC. A legacy `videoRenderer` parser remains as a fallback. InnerTube returns the video ID, title, and available status metadata, but no `liveChatId`.

Only **public** streams appear in this discovery path. Unlisted and private broadcasts are not discovered through the public Streams tab.

### liveChatId Resolution (Data API v3)

| Aspect | Details |
|--------|---------|
| **Endpoint** | `liveBroadcasts.list?part=snippet,status&id=…&maxResults=50` |
| **Cost** | **1 unit per call**, with up to 50 video IDs per call |
| **Frequency** | On discovery when a broadcast has no known chat ID; unresolved IDs are retried after at least 10 minutes |
| **Source** | `crates/lo-youtube-api/src/client.rs` `get_broadcasts_by_id()` and `apps/api/src/workers/youtube.rs` |

The worker reuses known chat IDs from tracked streams or `channel_status`. For an unknown ID, it calls the Data API with the connected channel's OAuth token. `snippet.scheduledStartTime`, when returned, takes precedence over the time parsed from the Streams tab. An upcoming broadcast without a chat ID still appears on the dashboard, but it has no chat reader task and does not appear in the Multichat broadcast dropdown until the ID resolves. A live broadcast without a chat ID waits for resolution. A failed lookup leaves broadcasts with known IDs available; quota errors pause further lookups for five minutes, and other API errors for one discovery interval (60 seconds).

The live-chat embed page is still used to bootstrap an InnerTube **chat continuation token** after a chat ID is known. It is not the source of the `liveChatId`.

## Quota-Consuming Operations (Data API v3)

### Chat Sending + Moderation

| Operation | Endpoint | Cost | Frequency | Source |
|-----------|----------|------|-----------|--------|
| Send chat message | `POST /liveChat/messages` | 200 | Per message sent | `apps/api/src/services/chat_send.rs` |
| Ban / timeout user | `POST /liveChat/bans` | 200 | Per action | `apps/api/src/services/moderation.rs` |
| Delete message | `DELETE /liveChat/messages` | 200 | Per action | `apps/api/src/services/moderation.rs` |

These use the account's Google login OAuth connection (`db::auth::get_account_provider_token`), not the channel connection.

### Channel Info Lookup

| Aspect | Details |
|--------|---------|
| **Endpoint** | `channels.list` |
| **Cost** | 1 unit |
| **Source** | `apps/api/src/routes/connections.rs` `fetch_channel_info()` |
| **Trigger** | Once per YouTube channel connection (OAuth callback) |
| **Daily Units** | Negligible (< 10) |

### REST Fallback (Disabled by Default)

Broadcast discovery through the Data API runs when `rest_fallback_enabled = true` and InnerTube browse fails. REST chat polling is the last transport after the enabled InnerTube and gRPC tiers fail:

| Operation | Endpoint | Cost | Interval |
|-----------|----------|------|----------|
| Broadcast discovery | `liveBroadcasts.list` | At least 2 (one page each for `active` and `upcoming`) | Every 60 s; more for additional pages |
| Chat polling | `liveChatMessages.list` | 5 | ~10 s active / 30 s idle |

| Caller | File | Daily Units (per channel, one page per broadcast status) |
|--------|------|---------------------------------------|
| YouTube Worker (broadcast poll) | `apps/api/src/workers/youtube.rs` | At least 2,880 |
| YouTube Worker (chat poll) | `apps/api/src/workers/youtube.rs` | up to 43,200 |

## Configuration

```toml
[youtube]
# Enable gRPC streamList as first fallback when InnerTube fails
# ENV: LUMIO__YOUTUBE__GRPC_FALLBACK_ENABLED
grpc_fallback_enabled = false  # default

# Enable REST polling as last resort when InnerTube + gRPC both fail
# Also gates Data API broadcast discovery fallback
# ENV: LUMIO__YOUTUBE__REST_FALLBACK_ENABLED
rest_fallback_enabled = false  # default
```

## Daily Quota Calculator

### Default Mode (InnerTube Only)

With both fallbacks disabled (default), quota consumption is minimal:

**Per active channel (stream is live):**

| Component | Quota per call | Calls | Quota |
|-----------|---------------|-------|-------|
| InnerTube chat polling | 0 | ~28,800/day (3 s interval) | 0 |
| InnerTube broadcast discovery | 0 | 1,440/day (60 s interval) | 0 |
| InnerTube statistics | 0 | 1,440/day (60 s interval) | 0 |
| liveChatId resolution (`liveBroadcasts.list?id=…`) | 1 per call | 1 call for up to 50 new IDs; unresolved IDs retry after at least 10 min | **1** for one resolved broadcast |
| **Total for one resolved broadcast** | | | **1** |

**Per idle channel (no stream):**

| Component | Quota per call | Calls | Quota |
|-----------|---------------|-------|-------|
| InnerTube broadcast discovery | 0 | 1,440/day | 0 |
| **Total** | | | **0** |

### Example: 1 Channel, 8h Stream (Default InnerTube Mode)

```
Idle hours (16h):                     0 units
Stream hours (8h):                    0 units
liveChatId resolution (once):         1 unit
                                ─────────
Total:                              1 unit / 10,000 limit
```

This example assumes the chat ID resolves on the first call. A broadcast without a chat ID may cost another unit on each retry after at least 10 minutes. Human actions also consume quota - sending a chat message (200), a ban/timeout (200), or a message delete (200) - as does the one-off `channels.list` at connection time (1).

### Example: 1 Channel, 8h Stream (REST Fallback Active)

```
Idle hours (16h):     16 *  120 =  1,920 units  (active + upcoming discovery)
Stream hours (8h):     8 * 1920 = 15,360 units  (discovery + chat polling)
                                ─────────
Total:                           17,280 units / 10,000 limit (173% -- OVER QUOTA)
```

This assumes one page for each broadcast status and a chat poll every 10 seconds. The fallback listing supplies the chat ID, so this continuous-fallback example has no separate ID lookup. REST fallback is disabled by default for this reason.

## Quota Safeguards

| Mechanism | Details |
|-----------|---------|
| **InnerTube primary** | 0 quota for all chat reception and broadcast discovery |
| **Detection** | HTTP 403 (REST) or `RESOURCE_EXHAUSTED` (gRPC) |
| **Backoff** | 5-minute pause on quota exhaustion (`QUOTA_BACKOFF_SECS = 300`) |
| **Fallback chain** | InnerTube → gRPC → REST (each after 3 failures in 60 s) |
| **REST toggle** | `rest_fallback_enabled = false` disables REST fallback entirely |
| **Shared cache** | Copyright Worker and Bot read broadcast status from Redis, not YouTube API |
| **Adaptive polling** | REST fallback respects `polling_interval_millis` from YouTube's response |

## Requesting Higher Quota

To request a quota increase from Google:

1. Pass the [Quota and Compliance Audit](https://support.google.com/youtube/contact/yt_api_form)
2. Demonstrate compliance with YouTube API Terms of Service
3. If previously audited within 12 months, use the Audited Developer Requests Form
4. There is no published maximum - increases are granted case-by-case

---

## Developer Guide / InnerTube Proxy

Source: https://docs.lumio.vision/developer-guide/innertube-proxy

# InnerTube Proxy

YouTube's InnerTube `player` and `updated_metadata` endpoints return `LOGIN_REQUIRED` from certain datacenter IPs. The InnerTube Proxy is a standalone Rust binary (Actix Web) that forwards these requests from a host with a trusted IP.

## Architecture

```
API Server (Hetzner) ── POST ──▶ Rust Proxy (Proxmox) ── POST ──▶ YouTube InnerTube
                                 innertube-proxy                    /youtubei/v1/*
                     ◀── Response ───────────────────── ◀── Response ──────────────
```

Only `player` (total views) and `updated_metadata` (like count) are proxied. Chat polling (`get_live_chat`) and broadcast discovery (`browse`) call YouTube directly - they work from datacenter IPs and are latency-sensitive.

## Why not a Cloudflare Worker?

The proxy **was** a Cloudflare Worker (`apps/innertube-proxy/src/index.ts` + `wrangler.toml` + `deploy-innertube-proxy.yml`). It was removed in `24dc5452` on 2026-05-22 and replaced by this Rust binary.

**Reason:** YouTube returns `LOGIN_REQUIRED` for the `player` endpoint from **Cloudflare Edge IPs** as well - not just from Hetzner Cloud and GitHub Actions/Azure. A Worker sits on exactly the kind of datacenter IP range this proxy exists to escape, so it cannot solve the problem it was built for. The trusted host (Proxmox) can reach the endpoint; Cloudflare cannot.

Do **not** reintroduce a Worker that calls `youtubei/v1/*` itself - it will return empty `total_views` / `like_count`. The only sound Cloudflare role here would be a **router in front of** one or more trusted-IP proxies (Cloudflare terminates TLS and forwards to a self-hosted backend, never fetching YouTube directly).

## Configuration

| Setting | ENV Override | Default | Description |
|---------|-------------|---------|-------------|
| `innertube_proxy_urls` | `LUMIO__YOUTUBE__INNERTUBE_PROXY_URLS` | `[]` | Proxy host list. The API fails over between entries by itself. ENV form is comma-separated (`https://a,https://b`). |
| `innertube_proxy_url` | `LUMIO__YOUTUBE__INNERTUBE_PROXY_URL` | unset | Back-compat single-host alias for `innertube_proxy_urls`. Folded into the host list (deduplicated) when set. |
| `innertube_proxy_token` | `LUMIO__YOUTUBE__INNERTUBE_PROXY_TOKEN` | unset | Shared bearer token for proxy auth - one token for every host. |

When at least one host **and** the token are set, the YouTube worker routes `player` and `updated_metadata` requests through the proxy pool. When no host is configured (local dev), requests go directly to YouTube. The two URL settings are additive: `innertube_proxy_urls` plus the single `innertube_proxy_url` alias are merged into one deduplicated host list, so existing single-URL deployments keep working unchanged.

## Proxy Routes

| Route | YouTube Target |
|-------|---------------|
| `POST /player` | `youtubei/v1/player` |
| `POST /updated-metadata` | `youtubei/v1/updated_metadata` |
| `GET /health` | Returns 200 (Docker healthcheck) |

The `api_key` query parameter is forwarded from the incoming request.

> **Route names are not YouTube path names:**
> The proxy route is `/updated-metadata` (**hyphen**); YouTube's own endpoint is `youtubei/v1/updated_metadata` (**underscore**). A client must resolve the path per transport - sending the hyphenated route straight to `youtube.com` returns 404 and silently leaves the like count empty. `InnerTubeEndpoint` in `crates/lo-youtube-api/src/innertube/browse.rs` holds both names, and tests on either side pin the mapping.

## Auth

The proxy validates `Authorization: Bearer {token}` against the `INNERTUBE_PROXY_TOKEN` env var. Invalid or missing tokens return 401.

## Operational metrics (Prometheus)

The proxy exposes the shared `lo-metrics` `/metrics` endpoint (ZAF-674). The bearer
check on `POST /player` lives in the handler, not as middleware, so `/metrics`
is **not** served on the public `LISTEN_ADDR` server (which the deployment publishes
on `3100`) - it would be unauthenticated there. Instead it runs on a **separate
internal server**:

| Env | Default | Description |
|-----|---------|-------------|
| `METRICS_ADDR` | `127.0.0.1:9100` | `host:port` for the internal `GET /metrics` server. Loopback by default. |

`9100` is the single dedicated metrics port shared by every service that runs a
separate metrics server (`apps/api`, both workers); it is collision-free because
each runs in its own container (ZAF-683). To scrape it, set `METRICS_ADDR` to an
internal address (e.g. `0.0.0.0:9100`) and publish **only** that port to the
Prometheus network - never fold it onto the public `3100`. The security is carried
by network isolation (an unpublished port), not the bind address. A bind failure is
fail-open: the proxy logs and keeps serving its payload routes. See
[Operational Metrics](./metrics.md).

## Logging and error tracking

The proxy has no TOML config. It reads its telemetry settings from env vars and hands them to the same `lo_telemetry::init_sentry` + `init_tracing` pair every Rust service uses, so its logs and Sentry events look like the API's:

| Env | Default | Description |
|-----|---------|-------------|
| `SENTRY_DSN` | unset | DSN of the Sentry project `innertube-proxy`. Unset or empty keeps Sentry off. |
| `SENTRY_ENVIRONMENT` | `production` | Sentry `environment` tag, also the `env` label on `/metrics`. |
| `RUST_LOG` | `info` | Log selection for stdout **and** Sentry. |

- **Events.** Every `warn!` / `error!` becomes a Sentry event (`[sentry] event_level = "warn"`), `info!` becomes a breadcrumb, `debug!` and `trace!` are dropped. Events carry `release = innertube-proxy@<version>`, the `service` tag and the shared fingerprint + per-fingerprint volume guard (10 events per 60 s). See [Error Tracking → Rust backend](./error-tracking.md). A `RUST_LOG` that hides a level hides it from Sentry too.
- **`SENTRY_ENVIRONMENT` defaults to `production`** because the proxy only runs on a trusted-IP host in front of a live API, never in a dev stack. A host that serves the staging API sets `SENTRY_ENVIRONMENT=staging`, otherwise its events are filed under `production`.
- **Stdout** is one JSON object per line. There is no diagnostics file.

## Deployment

The proxy runs as an OCI container built with Bazel:

```bash
# Build image
bazel build //apps/innertube-proxy:innertube-proxy_image

# Push to registry
bazel run --config=release //apps/innertube-proxy:innertube-proxy_push
```

Docker Compose. The image is pinned **by digest**, and only a digest that passed the release signature check is used (see [Deployment → Deploy-Side Signature Verification](./deployment.md#deploy-side-signature-verification)):

```bash
# From a lumio checkout: prints ghcr.io/zaflun/lumio/innertube-proxy@sha256:…, or refuses.
dev-stack/staging/verified-pull.sh verify innertube-proxy latest
```

```yaml
innertube-proxy:
  # The ref printed by `verified-pull.sh verify` - never a tag.
  image: ${INNERTUBE_PROXY_IMAGE:?set to the cosign-verified digest ref}
  environment:
    INNERTUBE_PROXY_TOKEN: "${INNERTUBE_PROXY_TOKEN}"
    LISTEN_ADDR: "0.0.0.0:3100"
    # Internal /metrics server. Bind 0.0.0.0 only if a scraper needs it, and then
    # expose 9100 solely on the trusted scraper network — never publish it publicly.
    METRICS_ADDR: "127.0.0.1:9100"
    RUST_LOG: "info"
    # Sentry project `innertube-proxy`; leave unset to keep Sentry off.
    SENTRY_DSN: "${INNERTUBE_PROXY_SENTRY_DSN:-}"
    SENTRY_ENVIRONMENT: "production"   # `staging` on a host that serves the staging API
  ports:
    # Public payload port only. `/metrics` (9100) is deliberately NOT published here.
    - "3100:3100"
  restart: unless-stopped
  healthcheck:
    test: ["CMD", "wget", "-q", "--spider", "http://localhost:3100/health"]
    interval: 30s
    timeout: 5s
    retries: 3
```

The API connects via Docker network: `LUMIO__YOUTUBE__INNERTUBE_PROXY_URLS=http://innertube-proxy:3100` (the singular `…_PROXY_URL` alias still works for existing single-host deployments).

### Image tags

`release-images.yml` publishes `ghcr.io/zaflun/lumio/innertube-proxy` on GitHub Release `published` (or via `workflow_dispatch`). Tags follow the release channel: a **pre-release** publishes `beta` (plus the version and SHA tags), a **full release** publishes `latest` and the `MAJOR.MINOR` tag. `latest` therefore only exists once a non-pre-release has been cut - pin an explicit version or SHA tag if you need a specific build.

### Running on multiple hosts

The API talks to the proxy pool **directly** and fails over between hosts by itself - **no** load balancer, router, or DNS trick in front. Configure every host in `innertube_proxy_urls` (`apps/api/src/config.rs`) and the API rotates across them:

```toml
[youtube]
innertube_proxy_urls = [
  "http://innertube-proxy-a:3100",
  "http://innertube-proxy-b:3100",
]
innertube_proxy_token = "…"   # one shared token for every host
```

or, ENV-only (comma-separated):

```
LUMIO__YOUTUBE__INNERTUBE_PROXY_URLS=http://innertube-proxy-a:3100,http://innertube-proxy-b:3100
LUMIO__YOUTUBE__INNERTUBE_PROXY_TOKEN=…
```

**Failover is passive and sticky** (`innertube_fetch_json` in `crates/lo-youtube-api/src/innertube/browse.rs`): each request starts at the last host that answered and rotates forward only when a host fails - on a transport error, a non-2xx status, or a `LOGIN_REQUIRED`-shaped body (the datacenter/edge IP-block signal the proxy exists to dodge). The host that answers becomes the new sticky start, so a dead host is skipped on subsequent calls **without** a background health-check loop or any extra config. With a single host configured the behaviour is identical to a one-URL deployment.

Every host must share the same `INNERTUBE_PROXY_TOKEN`, since the API sends one shared token to all of them. The single-host `innertube_proxy_url` alias still works and is merged (deduplicated) into the host list, so existing deployments need no change.

> A fronting layer (Cloudflare router, Caddy/nginx/HAProxy, DNS round-robin) is **not** used here - the failover is owned by the API. A Cloudflare Worker in particular sits on a datacenter IP and cannot reach `youtubei/v1/*` at all (see [Why not a Cloudflare Worker?](#why-not-a-cloudflare-worker)).

## Token Management

Generate a token:

```bash
openssl rand -base64 32
```

Set it as env var on the proxy container (`INNERTUBE_PROXY_TOKEN`) and the API server (`LUMIO__YOUTUBE__INNERTUBE_PROXY_TOKEN`). Both must match.

## Health Check

`.github/workflows/innertube-health.yml` runs `cargo test -p lo-youtube-api --test innertube_smoke -- --ignored --nocapture` with the `INNERTUBE_PROXY_URL` and `INNERTUBE_PROXY_TOKEN` GitHub secrets (the smoke test reads the single-host form) to verify `total_views` end-to-end. If the proxy is down, the health check emits a warning or failure alert to Discord.

Because `player` and `updated_metadata` return `LOGIN_REQUIRED` from datacenter IPs (see above), a health-check run that does **not** reach the proxy - secrets unset, or the proxy unreachable - falls back to a direct call from the GitHub Actions runner and reports both `like_count` and `total_views` as empty, while the direct `browse` / chat checks stay green. To make that failure legible, the smoke test installs a `tracing` subscriber that routes the crate's `WARN` diagnostics to the CI log (the workflow runs with `--nocapture`). The log then names the exact failure path - a `playabilityStatus` bot-challenge (`LOGIN_REQUIRED`), a non-200 proxy status, or a missing `viewCount` / `videoDetails` field - instead of a bare "unavailable". Raise the level with `RUST_LOG` when running the test locally.

## Key Files

| File | Purpose |
|------|---------|
| `apps/innertube-proxy/src/main.rs` | Actix Web proxy server |
| `apps/innertube-proxy/BUILD.bazel` | Bazel build + OCI image targets |
| `crates/lo-youtube-api/src/innertube/browse.rs` | `InnerTubeProxy` host pool, proxy routing + multi-host failover |
| `apps/api/src/config.rs` | `YouTubeSettings` proxy fields (`innertube_proxy_urls` + single-host alias) |
| `apps/api/src/workers/youtube.rs` | Proxy config wiring |

---

## Developer Guide / Kick Webhook Public Key

Source: https://docs.lumio.vision/developer-guide/kick-webhook-public-key

# Kick Webhook Public Key

Kick signs every webhook delivery with one RSA key. It publishes that key without authentication at `https://api.kick.com/public/v1/public-key`, in the shape `{"data":{"public_key":"<SPKI PEM>"},"message":"OK"}`. The API fetches, caches and refreshes this key itself. Operators do not set it by hand.

The refresher has the same shape as the [InnerTube credential refresher](../features/youtube-streaming.md), with one deliberate difference: it **fails closed**.

## Resolution order

```text
webhooks.kick_public_key (optional pin) -> in-process key -> Redis -> live fetch from Kick
```

| Stage | Source | Notes |
|-------|--------|-------|
| 1 | `webhooks.kick_public_key` | Optional operator pin. When set, the pin always wins, and the refresher and the rotation refetch are both off. If the pin cannot be parsed, **every** delivery is rejected. The fetched key is never used silently in place of a broken pin. |
| 2 | In-process key | This is the parsed key the receiver verifies against. An ordinary delivery never parses PEM and never reads Redis. |
| 3 | Redis `lumio:kick:webhook_public_key` | Holds `{pem, fetched_at}` with a 24 h TTL. The leader writes it and every replica reads it. |
| 4 | `GET /public/v1/public-key` | Returns the live key from Kick. A successful fetch is written to Redis and installed in the process. |

There is **no compiled-in fallback key**. A baked-in key could not be revoked without a deploy if Kick ever rotated its key because of a compromise. When nothing resolves, the receiver answers `401` while `webhooks.require_signatures = true` (the default). The legacy `webhooks.kick_secret` HMAC path is consulted only in this no-key case.

## Refresher worker

`apps/api/src/workers/kick_public_key.rs` runs one cycle at startup and then one cycle every `refresh_interval_secs`:

- **Leader** (Redis `SET NX` on `lumio:kick:public_key_refresh:leader`, TTL about 90 % of the interval, left to expire): fetches the key from Kick, writes Redis, and installs the key in its own process.
- **Followers**: pull the Redis value into their own process.
- **Failed fetch**: the key already held stays in use, because it is most likely still valid.
- **Cold boot**: if a leader cycle ends with no usable key, the leader logs at `ERROR` and fires one Discord alert per incident. The alert is edge-triggered and latched in Redis under `lumio:kick:public_key_cold_boot_alert`, using the same state machine as the InnerTube alert (ZAF-206).

## On-demand reload in the receiver

`POST /v1/webhooks/kick` reloads the key itself in exactly two cases:

1. **Cold process.** No key is held yet, for example when a delivery arrives before the refresher's first cycle. The receiver reads Redis, then fetches from Kick.
2. **Rotation.** A signature fails against a *fetched* key (never against a pin). The receiver reloads once, checking Redis first because another replica may already hold the rotated key and then Kick. If the new key differs, it re-verifies **once**. It never loops.

Both reloads are single-flight (a Tokio mutex) and are skipped when the previous on-demand attempt was less than `refetch_cooldown_secs` ago, or when the failing key was itself fetched that recently. The cooldown is floored at 60 s. A flood of forged deliveries therefore costs Kick at most one request per cooldown window, and a bad signature against a fresh key is plain `401` with no refetch.

## Configuration

`[webhooks.kick_public_key_observer]` in `apps/api/config/default.toml`:

| Key | ENV | Default | Meaning |
|-----|-----|---------|---------|
| `refresh_interval_secs` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__REFRESH_INTERVAL_SECS` | `21600` | Scheduled refresh interval (6 h). Shorter than the 24 h Redis TTL. |
| `refetch_cooldown_secs` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__REFETCH_COOLDOWN_SECS` | `60` | Minimum gap between on-demand reloads. Values below 60 are raised to 60. |
| `public_key_url` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__PUBLIC_KEY_URL` | `https://api.kick.com/public/v1/public-key` | Fetch endpoint. Override it only for tests or an egress proxy. |
| `cold_boot_alert_webhook_url` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__COLD_BOOT_ALERT_WEBHOOK_URL` | empty | Discord webhook for the no-key alert. Empty disables the alert, but the `ERROR` log still fires. |
| `cold_boot_alert_after_failures` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__COLD_BOOT_ALERT_AFTER_FAILURES` | `1` | Number of consecutive no-key cycles before the alert fires. `0` counts as `1`. |

## Metrics

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `kick_webhook_public_key_refresh_total` | counter | `trigger` (`scheduled`/`on_demand`), `outcome` (`changed`/`unchanged`/`fetch_failed`) | Fetches against Kick |
| `kick_webhook_public_key_age_seconds` | gauge | - | Seconds since the key in use was fetched. `0` means pinned, `-1` means there is no key and deliveries are rejected. The value is computed at scrape time. |

A value above 24 h means refreshes are failing. A value of `-1` means Kick events are being dropped.

## Audit

This worker emits no audit event. Refreshing the key is internal bookkeeping with no actor and no tenant effect (see [Audit Events](./audit-events.md), "do not emit").

## Code

| File | Role |
|------|------|
| `apps/api/src/services/kick_public_key.rs` | Resolution order, in-process key, single-flight reload, age collector |
| `apps/api/src/workers/kick_public_key.rs` | Scheduled refresher, leader lock, cold-boot alert |
| `crates/lo-kick-api/src/webhook.rs` | `fetch_public_key`, `parse_public_key`, `verify_rsa_signature_with_key` |
| `apps/api/src/routes/webhooks.rs` | `POST /v1/webhooks/kick` receiver |

---

## Developer Guide / Kick Chat-Moderation Listener

Source: https://docs.lumio.vision/developer-guide/kick-chat-listener

# Kick Chat-Moderation Listener

Kick sends no webhook when a message is deleted on kick.com or when a user is unbanned there. Kick declined to add one (`KickEngineering/KickDevDocs#310`, closed 2025-12-14). Both actions are broadcast only on Kick's **unofficial** public chat WebSocket, which runs on Pusher. The API keeps one outbound connection to it and handles exactly two events:

| Pusher event | Handling |
|--------------|----------|
| `App\Events\MessageDeletedEvent` | `lo_chat::soft_delete_message`, moderation log `delete`, WS `chat:delete` + `chat:moderation_log` |
| `App\Events\UserUnbannedEvent` | `lo_chat::mark_user_unbanned`, moderation log `unban` with the acting moderator, WS `chat:moderation_log` |
| everything else (`ChatMessageEvent`, `UserBannedEvent`, subs, hosts, …) | dropped by event name, nothing stored or forwarded |

Chat messages come in through the official `chat.message.sent` webhook, and bans and timeouts through `moderation.banned`. The listener adds no new data category.

**Unofficial means best effort.** Kick documents no contract for this socket and is moving its own web client to Centrifugo. When the listener fails, deletes and unbans made on kick.com stop reaching Lumio. The webhook intake, chat, events and moderation issued from Lumio are not affected: the listener sits on neither the webhook path nor the request path.

## Protocol

- **Socket:** `wss://ws-{cluster}.pusher.com/app/{app_key}?protocol=7&client=js&version=8.4.0&flash=false`. Connecting needs no authentication.
- **Channel:** `chatrooms.{chatroom_id}.v2`, subscribed with `pusher:subscribe` and an empty `auth`. Kick confirms each subscription with `pusher_internal:subscription_succeeded`.
- **Payload:** `data` is a JSON **string** inside the frame. A delete carries `{id, message:{id}, aiModerated, violatedRules}`. An unban carries `{id, user:{id,username,slug}, unbanned_by:{id,username,slug}, permanent}`.
- **Keep-alive:** the listener answers `pusher:ping` with `pusher:pong`. It sends its own `pusher:ping` after `activity_timeout` seconds of silence (from `pusher:connection_established`, 120 s by default) and reconnects when no answer arrives within 30 s.
- **Message ids:** `MessageDeletedEvent.message.id` is the id of the deleted `ChatMessageEvent`. A 2026-09-30 capture of 20 live chat rooms matched 25 of 25 deletes to a chat message seen earlier on the socket. The same UUID is the `message_id` Lumio stores from the `chat.message.sent` webhook as `platform_message_id`. An id Lumio does not know only increments a counter and can never delete another message.

### Chat-room ids

The official API has no chat-room id. For each connected Kick channel (`channel_connections` with `platform = 'kick'`), the listener resolves one as follows:

1. It reads Redis `lumio:kick:chatroom_id:{broadcaster_user_id}` (7 d TTL).
2. On a miss, it gets the slug from the stored `channel_login`, or else from the official `GET /public/v1/channels?broadcaster_user_id` with the connection's token.
3. It reads `chatroom.id` from `kick.com/api/v2/channels/{slug}` (undocumented, see [Connections → undocumented kick.com endpoints](../features/connections.md#kick-undocumented-kickcom-endpoints)).

If the lookup fails, the channel is skipped with a `warn!` and retried after 10 minutes. There are at most 50 lookups per resync. No migration is involved.

## Runtime shape

`apps/api/src/workers/kick_chat_moderation.rs`:

- **One listener per deployment.** A Redis lease (`lumio:kick:realtime_listener:leader`, 30 s TTL, renewed every 10 s by its owner) picks the replica that listens. The other replicas retry every 15 s. If the lease holder dies, another replica takes over within about 30 s. Processing an event twice during a hand-over is harmless: deletes are idempotent and unbans are deduplicated.
- **Channels follow connections.** The listener re-reads the connected Kick channels every `resync_interval_secs`. The same trigger that starts the Kick webhook worker (a connect, or a disconnect through the worker manager) also wakes the listener immediately.
- **Sharding.** Each connection carries at most `max_channels_per_connection` chat rooms (250 channels means 3 connections at the default 100). If Kick does not confirm a subscribe within `subscribe_confirm_timeout_secs`, or refuses it, the room is logged and moved to the next connection. After 3 moves it is parked for 10 minutes. A connection with no rooms closes its socket.
- **Reconnect.** A dropped or failed connection reconnects with backoff from 1 s up to 60 s, plus jitter. The backoff resets after a connection that lived at least 60 s.
- **Provider-neutral.** A connection talks only through the `RealtimeAdapter` trait (`services/kick_chat_moderation.rs`). `PusherAdapter` is the only implementation. A Centrifugo adapter would be one more implementation, not a rewrite.
- **Fail-safe.** A malformed event is dropped and counted, and a `warn!` is logged for the 1st, 2nd, 4th … occurrence. When the handler queue (1024 events) is full, the event is dropped and counted instead of blocking the socket. A delete that arrives before the chat buffer flush (Redis to TimescaleDB every 5 s) is retried once after 12 s.

### Deduplication

- **Delete.** The `deleted_at IS NULL` guard in `soft_delete_message` makes the delete idempotent. A message already deleted from Lumio, or deleted twice on the socket, changes nothing and writes no second log line. The delete event names no moderator, so the log uses `"moderator"`, the placeholder Twitch's `channel.chat.message_delete` path uses. When Kick marks the delete `aiModerated`, the log uses `"Kick AutoMod"` and stores `violatedRules` in `details`.
- **Unban.** An `unban` for the same user already logged within 60 s (`KICK_BAN_WEBHOOK_DEDUP_SECS`, e.g. an unban issued from Lumio) is skipped. The payload has the same shape as the Twitch `channel.unban` path, including `duration_secs` / `ends_at` (both `null`).

## Pusher key store

The Pusher `app_key` is public, but kick.com hands it to its web client at runtime and does not hardcode it. The API keeps it the same way it keeps the InnerTube key (`services/kick_realtime_credentials.rs`):

```text
override (emergency pin) -> Redis lumio:kick:realtime_pusher_credentials (24 h) -> fresh fetch -> cold-boot constant
```

- **Fetch:** `POST https://web.kick.com/api/v1/realtime/connection` with no auth and the body `{"client":{"id":"<uuid>","type":"web"},"capabilities":{"accepted_providers":[{"provider":"pusher"}]}}`. It answers `{"data":{"connections":[{"provider":"pusher","credentials":{"app_key":"…","cluster":"us2"}}],"mode":"websocket"},"message":"success"}`. Only a `pusher` entry with a valid `app_key` and `cluster` is accepted. Both values are charset-checked because they end up in the socket URL.
- **Cold boot:** `cold_boot_app_key` / `cold_boot_cluster` (`34bf7a0ff419a2a775b9` / `us2`, measured 2026-10-22). These are used only when override, Redis and the fetch all came up empty.
- **Refresher** (`workers/kick_realtime_credentials.rs`): does a full resolution at startup, then runs every `refresh_interval_secs` (6 h). The leader is chosen through Redis `SET NX` on `lumio:kick:realtime_refresh:leader`, with a TTL of about 90 % of the interval. The leader fetches and writes Redis, and followers adopt the Redis value. A key change logs the old and new public values at `info!`, and the listener reconnects every connection with the new key.
- **Failed fetch:** the key already held stays in use, and a process still on the cold-boot key adopts the Redis value if one exists.

### Emergency pin

Set **both** `app_key_override` and `cluster_override` (preferably through `LUMIO__KICK__REALTIME__APP_KEY_OVERRIDE` / `LUMIO__KICK__REALTIME__CLUSTER_OVERRIDE`). A pin wins over every other source and disables the refresher, and the API logs one `warn!` at startup. If only one of the two is set, or the pair is malformed, the pin is ignored. Unset both to resume auto-refresh.

### Alarms

The leader drives two alarms. Each is edge-triggered and latched in Redis: one incident sends one Discord message, and one recovery message follows when the incident clears. Both are logged at `ERROR` even when no webhook is configured.

| Alarm | Condition | Redis latch |
|-------|-----------|-------------|
| Cold boot | No pin, Redis empty, fetch failed: the listener runs on the cold-boot key | `lumio:kick:realtime_cold_boot_alarm` |
| Pusher no longer offered | The fetch worked, but kick.com offered no `pusher` provider (Centrifugo only) | `lumio:kick:realtime_pusher_not_offered_alarm` |

`alert_after_failures` (default `1`) requires that many consecutive bad cycles before an alarm fires. A cycle that says nothing about a condition keeps its latch: a failed fetch neither raises nor clears "not offered". When "Pusher no longer offered" fires, the listener keeps running on the last known key until Kick shuts Pusher down. The follow-up is a Centrifugo adapter.

## Configuration

`[kick.realtime]` in `apps/api/config/default.toml`:

| Key | ENV | Default | Meaning |
|-----|-----|---------|---------|
| `enabled` | `LUMIO__KICK__REALTIME__ENABLED` | `true` | Disable switch for the listener and the key refresher. |
| `max_channels_per_connection` | `LUMIO__KICK__REALTIME__MAX_CHANNELS_PER_CONNECTION` | `100` | Chat rooms per socket. |
| `subscribe_confirm_timeout_secs` | `LUMIO__KICK__REALTIME__SUBSCRIBE_CONFIRM_TIMEOUT_SECS` | `10` | Wait for `subscription_succeeded` before a room moves on. |
| `resync_interval_secs` | `LUMIO__KICK__REALTIME__RESYNC_INTERVAL_SECS` | `60` | Channel re-read interval (minimum 10). |
| `app_key_override` / `cluster_override` | `LUMIO__KICK__REALTIME__APP_KEY_OVERRIDE` / `…__CLUSTER_OVERRIDE` | empty | Emergency pin (both or neither). |
| `cold_boot_app_key` / `cold_boot_cluster` | `LUMIO__KICK__REALTIME__COLD_BOOT_APP_KEY` / `…__COLD_BOOT_CLUSTER` | `34bf7a0ff419a2a775b9` / `us2` | Stage-4 value, never a pin. |
| `connection_url` | `LUMIO__KICK__REALTIME__CONNECTION_URL` | `https://web.kick.com/api/v1/realtime/connection` | Key fetch endpoint. |
| `refresh_interval_secs` | `LUMIO__KICK__REALTIME__REFRESH_INTERVAL_SECS` | `21600` | Key refresh interval (minimum 60). |
| `alert_webhook_url` | `LUMIO__KICK__REALTIME__ALERT_WEBHOOK_URL` | empty | Discord webhook for both alarms (a `SensitiveString`, never logged). |
| `alert_after_failures` | `LUMIO__KICK__REALTIME__ALERT_AFTER_FAILURES` | `1` | Consecutive bad cycles before an alarm; `0` counts as `1`. |

## Metrics

On the internal `/metrics` server. No series carries a channel, account or user id.

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `kick_chat_ws_connected` | gauge | - | Open listener connections. `0` with Kick channels connected means the listener is down or not the leader on this replica. |
| `kick_chat_ws_events_total` | counter | `event` (`message_deleted`, `user_unbanned`, `chat_message`, `user_banned`, `other`, `unknown`), `outcome` (`applied`, `noop`, `duplicate`, `dropped`, `malformed`, `unrouted`, `overflow`, `error`) | Socket events and what happened to them. `noop` = message already deleted or unknown to Lumio. |
| `kick_realtime_credentials_source` | gauge | `source` (`override`, `redis`, `fetch`, `cold_boot`) | `1` for the source of the key in use. |
| `kick_realtime_pusher_offered` | gauge | - | `1` while kick.com still offers Pusher, `0` once it stops. |
| `kick_realtime_credentials_refresh_total` | counter | `outcome` (`changed`, `unchanged`, `not_offered`, `fetch_failed`) | Leader refresh cycles. |

## Audit

The listener emits no audit event. Deletes and unbans made on kick.com land in the chat moderation log, which is not a security record (see [Audit Events](./audit-events.md), "do not emit").

## Tests

- Parser and key-store unit tests with the measured payloads as fixtures (`apps/api/tests/fixtures/kick_pusher/*.json`, embedded via `include_str!`, `compile_data` in Bazel).
- DB integration tests `apps/api/tests/kick_chat_moderation.rs`: delete, AutoMod attribution, dedup against a delete issued from Lumio, unknown id, unban resets ban state, unban dedup.
- Live smoke test (network, not in CI): `cargo test -p lumio-api --lib kick_chat_live_smoke -- --ignored --nocapture` fetches the key, resolves a chat room through v2 and waits for the subscribe confirmation.

## Code

| File | Role |
|------|------|
| `apps/api/src/services/kick_chat_moderation.rs` | Frame model, `RealtimeAdapter`, `PusherAdapter`, `ShardPlan`, chat-room lookup, apply functions, listener metrics |
| `apps/api/src/workers/kick_chat_moderation.rs` | Lease, session, shards, event handler |
| `apps/api/src/services/kick_realtime_credentials.rs` | Key store, resolution chain, alarm decision, key metrics |
| `apps/api/src/workers/kick_realtime_credentials.rs` | Refresher, leader lock, Discord alarms |
| `crates/lo-kick-api/src/client.rs` | `KickWebsiteChannel.chatroom_id` |

---

## Developer Guide / 7TV Event Listener

Source: https://docs.lumio.vision/developer-guide/seventv-event-listener

# 7TV Event Listener

The API listens to 7TV's public EventAPI at `wss://events.7tv.io/v3` without an
API key. It watches the active 7TV emote sets of connected Twitch, Kick, and
YouTube channels. Additions, removals, renames, and active-set switches become
ordinary [stream events](/features/events#7tv-emote-set-changes-raw). This is
an outbound listener; it does not add an incoming endpoint or permission.

## Roster and subscriptions

`apps/api/src/workers/seventv_events.rs` elects one listening replica through
the Redis lease `lumio:seventv:events_listener:leader`. The leader reads
`channel_connections` and resolves each channel's 7TV user and active set with
the same 7TV v4 lookup used by the emote fetcher. The result is cached under
`lumio:seventv:link:{platform}:{channel}`: one hour for a linked user, six hours
when there is no 7TV user. A failed lookup is retried after ten minutes. A
roster refresh runs every `roster_refresh_secs`; connection changes on the
leader's replica also wake it. Each refresh caps lookups at 200, with eight in
flight at once.

The listener subscribes to `emote_set.update` for each active set and
`user.update` for each channel's 7TV user. Every subscription condition contains
only `object_id`. A shared set needs one subscription, even when several
channels use it. The listener does not subscribe with `ctx: "channel"`: that
condition would also deliver viewers' personal set changes. A dispatch whose
set or user is absent from the roster produces no event. The `kind: 3` field on
an `emote_set.update` dispatch means an emote-set object, not a personal set;
the roster is the privacy boundary.

Each connection holds at most `max_subscriptions_per_connection` subscriptions;
the listener opens another connection when needed. A silent connection is
considered dead after three server heartbeat intervals. Reconnects use
exponential backoff with jitter and try `RESUME`; if resume fails, the listener
subscribes again. An end-of-stream frame starts a fresh session.

Each connection hands dispatches to the leader's session through a bounded
queue so that a slow database write never stalls the socket. When that queue is
full, the dispatch is lost: it is logged at `warn` and counted as
`seventv_events_dispatch_total{outcome="dropped"}`, apart from the normal
`ignored` skips.

## Storage, relay, and freshness

The listener writes one `platform_event_logs` row per affected account and
broadcasts the stored row through `lumio:events:{account}` to the existing
`events:{account}` WebSocket channel. `external_id` uses the dispatch timestamp
rounded to whole seconds, so replayed frames and a lease handover do not
duplicate a change. A dispatch without a timestamp uses the second it was
received instead, so a later re-add or re-remove of the same emote is never
mistaken for a duplicate. The account's existing event retention sweep applies.
7TV does not provide a changes-since query, so a full outage leaves a gap in
history.

After a change, the listener deletes the affected channels' versioned
`lumio:emotes:v4:{platform}:{channel}` hot-cache keys. For additions and
renames it also upserts the emote into `chat_emotes` and invalidates the
catalog's Redis map. Removal clears the hot cache, but the catalog is
upsert-only: a removed shortcode can remain in the chat-ingest map until that
map expires. Browser chats receiving a matching live 7TV event reload their
emote picker and autocomplete, debounced by two seconds. The normal six-hour
hot-cache TTL remains a fallback when event delivery is unavailable.

## Configuration

The `[seventv]` block in `apps/api/config/default.toml` has these settings:

| Key | Environment variable | Default | Purpose |
|-----|----------------------|---------|---------|
| `events_enabled` | `LUMIO__SEVENTV__EVENTS_ENABLED` | `true` | Turn the listener off for operations; no 7TV events or event-driven cache refresh while off. |
| `ws_url` | `LUMIO__SEVENTV__WS_URL` | `wss://events.7tv.io/v3` | Outbound EventAPI URL. |
| `max_subscriptions_per_connection` | `LUMIO__SEVENTV__MAX_SUBSCRIPTIONS_PER_CONNECTION` | `450` | Maximum subscriptions before opening another connection. |
| `roster_refresh_secs` | `LUMIO__SEVENTV__ROSTER_REFRESH_SECS` | `600` | Interval for re-reading connected channels and their 7TV identities. |

See [Installation](/getting-started/installation#7tv-event-listener) for the
environment override pattern and [Operational Metrics](/developer-guide/metrics)
for the listener's four `seventv_events_*` series.

## Code

| File | Role |
|------|------|
| `apps/api/src/workers/seventv_events.rs` | Lease, roster, connections, dispatch and cache invalidation |
| `apps/api/src/services/seventv_events.rs` | Frame parser, subscriptions, event rows and metrics |
| `crates/lo-events/src/queries.rs` | Cross-platform 7TV predicate for server-merged chat history |

---

## Developer Guide / Chatter List Providers

Source: https://docs.lumio.vision/developer-guide/chatter-list-providers

# Chatter List Providers

The [chatter list](../features/chatter-list.md) knows no platform. Every platform is a **provider** that implements `ChatterProvider` (`apps/api/src/services/chatters/provider.rs`) and is registered in the `ProviderRegistry` built by `ChattersService::build` (`apps/api/src/services/chatters/mod.rs`). `TwitchHelixProvider` (`services/chatters/twitch.rs`) reads Helix; `KickWebProvider` (`services/chatters/kick.rs`) reads kick.com's web list.

What a provider does **not** do: it never writes Redis state, never publishes deltas and never decides who is in or out. The poller (`apps/api/src/workers/chatters.rs`) and the pure state machine (`services/chatters/model.rs`) do that for every platform alike. People who write in the chat are fed in automatically from the normalised `chat:message` stream (`lumio:chat:{account_id}`, `platform` + `user_id` + `badges`), so a platform whose chat already reaches that stream gets its writers listed with no extra work.

## The trait

| Method | Contract |
|---|---|
| `platform()` | The platform slug, e.g. `twitch`. It becomes the `platform` field of the API contract. |
| `listed_only_when_connected()` | Whether to omit the platform from an account's `supported_platforms`, statuses and poller until it has a usable connection. Kick uses this; Twitch remains listed without one and reports `not_connected`. |
| `is_available(account)` | Connection + scope check, **DB only** (it runs on the GraphQL/REST/bootstrap read path). Returns `Available`, `MissingScope` or `NotConnected`; `SourceUnavailable` is learned at poll time. |
| `snapshot(account, max)` | The chatter list (at most `max`), platform `total`, `truncated` and role inputs. `Ok(None)` when a platform has no list endpoint — presence then comes from chat messages alone. Return `ProviderError::MissingScope` for a rejected grant or `SourceUnavailable` for a failed or invalid list source. |
| `role_of(badges)` | Map one chat message's `badges` JSON onto `broadcaster \| moderator \| bot \| vip` (`None` = viewer). |
| `known_bots()` | Curated, lower-cased bot logins for this platform. |
| `base_role_inputs(account)` | Broadcaster id + known bots (incl. the account's own bot account) without a platform call. |
| `avatars(account, ids)` | Optional. `user_id → url`; cached by the poller under `lumio:avatar:{platform}:{uid}` for 24 h. |

Providers that call an OAuth API get tokens **only** from `crate::oauth::get_fresh_connection_token` on the account's channel connection — never the login token, never an inline refresh. Kick's website list is read without an OAuth token.

## Kick provider

`KickWebProvider` is listed only for accounts with a usable Kick channel connection. It takes the channel slug from `channel_login` (or resolves it from the channel identity), caches the kick.com channel id by slug for 24 hours, then reads the undocumented `web.kick.com/api/v1/channels/{channel_id}/chat/active-chatters` endpoint every 60 seconds. Kick's `chatters` group contains at most 100 recent writers, not lurkers; its moderators, VIPs, OGs and bots groups are complete. `total_count` is the platform's full count, so the snapshot reports `truncated` when that count exceeds the listed entries.

The web list gives usernames, not stable user ids. The provider looks up each username at `kick.com/api/v2/channels/{channel_slug}/users/{username}` (at most 50 lookups per poll, five concurrent), caches found ids for 24 hours and misses for one hour. An unresolved entry waits for a later poll; it is never keyed by a name. This lets the snapshot and a chat message update the same `(platform, user_id)` entry. Role groups are resolved first; a partial moderator or VIP id list falls back to chat badges. The channel owner is `broadcaster`, moderator/VIP/bot groups map directly, and OGs and ordinary chatters are `viewer`. Known and account-owned bots take precedence over moderator and VIP.

A blocked request, challenge, non-JSON response or unexpected shape is `ProviderError::SourceUnavailable`. The poller reports `reason = "source_unavailable"`, clears the platform total and truncation flag, and counts each failed poll as a snapshot miss. After two misses, entries kept only by the web list move to recently left; recent writers remain present. The next successful snapshot clears the reason. The Twitch session is independent. Kick requires no new OAuth scope or reconnection for this source.

## Add a platform — 6 steps

1. **Write the provider.** Implement `ChatterProvider` in `apps/api/src/services/chatters/<platform>.rs` and add it to the registry in `ChattersService::build`. Add a `[chatters.<platform>]` table (`enabled`, `poll_interval_secs`, `max_chatters`) to `ChattersSettings::platform` and `config/default.toml`; without one the provider runs on the defaults. Keep every platform-specific name inside the provider: the contract (`Chatter`, `ChatterPlatformStatus`, `ChattersSnapshot`) must not grow a platform field.
2. **Check the scopes.** For OAuth list/role endpoints, add required scopes to the platform's **channel** scopes in `apps/api/src/platforms.rs` and the own-app guide, which reads `channelOAuthScopes` from the API. A new scope makes `missing_scopes()` ask existing connections to reconnect; bundle related scopes into one change. Make `is_available` return `MissingScope` for a grant without them, and treat an unknown (NULL) stored grant as "try and see". A public web source such as Kick's needs no new scope; handle its failures as `SourceUnavailable` instead.
3. **Map badges to roles.** Implement `role_of` for the platform's badge format; take the bot badge `set_id`s from `services/chatters/bots.rs` (`is_bot_badge`), never a second literal list. Identity (broadcaster, known bot) beats lists, lists beat badges, and **bot beats moderator/VIP**. Add unit tests next to the provider like `services/chatters/twitch.rs`.
4. **Curate the bot list.** Add the platform's well-known bots to `services/chatters/bots.rs` (`known_bots(platform)`, lower-case logins, or channel ids for a platform matched by `IdentityKind::UserId` such as YouTube) and return them from `known_bots()`. Include Lumio's own bot account for that platform plus the account's custom bot (`bots::own_bot_identity`). The stream history reads the same module (`BotFilter`, `bot_message_sql`) to leave bot messages out of its chat counts, so the list and the history never disagree.
5. **Wire the live signal.** Live polling (and clearing the list at stream end) reads the account's online set `lumio:channel_online:{account_id}`. The platform's go-live / go-offline path must call `services::channel_status::set_online` / `set_offline` with the provider's platform string; Twitch, Kick and YouTube already do. Without it the platform is polled only while a panel is open, and its list is never cleared at stream end (it still expires 5 minutes after the last poll).
6. **Document it.** Add the platform to the roles and availability notes in [Chatter List](../features/chatter-list.md), any required scopes to [Channel Connections OAuth Scopes](./channel-connections-oauth-scopes.md), and its config table to [Installation](../getting-started/installation.md#chatter-list).

The frontend needs no change: it renders whatever `supported_platforms` lists, and shows platform chips and per-row icons once two or more platforms are connected.

---

## Developer Guide / Public Stats Crawler (Twitch)

Source: https://docs.lumio.vision/developer-guide/public-stats-crawler

# Public Stats Crawler (Twitch)

The public stats crawler records **public, non-personal aggregate** stream stats
(viewer curves, category timelines, title/metadata, and non-identifying chat
aggregates) for **foreign** channels - channels that are not connected Lumio
accounts. Those rows land in the same `channel_history*` tables as first-party
data, tagged `source = 'external_crawler'`, so the existing `/stats` read model
surfaces them with no reader change.

New crawler storage and high-volume write paths follow the
[data design standard](./data-design.md).

The Twitch arm is the app `apps/crawler-twitch`: a long-running Rust container
(precedent: [InnerTube Proxy](./innertube-proxy.md)) - **not** a Cloudflare
Worker, **not** one of the `*-bot` apps, and **not** part of `lumio-api`.

> **Regimes:**
> This crawler is **Regime B** (mass, foreign-channel ingest). First-party session
> recording for connected accounts (**Regime A**) is unrelated and writes directly
> to TimescaleDB. See [Stream History Platforms](./stream-history-platforms.md).

## Architecture

```
   Helix discovery ──▶ crawl-job bus (JobQueue) ──▶ sharded crawler replicas
   (Get Streams,        RabbitMQ in prod;             ├─ anonymous IRC read
    paged, app token)   in-memory single-node          ├─ Helix stats poll (60s)
                        pre-broker                      └─ Twitch-GQL panels (fail-open)
                                                              │ typed CrawlEvents
                                                              ▼
                                              result log (ResultBus)
                                              Kafka in prod; in-memory single-node
                                                              │
                                                              ▼
                                       shared writer ──▶ batch upsert into
                                                         channel_history{,_streams,_stats}
                                                         (source='external_crawler')
```

### Transport seam (broker-agnostic)

Two traits keep the producer code identical on a single-node staging box and on
a multi-node cluster:

- `JobQueue` - the crawl-job bus. Production impl **RabbitMQ** (per-msg ack,
  per-platform routing, DLQ). A job is routed to the shard that owns its channel.
- `ResultBus` - the durable, replayable result log. Production impl **Kafka**,
  partitioned by channel id, consumed by the shared writer.

Redis is **cache only** (never a bus or system-of-record). The crate ships an
**in-memory single-node** implementation of both traits so the full
discovery → shard → writer pipeline is runnable **before** the broker/cluster
land. End-to-end validation on staging single-node is gated on broker
provisioning; live global ingestion is a separate, capacity-gated step.

### Components

| Component | Role |
|-----------|------|
| **Discovery** | Resolves the live [crawl scope](#crawl-scope) and enumerates the channels it covers, publishing one crawl job per live channel. `global` pages Helix `Get Streams` (100/page, cursor, app token) over the whole live set; the bounded modes query a resolved channel set via `Get Streams?user_id=` (≤100 ids/request). |
| **Shard worker** | Owns `hash(channel_id) % num_shards`. Opens one anonymous (`justinfan`) IRC client, JOINs its channels under a JOIN token-bucket, and folds chat into per-broadcast aggregates. **No single-leader election.** |
| **Stats poller** | 60s viewer sweep over the live [crawl scope](#crawl-scope) → `StreamObservation` events (viewer curve + title/category/tags). Branches on the mode exactly as Discovery does. Fires the panels fetch once per broadcast. The writer diffs each observation's title/category/tags into the per-broadcast **stream-metadata change timeline** (`public_stream_metadata_history`, ZAF-890 - old→new rows, idempotent on unchanged re-observe). |
| **Channel GQL** | One undocumented Twitch GQL `user(login:)` fetch per broadcast at session start, carrying the ad-marked **panels**, the public **follower total** (ZAF-796), the **About box** (description / social links / team, ZAF-799), and the **channel type** (`roles { isPartner isAffiliate }` → partner/affiliate, ZAF-841). Isolated and **fail-open** - a missing/renamed field simply reads as absent and never drops the session; each derived event is emitted independently. The panels event is emitted on **any valid observation** (a `user` node with an `id`) even when the ad-marked set is **empty**, so the writer can reconcile panel **removals** (ZAF-892); a fail-open null fetch emits nothing (no spurious removals). |
| **Writer** | Kafka consumer group. Batch-upserts into `channel_history*` with one set-based statement per table and flush (see [Writer flush](#writer-flush)) **and** into the crawled channel-level tables `public_channel_{panels,metrics,profile}`, all in TSDB (relocated from main Postgres, ZAF-843), with write-amplification guards. **Panel lifecycle reconciliation** (ZAF-892): after upserting the present ad panels, it marks `removed_at` on any stored `panelId` absent from the channel's current set and clears it on re-observation - coherent per panel, guarded so an unchanged state writes nothing. |
| **Close sweep** | Ends crawled streams that stopped being sampled and freezes their sessions - see [Session lifecycle](#session-lifecycle). |
| **Opt-out enforcer** | Refreshes the opt-out registry from `public_channel_settings` (main DB) on a fixed cadence; every producer consults it before crawling, and it erases newly opted-out channels' crawled rows from TSDB. |

## Crawl scope {#crawl-scope}

The crawler is not unconditionally global. A **scope selector** bounds *which*
live channels the crawler touches - both the jobs Discovery publishes and the
observations the Stats poller records - so `/stats` can launch on today's
single-host capacity and later ramp to a full global sweep with one admin flip
(founder ruling ZAF-594). Four modes:

| Mode | Channels crawled |
|------|------------------|
| `lumio` | First-party roster only - channels in `channel_connections`. |
| `list` | Curated `crawl_watchlist` only. |
| `lumio_plus_list` | **Default** - the union of the roster and the watchlist. |
| `global` | The unfiltered Helix sweep (kill-switch / ramp target). |

- **Fail-closed default.** The default is `lumio_plus_list` (bounded), **never**
  `global`. `global` is an explicit, opt-in widening. An unreadable settings row
  or a corrupt value resolves to the configured fallback, never silently to
  `global`.
- **DB-backed & live-switchable.** The active mode is the singleton
  `crawler_settings.scope` row in the **main** Postgres DB, re-read once per
  sweep by each producer - an operator change lands on the next tick, no
  redeploy. The TOML `[crawler] scope` key is only the fallback default used when
  the row is unreadable.
- **Every Helix producer branches on the mode.** `global` keeps the paged
  whole-live-set sweep. The bounded modes resolve a channel-id set from
  `channel_connections` (`lumio`) and/or `crawl_watchlist` (`list`), deduplicate
  it, and query it directly via Helix `Get Streams?user_id=` in ≤100-id batches -
  **skipping** the global sweep. A bounded scope that resolves to zero channels
  does nothing (the fail-closed outcome), never a global fallback.
- **Both producers, not just Discovery.** The Stats poller is the module that
  actually feeds `channel_history_streams` / `_stats`, so it must honour the
  scope too - while it paged the whole live set, a `lumio_plus_list` deployment
  still wrote global history rows regardless of what Discovery published
  (ZAF-790). A source-scan guard in `apps/crawler-twitch/src/stats.rs` fails the
  build if any crawler module reaches the unfiltered sweep without first
  resolving the scope.

### Admin control surface

The mode and the watchlist are steerable from the Admin app on **both**
protocols (GraphQL primary + REST parity - same fields, validation, and error
messages):

| Action | GraphQL | REST | Permission |
|--------|---------|------|------------|
| Read scope | `crawlerScope` | `GET /v1/crawler/scope` | `crawler:scope-read` |
| Set scope | `setCrawlerScope(scope)` | `PUT /v1/crawler/scope` | `crawler:scope-edit` |
| List watchlist | `crawlerWatchlist(platform)` | `GET /v1/crawler/watchlist` | `crawler:watchlist-read` |
| Add channel | `addCrawlerWatchlistChannel(input)` | `POST /v1/crawler/watchlist` | `crawler:watchlist-create` |
| Remove channel | `removeCrawlerWatchlistChannel(platform, platformChannelId)` | `DELETE /v1/crawler/watchlist/{platform}/{platform_channel_id}` | `crawler:watchlist-delete` |

The `crawler:*` permissions are **granular** (the coarse `:manage` is disallowed
by the ZAF-594 ruling; see [RBAC Permissions](./rbac-permissions.md)) and
**admin-scope** - steering the single global crawler is a platform-operator
action, so they are enforced via `require_admin_permission` /
`AdminPermissionGuard` (never account-scope grants) and seeded to the
`system_admin` admin role (ZAF-725; migration
`20260825000001_crawler_perms_to_admin_scope`). Every scope change and watchlist
mutation emits a **system-scope** audit event (`crawler:scope_changed`,
`crawler:watchlist_added`, `crawler:watchlist_removed`). Adding a channel is an
idempotent upsert on the `(platform, platform_channel_id)` identity.

## Identity & write path

Each crawled broadcast maps onto the frozen identity columns on
`channel_history_streams`:

| Helix field | Column |
|-------------|--------|
| `user_id`   | `platform_channel_id` (join key, frozen) |
| `user_login`| `channel_login` (URL spelling, frozen) |
| `user_name` | `channel_display_name` (frozen) |
| `id` (stream) | `broadcast_id` - public key `(platform, broadcast_id)` |

Identity and `source` are captured **once on INSERT and never rewritten** (a
later handle rename must not rewrite history), mirroring the first-party
contract. Viewer samples upsert with `ON CONFLICT … DO UPDATE … WHERE
viewer_count IS DISTINCT FROM …` so an unchanged re-poll is not a fresh
row-version.

### Writer flush {#writer-flush}

The writer collects events for `writer_batch_size` (500) events or
`writer_flush_interval_secs` (5 s), whichever comes first, keeps the last event
per broadcast and sorts them by `broadcast_id`. It then writes the whole flush
with a fixed number of statements, however many channels are live:

| Step | Statement | Failure |
|------|-----------|---------|
| 1 | `channel_history_streams` upsert from `UNNEST` arrays | transaction: all of 1–3 or nothing |
| 2 | `channel_history` (session) upsert from `UNNEST` arrays | transaction |
| 3 | `channel_history_stats` viewer samples from `UNNEST` arrays | transaction |
| 4 | Stream-metadata diff into `public_stream_metadata_history`, after the commit | fail-open: logged and counted, never rolls back 1–3 |
| 5 | Chat aggregates onto `channel_history_streams`, then onto `channel_history` (`UPDATE … FROM UNNEST`) | logged and counted |

That is six statements plus `BEGIN`/`COMMIT` per flush. Panels, follower
totals and About boxes are still written one channel at a time; they arrive
once per broadcast, not every minute.

- **One row per key.** Each statement carries a broadcast at most once. A key
  twice in one `INSERT … ON CONFLICT DO UPDATE` fails the whole statement, so the
  per-broadcast dedupe is a hard invariant.
- **Lock order.** Arrays are sorted by `broadcast_id`, and stream rows are
  written before session rows. The close sweep locks stream rows with
  `SKIP LOCKED` and then waits on sessions, so a writer that reopens a closed
  broadcast cannot deadlock with it. Should the transaction still deadlock
  (`40P01`), it is retried once.
- **Metadata diff.** Step 4 locks the anchor stream rows `FOR UPDATE` in
  `broadcast_id` order and compares each incoming title / category / tags value
  with the latest recorded value of that field for that broadcast. A broadcast
  without its stream row is skipped.
- **Bounded bus.** The in-process result bus between the producers and the
  writer holds at most `writer_bus_capacity` events (default 100 000, about two
  minutes of stream and chat events at 30 000 live channels). A producer never
  waits on a full bus; the event is dropped and counted in
  `crawler_bus_dropped_total{kind}` (`stream`, `chat`, `panels`,
  `channel_metrics`, `channel_profile`). Every event is a latest-value
  snapshot, so a drop leaves a gap until the next observation.

### Session lifecycle {#session-lifecycle}

A crawled broadcast is one session with one stream (`session_id` is derived from
the broadcast id). The crawler owns the whole lifecycle of these rows; the API's
first-party history workers skip every session of the nil-UUID sentinel account.

- **Open.** The first observation inserts the session and stream rows. Each
  later poll upserts them and writes one viewer sample per minute.
- **Close.** Helix stops listing a broadcast once it ends, so the crawler
  closes it itself. The close sweep runs every `stream_close_interval_secs`
  (120 s) and ends every `external_crawler` stream with no viewer sample for
  `stream_close_after_secs` (600 s). In one statement it sets the stream's
  `ended_at` to its last sample minute (or its start when it has no samples), its
  final `peak_viewers` / `avg_viewers` from its samples, and on the session
  `ended_at`, `duration_secs`, the same peak/avg and `finalized = TRUE`. It closes
  at most 10 000 rows per statement and repeats until a batch comes back short, so
  a backlog drains without a long lock. Every crawler process may run it;
  `FOR UPDATE SKIP LOCKED` keeps two sweeps off the same rows. After a start it
  first waits one `stream_close_after_secs`, so streams the poller has not re-seen
  since a crawler outage are not ended. Closed rows count in
  `crawler_streams_closed_total`.
- **Frozen, not finalized by the API.** The crawler keeps the chat aggregates
  current while the stream is live, so a closed crawled session is already
  final. The API finalizer never picks it up: its account-scoped aggregation
  (chat log, events) would zero those aggregates.
- **Reopen.** A closed broadcast that Helix lists as live again (after a crawler
  outage longer than the close window) is reopened by the next upsert:
  `ended_at`, `duration_secs` reset and `finalized = FALSE`. The next close
  freezes it again.

Liveness on the public pages is still observation freshness (a viewer sample in
the last 5 minutes), which clears a stream before the close sweep ends it.

### Notes on the data model

- The crawler adds **no migration** of its own; the tables and indexes are
  owned by `apps/api/tsdb_migrations`.
- `channel_history_streams` has no index on `peak_viewers` or `avg_viewers`
  and leaves 10 % free space per page (`fillfactor = 90`). A peak rise of a
  live stream then changes no indexed column and can be a HOT update. The
  browse ranks these values after grouping by channel, so such an index would
  have no reader.
- `channel_history.account_id` / `channel_history_stats.account_id` are
  `NOT NULL`, so crawler rows (which have no owning account) use a **nil-UUID
  sentinel** account id. Whether to make `account_id` nullable instead is a
  write-path decision for the API owner.
- There is no `channel_history_panels` table; panels land in
  `channel_history_streams.platform_metrics -> 'twitch' -> 'panels'`.
- The panel **lifecycle marker** `public_channel_panels.removed_at` (ZAF-892) is
  the one exception to "no migration owed": that `ALTER TABLE ... ADD COLUMN` lives
  in `apps/api/tsdb_migrations` (API-owned), not the crawler. The crawler only
  writes it (the per-observation reconciliation above); image *versions* need no new
  column - they are already the `content_hash`-keyed version rows.

## Regime-B capture scope (aggregates only)

For channels crawled **without consent**, capture is restricted to genuinely
public, non-personal aggregates:

- **Kept:** unique-chatter *count*, message count, top *words*, top *emotes*,
  viewer curve, category timeline, title/metadata.

The viewer curve lands in `channel_history_stats` (raw 60s samples) and is rolled
up into the `channel_history_stats_5m` / `_1h` continuous aggregates that long /
cross-session reads use. Raw samples are kept 90 days and the 5m rollup 12
months, both table-wide (crawled and first-party alike); the 1h rollup is kept.
See
[Stream History: storage, rollups & retention](./stream-history-storage.md) for
which layer answers which read and how retention is bound by the privacy policy.
- **Excluded until a channel is verified-claimed / opted in:** per-username "top
  chatters" and pinned-message author/text. These identity-bearing fields write
  `NULL` for `source='external_crawler'` rows.

### GIF content data - Top GIFs (ZAF-965 decision)

Top GIFs are the one Regime-B capture that is a **content datum**, not a pure
distribution/count, so the ZAF-965 founder decision (2026-09-03) opened them as
their own ingest / retention / legal case (capture + retention in **ZAF-968**;
privacy, consent-category and retention decision in **ZAF-969**; public display in
**ZAF-970**, which is blocked on the legal texts landing first).

- **What is stored:** per broadcast, **which GIF appeared and how often** - the
  GIPHY id and the GIPHY image URL plus a frequency count. **No sender reference
  is stored** - no chatter username, no message text, no user/message id. The
  stored record identifies no natural person ("which GIF, how often"), the same
  non-personal class as top *words* / top *emotes*.
- **Retention: 90 days.** Unlike the indefinitely-kept public-profile /
  stream-metadata change histories, GIF content data is bounded to **90 days**
  (aligned with the raw retention of the other crawled broadcast data - the
  `channel_history_stats` raw-sample window, ZAF-689), then auto-deleted. Opt-out
  erases a channel's GIF content data like every other crawled row. This figure
  is fixed by the founder decision and is stated identically in ZAF-968; do not
  let the two drift.
- **Display is consent-gated (Giphy embed).** The public Stats page renders the
  Top GIFs by loading the image directly from `media*.giphy.com`, which transmits
  the **visitor's** IP + user agent to GIPHY (US). Because `stats.lumio.vision` is
  public - the visitor is not a customer, so the Multichat Art. 6(1)(b) contract
  basis does **not** carry over - the embed loads **only after the visitor grants
  the Functional consent category**, honouring the `cookies.mdx` "loads only after
  consent, listed beforehand" promise. Consent category = **Functional** (the same
  class as the existing YouTube/Twitch embeds; see
  `shared/cookies-consent` `cookieDetector.ts`). Legal basis for the display is
  Art. 6(1)(a) GDPR consent; the US transfer rides GIPHY/Shutterstock's EU-US DPF
  certification + SCCs. Storing the id/URL does **not** itself hit GIPHY - only the
  display does.
- **Where it is documented:** the published treatment lives in
  `apps/web/content/{de,en}/legal/privacy.mdx` (§"Public statistics (Lumio Stats)",
  content class **(D)**) and `…/legal/cookies.mdx` (§"Lumio Stats" embed registry).
- **Ingest (ZAF-968).** Twitch delivers GIFs as a `gifs` IRC tag on the chat
  message - comma-separated `<start>-<end>|<gifID>|<gifURL>` segments. The shard
  worker reads it from the raw `source.tags` (the typed `PrivmsgMessage` drops it,
  same as `source-room-id`), parses it defensively (broken segments dropped, never
  panics), and `apps/crawler-twitch/src/chat.rs` folds it into per-broadcast
  `gif_count` (every occurrence) + `top_gifs` (top-N by frequency). Shared-chat
  GIFs from a foreign room are **excluded** from the host aggregate, exactly like
  emotes (ZAF-819), and **no sender reference** is ever kept (§12). `writer.rs`
  rolls both onto the `channel_history` **session** row - the same columns the
  first-party finalizer fills (ZAF-972) - in the canonical
  `{id, url, provider, alt, count}` shape (`provider`/`alt` are `null` on this IRC
  path, which carries only id + URL). They surface unchanged through the public
  read model (`publicStreamStats` / `GET /v1/public-stats/streams/{platform}/{broadcast_id}`).
- **Retention mechanism (ZAF-968).** `channel_history` is a plain table with no
  TimescaleDB retention policy, so the 90-day cap is an app-side sweep:
  `apps/api/src/workers/gif_retention.rs` (gated by `[public_stats]
  gif_retention_enabled`, **on in production**) periodically erases `gif_count` →
  0 / `top_gifs` → `[]` on crawler rows (`account_id = nil`) older than 90 days.
  Only the GIF content is cleared - the session row, viewer curve and emote/word
  aggregates stay; first-party (owner) history sharing the same columns is **never**
  touched (kept on its Art. 6(1)(b) contract basis); opt-out separately deletes the
  whole crawled row (GIF content included) via the opt-out enforcer.

### Twitch Shared Chat attribution (ZAF-819)

Twitch **Shared Chat** delivers messages from other channels into a host
channel's room. The shard worker reads each PRIVMSG's `source-room-id` IRC tag
(from the raw `source.tags`, which the typed `PrivmsgMessage` drops): when it is
present and differs from the joined room, the message **originated in a different
channel** and is attributed to that source channel instead of being folded into
the host's aggregate. Concretely, a shared-chat message is kept **out** of the
host broadcast's `message_count` / `unique_chatters` / top-words / top-emotes, and
counted in a per-source-channel breakdown emitted on the `ChatAggregate` and
written to `channel_history_streams.shared_chat_sources` as
`[{"platform_channel_id": …, "message_count": …}]` (`NULL` for a normal
broadcast). The public read model surfaces it on every stream summary
(`shared_chat_sources`) so the stream page can show "who these stats are coming
from". At read time each source is enriched with the source channel's
`display_name` + `avatar_url` (ZAF-868), resolved from `public_channel_profile`
keyed by `(platform, platform_channel_id)` - the crawler captures these from the
same `user(login:)` GQL node (`displayName` / `profileImageURL`) it already fetches
for the About box, refresh-and-overwrite, and a source the crawler never profiled
resolves to `null` identity (fail-open, the client falls back to the id). This
stays **aggregates-only** - the breakdown is by **channel** (public broadcaster
identity), never by viewer.

## Opt-out enforcement (two-sided)

A channel opts out by setting `is_public = false` in `public_channel_settings`,
via one of two writers: the **dashboard toggle** (a first-party account managing
its own connected channels) or a **verified `!optout` chat command** typed by the
broadcaster in their own channel (see [below](#broadcaster-optout-chat-command)).
The registry is public-**by-default**: the absence of a row means public.
Enforcement is **two-sided**, and both sides must hold before global ingest is
armed:

- **Read side (already shipped, `apps/api`):** the public-stats read model serves
  nothing for an opted-out channel - single-channel reads return empty, the
  cross-channel browse excludes it, and the WS bootstrap is gated.
- **Capture side (crawler):** the crawler stops *producing* data for the channel
  **and erases what it already captured**:
  - **Roster-drop.** All three producers consult an in-memory opt-out registry
    before acting - Discovery does not publish a crawl job, the Stats poller does
    not emit a viewer sample, and a Shard worker **PARTs** a channel it had
    already joined (dropping its in-flight aggregate). So an opted-out channel is
    neither joined, polled, nor written.
  - **Serviceable deletion.** When a channel newly opts out, its already-captured
    `source='external_crawler'` rows are deleted from `channel_history`,
    `channel_history_streams`, and `channel_history_stats` (scoped to the crawler
    account sentinel / `source`, so first-party history is never touched), together
    with those sessions' rows of the viewer-curve rollups `channel_history_stats_5m` /
    `_1h` in the same transaction (ZAF-2677 - without it, buckets older than the
    refresh windows would stay, `_1h` forever; see
    [Stream History storage](./stream-history-storage.md)), **and**
    its channel-level rows are deleted from `public_channel_panels` (every ad-panel
    version), `public_channel_metrics`, every follower-growth snapshot row
    (`public_channel_follower_history`, ZAF-891), `public_channel_profile`, every
    About-box change-history row (`public_channel_profile_history`, ZAF-836), and
    every stream-metadata change-history row for its broadcasts
    (`public_stream_metadata_history`, ZAF-890 - keyed by broadcast for reads but
    carrying `platform_channel_id` so opt-out erases by channel identity like the
    siblings). All these crawled tables live in TSDB - the `public_channel_*` data
    tables were relocated there (`_panels`/`_metrics`/`_profile`, ZAF-843) or
    authored there directly (`_profile_history` ZAF-836, `_follower_history` ZAF-891,
    `public_stream_metadata_history` ZAF-890) per the founder ruling ZAF-791 - so
    every erasure targets the TSDB pool; only the `public_channel_settings` opt-out
    registry is read from the main Postgres db. A crawler restart reconciles the
    full opted-out set once, so rows that landed while it was down are still erased.
    Each per-table delete is independently fail-open with **no** wrapping
    transaction: if any chunk fails (a transient TSDB outage), that channel is held
    back from the reconciled set and **re-attempted on every subsequent tick until
    all its rows are gone** - it is never left partially erased until a restart
    (ZAF-844). The deletes are idempotent, so re-running them against an
    already-clean table is a harmless no-op.

The registry (`public_channel_settings`) is the one crawled surface that stays in
the **main** Postgres DB, so the crawler opens a small pool onto it (`[database]`)
in addition to its TSDB write pool (the target for `channel_history*`, the
`public_channel_*` data tables, and every erasure). The main-DB pool is
read-mostly: the enforcer reads the registry, and the only write the crawler ever
makes to the main DB is the broadcaster `!optout` upsert below. The refresh + erasure loop
is **fail-open**: a main-DB outage degrades to "enforce with the last-known
snapshot", never a crash, and is retried on the next tick.

`crawler_optout_*` metrics expose the registry size, roster-drop skips, PARTs,
rows erased, refresh/erasure errors, and honoured `!optout` commands
(`crawler_optout_commands_total`).

### Broadcaster `!optout` chat command {#broadcaster-optout-chat-command}

A broadcaster can opt their own channel out **from chat**: they type `!optout` in
their own Twitch channel and the crawler upserts
`public_channel_settings(is_public = false, opted_out_via = 'crawler_command')`
for that channel identity. Enforcement is then **automatic** - the enforcer loop
above picks the new row up on its next refresh and PARTs + erases exactly as it
does for a dashboard opt-out. This is the *write* counterpart to the capture-side
enforcement; there is no separate command-side enforcer.

- **Verification - broadcaster badge alone (design §6 ruling).** The command is
  honoured **only** when the `PRIVMSG` carries the server-authoritative
  `broadcaster/1` badge, which Twitch stamps into the IRC tags for the channel
  owner (and only in their own room). It cannot be forged by a viewer, so it is
  strong self-service proof of *this* channel's ownership. Design §6 also names an
  out-of-band **hash-verified claim**; that stronger proof exists to *bind* a
  channel to a Lumio **account** for management (an access-granting link) and is
  **not** required for opt-out. `!optout` only ever *removes* a channel and
  triggers erasure - a privacy-protective, reversible action whose safe default
  is to honour it immediately (requiring an extra step would mean crawling a
  channel whose owner has already asked us to stop).
- **Non-clobbering, idempotent write.** The upsert only flips a currently-public
  row to opted-out; it never overwrites an existing opt-out (a prior `dashboard`
  opt-out keeps its provenance), never touches `account_id` or
  `show_top_chatters`, and is a no-op once the channel is already opted out
  (`... ON CONFLICT DO UPDATE ... WHERE is_public = true`), so a spammed command
  does not amplify writes. It runs off the IRC hot path and is **fail-open** - a
  failed write is logged/counted and simply retried on the next `!optout`.
- **Audit parity (deliberate difference).** The dashboard path emits a
  `public_stats:channel_opted_out` audit event (**account** scope, actor = the
  Lumio user). The command path **does not** emit that event: the actor is a
  Twitch platform user proven by a badge (no Lumio `user_id`) and a crawled
  channel has no `account_id`, so an account-scoped event has no valid keys; and
  `db::audit::emit` lives inside the `lumio-api` binary crate, unreachable from
  the crawler. Provenance is instead recorded on the row itself
  (`opted_out_via = 'crawler_command'`, `opted_out_by = <broadcaster Twitch user
  id>`, `updated_at`). A *system*-scoped mirror event would require extracting
  audit into a shared crate and is tracked as a coordinated follow-up with the
  Rust Backend Engineer rather than a one-sided raw insert.

## Rate limits & IP reputation

- Runs on a **trusted-IP container host** (never Cloudflare Edge / CI ranges,
  which platforms bot-gate - the InnerTube Proxy lesson).
- Helix is a points bucket (~800/min per app token). Prefer **paged sweeps** over
  per-channel calls; on `429`, honour `Ratelimit-Reset`.
- Anonymous IRC has a per-connection JOIN limit (~20 JOIN/10s); a token-bucket
  paces JOINs. Reconnects are handled automatically by the IRC pool.
- Crawl data **may** be dropped under writer lag (a full result bus, later Kafka
  retention / 1-of-N sampling for hot channels). Drops are **never silent** -
  they increment a metric (`crawler_bus_dropped_total{kind}` for the bus).

## Metrics

The crawler exposes Prometheus text at `GET /metrics` (plus `/health`,
`/ready`). Metric families: discovery coverage/freshness, Helix + reputation
alarms (`429` / auth-fail / `LOGIN_REQUIRED` / ban), IRC connection/JOIN health,
panels, bus/writer throughput + write-amplification (`rows_upserted` vs
`rows_skipped_noop`), drop-policy activations, and opt-out enforcement
(`crawler_optout_*`: registry size, roster-drop skips, PARTs, rows erased,
refresh/erasure errors, honoured `!optout` commands). **Arming alarms on these is
the entry criterion for live ingestion.**

### Arming check for global scope {#arming-check}

Switch the [crawl scope](#crawl-scope) to **Global** only when all of these
hold, measured on the process at its target load:

- **Writer headroom.** The p99 of `crawler_writer_last_batch_ms` stays below
  50 % of `writer_flush_interval_secs` (below 2 500 ms at the default 5 s). A
  flush that takes longer than the interval means the writer cannot keep up.
- **No bus drops.** `crawler_bus_dropped_total` does not grow. A growing count
  means events are lost at the bus before they reach the database.
- **No writer errors.** `crawler_writer_errors_total` does not grow.
- **Browse read model backfilled (ZAF-2300).** `public_browse_state.first_drain_completed_at`
  is set in TimescaleDB. Until then the public browse aggregates every stream
  row ever recorded on each request, which at global scope grows past its
  latency budget within weeks. Once it is set, a browse page reads the
  per-channel read model and its cost does not depend on the stream count.

## Configuration

Layered TOML (`config/default.toml` → `{run_mode}.toml` → `local.toml` → ENV
`CRAWLER_TWITCH__*`). Secrets come from ENV / gitignored `local.toml`:

```
CRAWLER_TWITCH__TWITCH__CLIENT_ID=...
CRAWLER_TWITCH__TWITCH__CLIENT_SECRET=...
CRAWLER_TWITCH__TIMESCALE__URL=postgres://...
CRAWLER_TWITCH__DATABASE__URL=postgres://...   # main DB, opt-out registry (read + !optout write)
```

Two DB pools: `[timescale]` (the write target for `channel_history*` **and** the
crawled `public_channel_{panels,metrics,profile}` data tables - relocated to TSDB
per ZAF-791/ZAF-843) and `[database]` (the main Postgres - the
`public_channel_settings` opt-out registry; read by the enforcer, written only by
the broadcaster `!optout` upsert).

Key `[crawler]` knobs: `num_shards`, `owned_shards`, `discovery_interval_secs`,
`stats_poll_interval_secs`, `page_size`, `max_channels_per_shard`,
`join_bucket_capacity`, `join_refill_per_sec`, `writer_batch_size`,
`writer_flush_interval_secs`, `writer_bus_capacity` (the
[writer flush](#writer-flush)), `optout_refresh_interval_secs`, `stream_close_after_secs` /
`stream_close_interval_secs` (the [close sweep](#session-lifecycle)), and `scope` (the [crawl-scope](#crawl-scope)
fallback default - the live mode is the DB-backed `crawler_settings` row).

The scope selector adds two main-DB tables (owned by `lumio-api` migrations, not
the crawler): `crawler_settings` (the singleton, admin-switchable scope mode) and
`crawl_watchlist` (the curated `list` component, keyed by
`(platform, platform_channel_id)`).

---

## Developer Guide / Operational Metrics (Prometheus)

Source: https://docs.lumio.vision/developer-guide/metrics

# Operational Metrics (Prometheus)

Every Rust service exposes a Prometheus `/metrics` endpoint backed by the shared
`crates/lo-metrics` crate. This is **stage 1** of the observability plan
(ZAF-672): the instrumentation and the exposition format only. The *production*
scraping, dashboards, alerting and retention backend is stage 2 and is
intentionally **not** covered here - but a throwaway local Prometheus + Grafana
for developers is (see [Viewing metrics locally](#viewing-metrics-locally-dev-stack)).

Metrics are **operational telemetry**, distinct from the product time-series in
TimescaleDB (`channel_history*`) and from Sentry (which catches crashes, not
*degradation*). They emit **no audit event** - the audit log is a security
record, not a telemetry stream.

## What each service exposes

`lo-metrics` registers the same baseline in every service, plus any
service-specific series:

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `http_requests_total` | counter | `method`, `endpoint`, `status` | HTTP requests handled |
| `http_request_duration_seconds` | histogram | `method`, `endpoint` | Request latency (buckets 5 ms → 10 s) |
| `redis_commands_total` | counter | `operation`, `outcome` (`ok`/`timeout`/`error`) | Redis commands issued by the shared `lo-cache` client. `operation` is a bounded command name (`get`, `set`, `check_rate_limit`, `incr_with_expiry`, `pubsub_publish`, …) — never a key or id. Makes "Redis is slow / timing out" measurable rather than inferred (ZAF-1531/1532) |
| `redis_command_duration_seconds` | histogram | `operation` | Redis command round-trip latency (buckets 0.5 ms → 5 s) |
| `platform_api_requests_total` | counter | `platform`, `endpoint`, `outcome` | Outgoing platform API requests, including Kick ad-break polls and YouTube revenue calls. YouTube uses bounded endpoint labels `youtube_analytics/reports` (batched revenue and Partner Program checks), `youtube/videos` (video-existence checks) and `google/oauth_revoke` (grant revocation), with `platform="youtube"`. Shopify (`platform="shopify"`) counts every Admin API response on `/admin/api/{version}/graphql.json` and `/admin/oauth/access_token`; `outcome="forbidden"` is a `403`, typically an IP allowlist without this host's egress address ([Shopify → Monitoring](../features/shopify.md#monitoring)). `outcome` records success or the error class. No channel, account or session ID appears in labels. |
| `process_cpu_seconds_total` | counter | - | Process CPU time (Linux) |
| `process_resident_memory_bytes` | gauge | - | Resident memory (Linux) |
| `process_open_fds` / `process_max_fds` | gauge | - | Open / max file descriptors (Linux) |
| `process_start_time_seconds` | gauge | - | Process start time (Linux) |

Every series additionally carries two **constant labels** applied by the shared
registry:

- `service` - the logical service name (`api`, `twitch-bot`, `crawler-twitch`, …).
- `env` - the deployment environment (`staging`, `prod`, …), sourced from the
  service's Sentry environment.

`process_*` metrics come from the `prometheus` process collector and are
Linux-only (every Lumio Rust build target is Linux).

### The API's live gauges

`apps/api` registers a pull-time collector that reads the running `AppState` on
every scrape and exposes it as these gauges. Being live values, they are read at
scrape time from a `prometheus::core::Collector`, not eagerly updated; every read
is lock-free (atomic `WsServer` counters and `sqlx` pool counters), so a scrape
never contends with the WebSocket broadcast hot path.

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `lumio_build_info` | gauge | `version` | Constant `1`; running build version in the label |
| `lumio_uptime_seconds` | gauge | - | Seconds since the API process started |
| `lumio_websocket_sessions` | gauge | - | Active WebSocket sessions |
| `lumio_websocket_channels` | gauge | - | Active WebSocket broadcast channels |
| `lumio_db_pool_connections` | gauge | `pool` | Connections owned by the pool (`postgres`, `timescaledb`) |
| `lumio_db_pool_idle` | gauge | `pool` | Idle connections available for checkout |

The WebSocket, version and uptime values are also served as JSON on
`GET /v1/health`. These were ZAF-646's operational gauges; ZAF-674 retired their
hand-rolled public `/metrics`, and this collector re-registered them onto the
shared registry (ZAF-685) so they render on the internal endpoint again.

### The crawler's series

`apps/crawler-twitch` registers ~30 `crawler_*` counters/gauges into the same
registry (discovery/roster coverage, Helix + reputation alarms, IRC/JOIN health,
bus + writer pipeline, drop policy). These names are an **arming precondition**
for live global ingest (ZAF-595 §7) and are **stable** - a rename silently breaks
that promise, so it must be called out explicitly in the PR that makes it. The
one labelled series is `crawler_bus_dropped_total{kind}`: events dropped because
the bounded result bus was full, labelled by event kind (`stream`, `chat`,
`panels`, `channel_metrics`, `channel_profile`). The thresholds that gate global
scope are in the crawler's
[arming check](./public-stats-crawler.md#arming-check). Before
ZAF-674 these were hand-rolled `AtomicU64` counters rendered to text by hand;
they now live in the shared registry with no name change.

### The API's domain series (ZAF-680)

The API also exposes `id_turnstile_verify_total{action,outcome}`. The `action` label is a fixed sign-in or email-setup action; `outcome` is one of `passed`, `skipped`, `missing`, `rejected`, `wrong_action`, `wrong_hostname`, or `unavailable`. Neither label contains an account, address or IP. Use the counter to distinguish user challenges from site verification failures.

`apps/api` registers domain series into the same registry so ZAF-676 can alarm on
signals the HTTP status class structurally cannot see. All labels are bounded
enumerations - never an id.

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `ws_sessions_active` | gauge | - | Live WebSocket sessions (was JSON-only on `/v1/health`, ZAF-646) |
| `ws_channels_active` | gauge | - | Live broadcast channels with ≥1 subscriber |
| `ws_sessions_opened_total` | counter | - | Sessions opened since start (churn numerator) |
| `ws_sessions_closed_total` | counter | - | Sessions closed since start. `ws_sessions_active` high while this rate → 0 is the ZAF-396 leak ("session steht seit 72 h") |
| `ws_outbound_dropped_total` | counter | - | Forwarders dropped because the session outbound queue was full (the wedged/slow-consumer path) |
| `ws_broadcast_lagged_total` | counter | - | Subscribers that fell behind the broadcast ring and lost messages |
| `ws_idle_reaped_total` | counter | - | Sessions torn down by the idle (client-timeout) reaper |
| `ws_subscribe_frames_total` | counter | `outcome` (allowed/rate_limited) | `subscribe`/`unsubscribe` frames checked against the per-session token bucket (ZAF-1822). A sustained `rate_limited` rate means a client is cycling subscriptions; see [WebSocket → Subscribe rate limit](../api-reference/websocket.md#subscribe-rate-limit) |
| `ws_relay_connected` | gauge (0/1) | - | Whether the Redis → WebSocket event relay holds a live subscription. `0` means **no** relayed event reaches **any** client (ZAF-1226) |
| `ws_relay_reconnects_total` | counter | - | Times the relay lost its Redis subscription and reconnected. A sustained rate means a flapping Redis link |
| `ws_relay_messages_total` | counter | - | Messages relayed from Redis pub/sub onto WebSocket broadcast channels |
| `api_rate_limit_bucket_total` | counter | `bucket` (internal_anon/proxied/anon), `outcome` (allowed/rejected) | Anonymous requests counted by the inbound rate limiter, by the bucket they landed in (see [Authentication → Rate Limits](../api-reference/authentication.md#rate-limits)). Recorded from `lo-api` through a process-global recorder, like `redis_commands_total`. A `rejected` rise on `internal_anon` means first-party servers are calling without forwarding a visitor; each such rejection is also logged at `warn` |
| `graphql_requests_total` | counter | `op_type` (query/mutation), `outcome` (ok/error) | GraphQL outcome - GraphQL answers HTTP 200 on error, so `status` can't see a GraphQL failure |
| `db_pool_connections` | gauge | `pool` (primary/tsdb), `state` (total/idle) | Live sqlx pool connections, sampled every 15 s |
| `db_pool_max_connections` | gauge | `pool` | Configured `max_connections` ceiling per pool |
| `shopify_client_secret_matches_total` | counter | `verifier` (id_token/webhook), `secret` (current/previous) | Verified Shopify signatures, by the client secret that matched. `secret="previous"` stays at its value once Shopify no longer signs with the old secret; then remove `client_secret_previous`. See [Shopify → Client-secret rotation](../features/shopify.md#client-secret-rotation) |
| `kick_webhook_public_key_refresh_total` | counter | `trigger` (scheduled/on_demand), `outcome` (changed/unchanged/fetch_failed) | Fetches of Kick's webhook public key (ZAF-1614) |
| `kick_webhook_public_key_age_seconds` | gauge | - | Seconds since the Kick webhook key in use was fetched; `0` = pinned, `-1` = no key (every Kick delivery gets 401). See [Kick Webhook Public Key](./kick-webhook-public-key.md) |
| `platform_webhook_deliveries_total` | counter | `platform` (kick), `outcome` (stored/duplicate/unchanged/unmapped/unrouted/parse_failed/error) | Signed platform webhook deliveries by what the receiver did with them (ZAF-1632). Only `error` is answered 500; every other outcome answers 200. `parse_failed` = not JSON, missing type header, or a payload that does not match its documented shape (stored raw). `unchanged` = a metadata update with nothing changed against the stored baseline (not stored). The event type is in the log, never a label. See [Webhooks](../features/webhooks.md#kick) |
| `kick_chat_ws_connected` | gauge | - | Open connections of the Kick chat-moderation listener (ZAF-1653). See [Kick Chat-Moderation Listener](./kick-chat-listener.md#metrics) |
| `kick_chat_ws_events_total` | counter | `event` (message_deleted/user_unbanned/chat_message/user_banned/other/unknown), `outcome` (applied/noop/duplicate/dropped/malformed/unrouted/overflow/error) | Events on Kick's unofficial chat socket and what the listener did with them |
| `kick_realtime_credentials_source` | gauge | `source` (override/redis/fetch/cold_boot) | `1` for the source of the Kick Pusher key in use |
| `kick_realtime_pusher_offered` | gauge | - | `1` while kick.com still offers the Pusher provider, `0` once it stops |
| `kick_realtime_credentials_refresh_total` | counter | `outcome` (changed/unchanged/not_offered/fetch_failed) | Leader refresh cycles of the Kick Pusher key |
| `seventv_events_connections` | gauge | - | Open EventAPI connections on this API replica |
| `seventv_events_subscriptions` | gauge | - | 7TV EventAPI subscriptions held by the listener |
| `seventv_events_dispatch_total` | counter | `outcome` (emitted/ignored/parse_error/dropped) | Dispatches that stored a row, needed no row, failed parsing, or were lost because the listener's dispatch queue was full. Any `dropped` increase is a 7TV change that never reached history — worth alerting on |
| `seventv_events_reconnect_total` | counter | - | EventAPI connection reconnects |
| `chatters_snapshot_lag_seconds` | histogram | `platform`, `outcome` (seen/missed) | Seconds until a platform chatter snapshot first shows someone who already wrote (`seen`), or until such a writer left without any snapshot showing them (`missed`). The Helix-lag number behind the IRC-fallback decision. See [Chatter List](../features/chatter-list.md#metrics) |
| `chatters_snapshot_requests_total` | counter | `platform`, `outcome` (ok/missing_scope/not_connected/error) | Platform chatter-list reads. Flat while no chatter panel is open and no live-polled account is live (the poller runs on an open panel or, with `[chatters] live_polling`, on a live stream of an account that used the list in the last 7 days) |
| `youtube_channel_feed_fetches_total` | counter | `outcome` (ok/ok_retried/http_error/transport_error/parse_error) | Fetches of the public YouTube channel Atom feed, the quota-free like/view fallback behind InnerTube (at most one per live YouTube channel every 15 min; one count per fetch, however many of its up to 4 requests it took). `http_error` with no `ok` means YouTube stopped serving the feed (ZAF-1876); a share of `ok_retried` means YouTube serves it only on some connections and the retry bridged the gap (ZAF-2233). See [YouTube Streaming → Channel-feed fallback](../features/youtube-streaming.md#channel-feed-fallback) |

The WebSocket counters were the quietest paths in the layer before ZAF-680:
`ws_outbound_dropped_total` had **neither log nor metric**, `ws_broadcast_lagged_total`
had only a `warn!`, and `ws_idle_reaped_total` only an `info!`.

The `ws_relay_*` series cover the tier below a session: the **single** relay task
that feeds every WebSocket channel from Redis. A stalled relay and a genuinely
quiet hour used to look identical from outside the process, which is why the
ZAF-1226 stall stayed invisible for days at a time. Alarm on
`ws_relay_connected == 0`, and treat `ws_relay_connected == 1` with
`rate(ws_relay_messages_total[15m]) == 0` during known-live traffic as the
softer variant of the same failure.

### Chat-domain series (ZAF-680 §2)

`crates/lo-chat` registers a `ChatMetrics` handle (defined once, shared by the
`apps/api` chat-flush worker and the `ProfileService`) so chat-pipeline lag,
flush health and ProfileService behaviour become scrapeable. They feed ZAF-676
§4. All labels are bounded - never an account/user/channel id.

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `chat_buffer_depth` | gauge | - | Messages waiting in Redis live buffers (`lumio:chat:buffer:*`), summed across accounts. Measured **from Redis** (index set `lumio:chat:buffer:pending` + pipelined `LLEN`; a full `SCAN` only at worker start and ~15 min later) every ~30s after the flush pass, on every replica - so a buffer orphaned by a dead worker or another process shows up instead of reading `0` (ZAF-1569). A value that keeps rising = messages are not reaching TimescaleDB |
| `chat_pending_accounts` | gauge | - | Accounts with a non-empty Redis live buffer, from the same measurement |
| `chat_flush_duration_seconds` | histogram | - | Per-account TimescaleDB batch-insert (flush) duration |
| `chat_messages_flushed_total` | counter | - | Messages successfully inserted into TimescaleDB |
| `chat_messages_dropped_total` | counter | `reason` (`dead_letter`/`lost`/`push_failed`) | Messages that never reached TimescaleDB - parked after the retry ceiling (`dead_letter`, recoverable), lost when insert + dead-letter + re-queue all failed (`lost`), or lost at ingest when the buffer push **and** its direct-insert fallback both failed (`push_failed`, ZAF-1570) |
| `chat_buffer_push_failures_total` | counter | `outcome` (`direct_insert`/`lost`) | Ingest-time Redis buffer pushes that failed, on every chat ingest path (REST, GraphQL, Kick webhook, Twitch and YouTube workers). `direct_insert` = rescued by the synchronous TimescaleDB fallback (Redis is refusing writes, nothing lost); `lost` = the fallback failed too (message loss, also counted as `chat_messages_dropped_total{reason="push_failed"}`). Any increase is worth alerting on (ZAF-1570) |
| `chat_dead_letter_depth` | gauge | - | Messages parked in Redis dead-letter lists, summed across accounts, measured from Redis every ~30s on every replica (independent of which replica holds the drain lock). Distinct from `chat_messages_dropped_total{reason=dead_letter}` (a monotonic count of *parking events*): this gauge is the *live* backlog awaiting replay. `> 0` that does not fall back to `0` = a batch is stuck un-replayable — a parked chat window is still invisible (ZAF-1565) |
| `chat_dead_letter_recovered_total` | counter | - | Messages replayed out of a dead-letter list back into TimescaleDB by the drain worker. `rate(...) > 0` confirms the recovery path is clearing parked batches (ZAF-1565) |
| `chat_tally_dropped_total` | counter | `reason` (`cap`/`restore`) | Chatters the in-process chatter tally (`lo_chat::ChatterTally`) did not hold because it was at its cap of 250 000 distinct chatters per process: `cap` = a message from a new sender at ingest, `restore` = a row of a failed `platform_users` write handed back. Each drop loses that chatter's message count for the tick. Any increase means flush ticks are stalling or Postgres writes are failing (ZAF-2248) |
| `chat_flush_worker_restarts_total` | counter | - | Times the supervisor restarted the flush worker after a panic or unexpected exit. Any increase is an `error!`-level event worth alerting on (ZAF-1569) |
| `profile_service_cache_total` | counter | `result` (`hit`/`miss`) | ProfileService Redis cache lookups (was a `debug!` that never fires normally) |
| `profile_service_circuit_trips_total` | counter | `platform` | ProfileService circuit-breaker trips (also `platform="kick"` for the Kick website badge endpoints, ZAF-1622). A counter, not a live gauge: the breaker opens on an explicit event but closes silently via Redis TTL expiry, so only the trip is observable without per-account state |
| `chat_ingest_failures_total` | counter | `platform`, `outcome` (`decode_error`) | Platform chat events that could not be processed and were dropped - today a Kick `chat.message.sent` payload that does not decode. Kick is still answered `200`, so any increase is silent data loss worth alerting on (ZAF-1622) |
| `chat_emote_set_fetch_total` | counter | `platform`, `outcome` (`ok`/`empty`/`not_found`/`challenge`/`unrecognised`/`error`/`no_slug`) | Native platform emote-set fetches (Kick: undocumented `kick.com/emotes/{slug}`). Fail-open: a non-`ok` outcome means the emote menu serves Kick's catalog rows with a 5-minute cache; each one is also logged at `warn` with slug and HTTP status. `challenge` = Cloudflare answered instead of Kick (`cf-mitigated: challenge`, or HTML with `200`) |
| `chat_sub_badge_fetch_total` | counter | `platform`, `outcome` (`ok`/`not_found`/`error`/`circuit_open`/`busy`) | Background per-channel sub-badge image fetches (Kick `subscriber_badges`) |
| `chat_identity_badge_fetch_total` | counter | `platform`, `outcome` (`ok`/`not_found`/`error`/`circuit_open`/`busy`) | Background per-user global-badge fetches (Kick `badges_v2`: level, founder …) |
| `chat_identity_badge_cache_total` | counter | `platform`, `outcome` (`hit`/`miss`) | Ingest-time global-badge cache reads; a miss schedules a background fetch and the message goes out without the global badge |

### Platform-event series (ZAF-2187)

`crates/lo-events` registers `EventMetrics` for the durable event path
(`lo_events::persist_event` and the `apps/api` event retry worker). See
[Chat and event durability](./ingest-durability.md). No account label.

| Metric | Type | Labels | Meaning |
|--------|------|--------|---------|
| `events_persist_failures_total` | counter | `outcome` (`parked`/`recovered`/`lost`/`rejected`) | Platform-event inserts that failed, by how they ended: `parked` = transient TimescaleDB error, event parked in `lumio:events:deadletter:*` for replay; `recovered` = a parked event was replayed (or found already stored); `lost` = park failed too, the replay hit a permanent error, or the event outlived the 72 h replay window; `rejected` = permanent error (bad data), not parked. Any `lost` is event loss worth alerting on |
| `events_dead_letter_depth` | gauge | - | Platform events parked in Redis dead-letter lists, summed across accounts, measured from Redis every 30 s on every replica. `> 0` that does not fall back to `0` = replay is stuck |

### Platform-bot series (ZAF-680 §3)

Each platform bot registers the `lo-bot-commands` metric handles for the
constructs it actually has - a bot never registers a series it cannot drive (no
0-by-construction line). They feed ZAF-676 §5. The single bounded `platform`
label is the one dimension the cardinality rule allows.

| Metric | Type | Labels | Bots | Meaning |
|--------|------|--------|------|---------|
| `bot_reconnects_total` | counter | `platform` | twitch, kick (outer retry loop); discord (gateway `Resume`) | Reconnect / leader-handover churn. **youtube-bot** runs `Bot::run()` once (no restart loop) - its gRPC re-opens are by-design ~10 s cycling, not churn - so it registers no reconnect series |
| `bot_leader` | gauge (0/1) | `platform` | twitch, youtube, kick | Whether this replica holds the leader lock. Two replicas both reporting `1` = split-brain (`LeaderElection`'s `is_leader` was exported nowhere before) |
| `bot_chat_messages_dropped_total` | counter | `platform`, `outcome` (`ingest_full`/`channel_queue_full`) | twitch | Incoming chat messages shed under backpressure (drop newest). `ingest_full` = the bounded ingest queue between the IRC client and the dispatcher (4096) was full; `channel_queue_full` = that channel's ordered worker queue (128) was full. Any sustained non-zero rate means the bot cannot keep up with chat. The channel is never a label |
| `bot_sync_consecutive_failures` | gauge | `platform` | kick, youtube | Consecutive channel-sync failures (0 when healthy) |
| `bot_sync_attempts_total` | gauge | `platform` | kick, youtube | Total channel-sync attempts (success + failure) |
| `bot_sync_last_success_unix` | gauge | `platform` | kick, youtube | Unix timestamp of the last successful channel sync (0 = never) |
| `bot_sync_channels_active` | gauge | `platform` | kick, youtube | Channels active after the last successful sync |
| `bot_sync_channels_skipped` | gauge | `platform` | kick, youtube | Channels dropped in the last sync for missing provisioning data |

The `bot_sync_*` gauges mirror the `SyncHealth` atomics (kick/youtube) that
previously surfaced only as JSON on `/ready`. **twitch-bot** has no `SyncHealth`
(it joins via anonymous IRC, not the `fetch_channels` loop) and **discord-bot**
has neither leader election nor a channel-sync loop, so each registers only the
series that applies to it.

## The cardinality rule (hard, day 1)

A Prometheus series is created per unique label-value combination. High-cardinality
labels are *the* way to kill Prometheus - and across tens of thousands of crawled
channels a per-channel label would be the normal case, not an edge case.

**Never** use as a label:

- `account_id`, `channel_id`, `user_id`, `session_id`
- **raw URL paths** (`/v1/users/abc-123`)

**Allowed** labels:

- `service`, `env`, `platform`
- `endpoint` - the **template route** (`/v1/users/{id}`), never the concrete path
- status class (`2xx`, `3xx`, `4xx`, `5xx`) - plus `429`, broken out of the
  `4xx` class because rate-limiting is operational backpressure, not a client
  error, and needs a dedicated alarm (ZAF-680)
- `outcome`
- `method` - the bounded HTTP verb
- `state`, `pool`, `op_type` - bounded enumerations (see the API/WebSocket series
  below)

The `RequestMetrics` middleware enforces the route rule by labelling on Actix's
`match_pattern()` (the template), so `/v1/users/alice` and `/v1/users/bob`
collapse to a single `endpoint="/v1/users/{id}"` series. Requests that match no
route are bucketed as `endpoint="<unmatched>"` rather than leaking the raw path.

## `/metrics` is not publicly exposed

`/metrics` is an **operations endpoint** - metric names and route lists are recon
material - so it is never reachable via the public ingress. Two service shapes,
one rule: the scrape endpoint never sits unauthenticated next to payload routes.

**A. Health-only internal server (bots, crawler).** These services' only HTTP
surface *is* an internal `/health` server that the public ingress does not route
and that carries no payload routes; `/metrics` is mounted next to `/health`
there. The **effective** bind ports come from each service's `config/default.toml`
(the TOML layer overrides the Rust struct default), so read that, not the struct
default, when configuring a scraper:

| Service | `/metrics` bind (`default.toml`) |
|---------|--------------------------------|
| `twitch-bot` | `0.0.0.0:3001` |
| `youtube-bot` | `0.0.0.0:3002` |
| `kick-bot` | `0.0.0.0:3003` |
| `discord-bot` | `0.0.0.0:3005` |
| `crawler-twitch` | `0.0.0.0:8080` |

**B. Separate internal metrics server (`apps/api`, workers, `innertube-proxy`).**
These services serve **payload / handler routes on their main port**, so
`/metrics` must **not** ride it - a co-located scrape endpoint would be
unauthenticated next to those routes (`apps/api`'s `/v1/health` is on the public
ingress; the workers' payload is system-key-gated per handler; the proxy's
`POST /player` is bearer-gated per handler on a publicly published port). Each
therefore serves `/metrics` from a **separate internal server bound to loopback
by default** (`lo_metrics::serve`), with the `RequestMetrics` middleware still
recording latency/status on the main server:

| Service | `/metrics` bind (default) | Host / port override |
|---------|--------------------------|----------------------|
| `apps/api` | `127.0.0.1:9100` | `LUMIO__METRICS__HOST` / `__PORT` |
| `bot-module-worker` | `127.0.0.1:9100` | `BOT_MODULE_WORKER__METRICS__HOST` / `__PORT` |
| `automation-worker` | `127.0.0.1:9100` | `AUTOMATION_WORKER__METRICS__HOST` / `__PORT` |
| `innertube-proxy` | `127.0.0.1:9100` | `METRICS_ADDR` (single `host:port`) |

**`9100` is the single dedicated metrics port** for every service that runs a
separate metrics server - `apps/api` set the pattern (ZAF-683). One port for all
is collision-free because each service runs in its own container (the same way the
bots would share `3001`–`3005` if they could); only a scraper needs to know one
port, not four. For local development that runs several of these as **processes on
one host**, override the port per process via `[metrics] port` (workers /
`apps/api`) or `METRICS_ADDR` (`innertube-proxy`).

`apps/api` configures this under `[metrics]`; the workers under their own
`[metrics]` section; `innertube-proxy` via the `METRICS_ADDR` env var:

```toml
[metrics]
enabled = true
host = "127.0.0.1"  # loopback — internal only; a scraper overrides this
port = 9100
```

### Reaching a loopback endpoint from another container

Loopback (`127.0.0.1`) is the safe default, but **a Prometheus running in a
different container cannot reach another container's loopback**. To let a scraper
in, bind the metrics server to `0.0.0.0` via the host override - e.g.
`LUMIO__METRICS__HOST=0.0.0.0` for `apps/api`, `BOT_MODULE_WORKER__METRICS__HOST=0.0.0.0`
for the worker, or `METRICS_ADDR=0.0.0.0:9100` for the proxy - and then publish
that metrics port **only** to the scraper's network, never on the public ingress.
The security here is carried by **network isolation** (an unpublished/internal
port), not by the bind address: `0.0.0.0` is the intended, supported way to expose
the scrape endpoint to an in-cluster Prometheus.

## Fail-open

No request-handling error path depends on metric collection (the same discipline
as GeoIP in the audit path). The `RequestMetrics` middleware only records *after*
the inner service resolves, with fixed label arity, so it can neither fail nor
delay a request. Registry construction and metric registration ignore duplicate
errors so they never abort service startup, and rendering a scrape returns an
empty body rather than surfacing an encode error.

## Viewing metrics locally (dev stack)

The scrape endpoints are useless on a laptop without something to read them. A
throwaway Prometheus + Grafana ships in the dev stack for exactly this:

```sh
just observability-up      # Grafana http://localhost:3009 · Prometheus http://localhost:9090
just observability-down    # stop it (add `-v` on the compose to wipe the volumes)
```

This is **not** the staging stack (`dev-stack/staging/`, ZAF-675) - it is a
separate, minimal `dev-stack/observability.docker-compose.yml`:

- **Host networking (Linux).** Local services run as processes on your host, not
  in containers, so Prometheus scrapes `localhost:<port>` directly. A service
  bound to its default `127.0.0.1` is reachable as-is - you do **not** need to set
  `LUMIO__METRICS__HOST=0.0.0.0` the way the containerised staging stack does.
  On Docker Desktop (macOS/Windows), host networking behaves differently; use the
  staging pattern (bridge network + `host.docker.internal`) instead.
- **Targets** are `api` (`:9100`) and the five bots (`:3001`–`:3005`). Anything you
  are not currently running shows as `up == 0` - expected on a dev box, and not the
  "silent dead target" problem the staging config guards against. The crawler and
  the workers/proxy (which share `:9100` with the api) are commented out in
  `dev-stack/observability/prometheus.yml` with instructions to enable them.
- **Grafana** loads the same three dashboards as staging (single-sourced from
  `dev-stack/staging/observability/grafana/dashboards`) and runs with anonymous
  admin + no login - a local-only convenience that is explicitly **disabled** in
  staging. Both UIs bind to `127.0.0.1` only.

Prefer a one-off check without the stack? `curl -s localhost:9100/metrics` (api)
or `curl -s localhost:3001/metrics` (twitch-bot) prints the raw exposition.

## Adding metrics to a service

```rust
// Build one registry per process (service name + environment label).
let metrics = lo_metrics::Metrics::new("my-service", &settings.sentry.environment);

// Shape A — a health-only internal server (no payload routes): mount /metrics
// next to /health on that server.
App::new()
    .wrap(lo_metrics::RequestMetrics::new(&metrics))   // http_* series
    .service(lo_metrics::metrics_route(metrics.clone())) // GET /metrics
```

If the server also carries **payload / handler routes** (shape B above), do **not**
`.service(metrics_route(..))` it there - that puts an unauthenticated `/metrics`
next to them. Keep the `RequestMetrics` middleware on the payload server, but serve
the scrape endpoint from a separate internal server:

```rust
// Loopback-bound scrape endpoint on its own port; spawn alongside the main server.
if cfg.metrics.enabled {
    if let Ok(server) = lo_metrics::serve(metrics.clone(), &cfg.metrics.host, cfg.metrics.port) {
        tokio::spawn(server);
    }
}
```

To declare a service-specific series, register it into the shared registry so it
renders alongside everything else:

```rust
use lo_metrics::IntCounter;

let jobs_total = IntCounter::new("myservice_jobs_total", "Jobs processed")
    .expect("valid metric");
let _ = metrics.registry().register(Box::new(jobs_total.clone()));
jobs_total.inc();
```

Adding a metrics dependency pulls a new `prometheus` (+ `procfs`) into the graph:
hand-add it to the affected `BUILD.bazel` and run `just bazel-vendor`, or CI's
**Vendor Check** goes red.

## Out of scope (stage 2+)

Scraper, Grafana, alert rules, retention (ZAF-672 stage 2/3). OpenTelemetry /
distributed tracing is deliberately excluded - the door stays open via
`tracing-opentelemetry`, but an OTel collector is another stateful hop.

---

## Developer Guide / Platform Stream Debuggers

Source: https://docs.lumio.vision/developer-guide/platform-stream-debuggers

# Platform Stream Debuggers

CLI tools for inspecting live platform event streams in real time. Each debugger connects directly to a platform's streaming API, subscribes to all event types, and prints every incoming event with its type, timestamp, and payload.

Both tools read credentials from the database using the same config as the API server.

## Shared Prerequisites

- The API database must be accessible (PostgreSQL)
- A valid `channel_connection` must exist for the account on the target platform
- The `token_encryption_key` in the config must match the key used to encrypt stored tokens
- The API's Token Refresh Worker should be running (`just dev-api`) to keep tokens fresh

## Shared Options

| Flag | Description |
|------|-------------|
| `--account <uuid>` | **Required.** Account UUID whose credentials to use. |
| `--config <path>` | Config directory holding `config/default.toml` + `config/local.toml`. Defaults to the `apps/api` crate directory, baked in at compile time. |
| `--raw` | Print full raw output for every event. |

Both binaries `chdir` into the config directory before loading `Settings`, so they work from any working directory without `--config`.

## Troubleshooting

| Symptom | Cause |
|---------|-------|
| `"configuration file not found"` | The `--config` directory has no `config/` subtree - point it at `apps/api` or drop the flag to use the default |
| `"Failed to get token: invalid key length"` | `token_encryption_key` is empty or missing in config |
| `"Failed to get token: decryption failed"` | `token_encryption_key` does not match the key used to encrypt stored tokens |
| `"invalid authentication credentials"` | Token is expired - ensure the Token Refresh Worker is running |

---

## YouTube gRPC Debugger

Connects to YouTube's `liveChatMessages.streamList` gRPC API and prints every incoming chat message and event.

### Usage

```bash
cargo run -p lumio-api --bin grpc-debug -- --account <uuid>

# Explicit live chat ID (skip broadcast discovery)
cargo run -p lumio-api --bin grpc-debug -- --account <uuid> --live-chat-id <id>
```

### Additional Options

| Flag | Description |
|------|-------------|
| `--live-chat-id <id>` | Skip broadcast discovery and connect directly to this chat. |

### How It Works

1. Looks up the YouTube `channel_connection` for the account
2. Decrypts the OAuth access token from the database
3. Discovers active broadcasts via the YouTube Data API (or uses `--live-chat-id`)
4. Opens a gRPC `streamList` connection and prints every incoming item
5. On disconnect, fetches a fresh token and reconnects automatically

### Output

```
[resp #1] items=42 next_page=true offline=false
  [0] TextMessageEvent | id=abc123 | 2026-05-05T12:00:00Z | Username (UC...)
       text: Hello world
       detail: text: Some("Hello world")
  [1] SuperChatEvent | id=def456 | 2026-05-05T12:01:00Z | Supporter (UC...)
       text: Great stream!
       detail: amount: Some(5000000) Some("EUR")
```

Unknown event types show their numeric value with automatic raw output:

```
  [0] UNKNOWN(25) | id=xyz789 | 2026-05-05T12:02:00Z | ? (?)
       raw: LiveChatMessage { ... }
```

### YouTube Event Types

| Type | Description |
|------|-------------|
| `TextMessageEvent` | Regular chat message |
| `SuperChatEvent` | Paid Super Chat |
| `SuperStickerEvent` | Paid Super Sticker |
| `NewSponsorEvent` | New channel member |
| `MemberMilestoneChatEvent` | Membership anniversary message |
| `MembershipGiftingEvent` | Gift memberships sent |
| `GiftMembershipReceivedEvent` | Gift membership received |
| `MessageDeletedEvent` | Message deleted by moderator |
| `MessageRetractedEvent` | Message retracted by author |
| `UserBannedEvent` | User banned (permanent or temporary) |
| `PollEvent` | Chat poll |
| `ChatEndedEvent` | Stream ended |
| `SponsorOnlyModeStartedEvent` | Members-only mode enabled |
| `SponsorOnlyModeEndedEvent` | Members-only mode disabled |
| `Tombstone` | Deleted message placeholder |
| `FanFundingEvent` | Legacy fan funding |

---

## Twitch EventSub Debugger

Connects to Twitch's EventSub WebSocket, subscribes to all event types for the account's channel, and prints every incoming notification.

### Usage

```bash
cargo run -p lumio-api --bin eventsub-debug -- --account <uuid>
```

| Flag | Description |
|------|-------------|
| `--raw` | Print the full raw JSON of every event. |
| `--config <dir>` | Directory with `config/default.toml` / `config/local.toml`. Defaults to `apps/api`. |
| `--watch-channel <login>` | Read **another** channel's chat instead of the account's own. Subscribes only to `channel.chat.notification` for that Twitch login, read as the account's connected user (the connection token needs `user:read:chat`), and prints every notice with its raw payload. Use it to capture notice types Twitch has not documented yet from a channel where they occur. |
| `--automod` | AutoMod capture. Subscribes only to `automod.message.hold` / `automod.message.update` (v2) and `channel.chat.message` on the account's own channel and prints every event raw. The channel connection needs `moderator:manage:automod`; reconnect it once if it was granted before that scope was requested. Cannot be combined with `--watch-channel`. |

```bash
cargo run -p lumio-api --bin eventsub-debug -- --account <uuid> --watch-channel ronnygolisch
```

### How It Works

1. Looks up the account's Twitch `channel_connection`
2. Decrypts its OAuth access token and resolves the client ID from the app that issued the token: the connection's pinned `credential_source` picks the global Lumio app from `[auth]` (`system`, the Twitch default) or the account's `app_credentials` row (`account`). The header line `Credentials:` shows which one is used
3. Connects to the EventSub WebSocket and receives a session ID
4. Subscribes to all event types via the Helix API
5. Prints every incoming event with type, user, and a human-readable summary
6. On disconnect, fetches a fresh token and reconnects automatically
7. Handles Twitch `session_reconnect` inside the EventSub client: it opens the new URL and closes the old connection after the new welcome, and the subscriptions carry over

### Output

```
[eventsub] Connected (session: abc123)
[eventsub] Subscribed to 25 event types
[#1] 14:32:05 | channel.chat.message | Username
       chat: Hello everyone!
[#2] 14:32:08 | channel.follow | NewFollower
       new follower
[#3] 14:32:15 | channel.subscribe | Subscriber
       tier 1000 sub
[#4] 14:33:01 | channel.raid | OtherStreamer
       raid with 150 viewers
[#5] 14:33:45 | channel.ban | ModName
       timeout: spam
[#6] 14:34:00 | stream.offline |
       stream went OFFLINE
```

### Twitch Event Types

| Type | Description |
|------|-------------|
| `channel.chat.message` | Chat message |
| `channel.chat.message_delete` | Single message deleted by a moderator |
| `channel.chat.notification` | Sub, resub, gift sub, raid notice in chat |
| `channel.follow` | New follower |
| `channel.subscribe` | New subscription |
| `channel.subscription.gift` | Gift subscriptions |
| `channel.subscription.message` | Resub message |
| `channel.cheer` | Bits cheer |
| `channel.raid` | Incoming raid |
| `channel.ban` | User banned or timed out |
| `channel.unban` | User unbanned |
| `channel.moderate` | Moderator action |
| `channel.channel_points_custom_reward_redemption.add` | Channel point redemption |
| `channel.channel_points_custom_reward_redemption.update` | Redemption fulfilled or canceled |
| `channel.channel_points_custom_reward.add/update/remove` | Custom reward created, changed or deleted |
| `channel.poll.begin/progress/end` | Poll lifecycle |
| `channel.prediction.begin/progress/lock/end` | Prediction lifecycle |
| `channel.hype_train.begin/progress/end` | Hype train lifecycle |
| `channel.goal.begin/progress/end` | Goal lifecycle |
| `channel.update` | Stream title/category/language change (tags read from Helix, see [Events → Stream update payloads](../features/events.md#stream-update-payloads-twitchstream_update-kickstream_update)) |
| `channel.ad_break.begin` | Ad break started |
| `channel.suspicious_user.message` | Suspicious user message |
| `channel.suspicious_user.update` | Suspicious user status change |
| `stream.online` | Stream went live |
| `stream.offline` | Stream ended |

---

## Developer Guide / npm Package Publishing

Source: https://docs.lumio.vision/developer-guide/npm-publishing

# npm Package Publishing

How to publish `@zaflun/lumio-*` packages to npmjs.com.

## Packages

| Package | npm Name | Directory |
|---------|----------|-----------|
| Protocol | `@zaflun/lumio-protocol` | `packages/protocol` |
| Extension Types | `@zaflun/lumio-extension-types` | `packages/extension-types` |
| SDK | `@zaflun/lumio-sdk` | `packages/sdk` |
| Devkit | `@zaflun/lumio-devkit` | `packages/devkit` |
| CLI | `@zaflun/lumio-cli` | `packages/cli` |
| Agent Skill | `@zaflun/lumio-agent-skill` | `packages/agent-skill` |

Each package carries its **own independent SemVer** (`0.x` / `1.x` …), NOT the Lumio `YYYY.M.PATCH` product version, and is **not** in lockstep with the API or the apps. Bump a package's `version` in the same pull request that changes it - unlike the product version, which the release step owns.

## Prerequisites (one-time setup)

Publishing uses **npm Trusted Publishing** (OIDC). There is no npm token and no `NPM_TOKEN` secret: the job requests `id-token: write`, and the npm CLI exchanges the GitHub OIDC token for a short-lived publish token that is valid for one package and one run.

1. **npm Organization:** the `@zaflun` org on npmjs.com, with the package maintainer as a member.
2. **Trusted publisher, once per package:** on the package page → **Settings** → **Trusted Publisher** → **GitHub Actions**:

   | Field | Value |
   |-------|-------|
   | Organization or user | `zaflun` |
   | Repository | `lumio` |
   | Workflow filename | `publish-npm.yml` |
   | Environment name | empty |
   | Allowed actions | **Direct npm publish** |

   A new trusted publisher only allows *staged* publishes by default. Without **Direct npm publish** the publish step fails with `E403 … OIDC permission denied for this action`. `npm dist-tag` is not needed: `publish` sets `latest` itself.
3. **A brand-new package** cannot get a trusted publisher before it exists on npm. Publish its first version by hand, then add the trusted publisher:
   1. Publish its workspace dependencies first (an `all` run publishes them and stops at the new package). `pnpm publish` rewrites `workspace:*` to the dependency's version, so a dependency that is not on npm yet makes the new package uninstallable.
   2. On a clean checkout of the release commit: `pnpm install --frozen-lockfile`, then `pnpm --filter "@zaflun/<name>..." build`.
   3. `npm login` with 2FA, then `pnpm --filter @zaflun/<name> publish --no-git-checks --access public`. Use `pnpm`, not `npm publish`: only pnpm rewrites the `workspace:` ranges. `--no-git-checks` is needed because releases are cut from `next`, and pnpm otherwise only publishes from `main`/`master`.
   4. Add the trusted publisher as in step 2, then run the workflow again for the packages that come after it.

npm allows only **one** workflow file per package as trusted publisher, which is why both single and all-packages releases run from `publish-npm.yml`. Renaming that file breaks publishing until every package's trusted publisher is updated. The workflow must stay on a GitHub-hosted runner.

Releases carry **no provenance attestation**: npm only issues provenance for public source repositories, and `zaflun/lumio` is private. The npm package page still shows the publisher as GitHub Actions via a trusted publisher.

## Publishing a Single Package

### Via Tag (recommended)

```bash
# 1. Bump version in package.json
cd packages/protocol
# Edit "version": "1.0.0" → "1.0.1"

# 2. Commit
git add packages/protocol/package.json
git commit -m "chore(protocol): bump version to 1.0.1"

# 3. Create tag (format: @zaflun/{package-name}@{version})
git tag "@zaflun/lumio-protocol@1.0.1"

# 4. Push (triggers publish-npm.yml workflow)
git push origin next --tags
```

The workflow runs: Install (`--frozen-lockfile`) → **dependency-confusion guard** (`scripts/supply-chain/check-dependency-confusion.mjs`, fail-closed) → Build (the package **and its workspace dependencies**, via the `...` filter suffix) → Test → Typecheck → Publish (`--access public`).

### Via Manual Dispatch

1. Go to GitHub → **Actions** → **"Publish npm Package"**
2. Click **"Run workflow"**
3. Select the package from the dropdown (e.g. `protocol`)
4. Optionally tick **Dry run** (build, test and typecheck only, no publish)
5. Click **"Run workflow"**

### Via gh CLI

```bash
gh workflow run "Publish npm Package" --ref next --field package=protocol
```

## Publishing All Packages

Dispatch the same **"Publish npm Package"** workflow with `package` = **`all`**. One job builds, tests and typechecks every package, then publishes them one after another in dependency order:

```
protocol → extension-types → agent-skill → sdk → devkit → cli
```

Nothing is published unless every package passes. A version that is already on npm is skipped with a notice, so a run that failed halfway can simply be started again. (A single-package run still fails on an existing version.)

```bash
# Dry run (build + test + typecheck only):
gh workflow run "Publish npm Package" --ref next --field package=all --field dry_run=true

# Actual publish:
gh workflow run "Publish npm Package" --ref next --field package=all
```

## Dependency Order

When publishing for the first time or after breaking changes, publish in this order:

| Order | Package | Depends On |
|:-----:|---------|------------|
| 1 | `@zaflun/lumio-protocol` | - |
| 2 | `@zaflun/lumio-extension-types` | - |
| 3 | `@zaflun/lumio-agent-skill` | - |
| 4 | `@zaflun/lumio-sdk` | protocol + extension-types |
| 5 | `@zaflun/lumio-devkit` | protocol (peer: sdk) |
| 6 | `@zaflun/lumio-cli` | extension-types |

`package: all` publishes in exactly this order.

## Version Bumping

```bash
# Patch (bug fix): 0.6.4 → 0.6.5
# Minor (new feature): 0.6.4 → 0.7.0
# Major (breaking change): 0.6.4 → 1.0.0
```

Edit `"version"` in the package's `package.json` directly. No automated version bump tool. Do **not** set it to the product `YYYY.M.PATCH` version - `packages/*` are versioned independently.

## Verifying a Release

After publish, verify on npm:

```bash
npm view @zaflun/lumio-protocol
npm view @zaflun/lumio-sdk version
```

Or visit: `https://www.npmjs.com/package/@zaflun/lumio-sdk`

## Testing Locally Before Publish

```bash
# Build
cd packages/sdk && pnpm build

# Test
pnpm test

# Typecheck
pnpm typecheck

# Or dispatch "Publish npm Package" with package=all and dry_run=true
```

## Workspace Dependencies

Packages reference each other via `"workspace:*"` in `package.json`:

```json
"dependencies": {
  "@zaflun/lumio-protocol": "workspace:*"
}
```

When `pnpm publish` runs, it automatically replaces `workspace:*` with the actual version (e.g. `^1.0.0`). This means the referenced package must already be published on npm.

## Troubleshooting

### "No projects matched the filters"

The package name in `pnpm-workspace.yaml` doesn't match. Verify:
- `packages/*` is listed in `pnpm-workspace.yaml`
- The `"name"` field in `package.json` matches `@zaflun/lumio-*`

### "404 Not Found - PUT …"

npm reports a publish it cannot authenticate as `E404`, not `401`. With Trusted Publishing that means the OIDC exchange did not match a trusted publisher. Check on the package's **Settings → Trusted Publisher** page:
- Organization `zaflun`, repository `lumio` (case-sensitive)
- Workflow filename exactly `publish-npm.yml`, without `.github/workflows/`
- Environment name empty
- The run comes from `zaflun/lumio` on a GitHub-hosted runner

### "403 Forbidden - … OIDC permission denied for this action"

The OIDC exchange worked, but the trusted publisher does not allow a direct publish. Edit it and tick **Direct npm publish** under *Allowed actions*.

### npmjs.com still shows the old version as current

The package page is cached separately from the registry. Check the registry itself: `npm view @zaflun/lumio-protocol dist-tags`. The page catches up within minutes.

### "EPUBLISHCONFLICT" / "Cannot publish over existing version"

The version already exists on npm. Bump the version number and try again.

## Workflow Files

| Workflow | File | Trigger |
|----------|------|---------|
| Single package or all | `.github/workflows/publish-npm.yml` | Push of a tag matching `@zaflun/**@*`, or manual dispatch with a `package` choice input (one package or `all`) and a `dry_run` boolean |

It runs on Node 24 with pnpm, on `ubuntu-latest` (npm Trusted Publishing does not accept self-hosted runners), with `contents: read` + `id-token: write`. Runs never overlap (`concurrency: publish-npm`). See [CI runner](./ci-runner.md).

---

## Developer Guide / Deployment

Source: https://docs.lumio.vision/developer-guide/deployment

# Deployment

Lumio uses release-driven deployment for its container images: they are built and pushed only when a GitHub Release is published, or by manual dispatch -- there are no automatic image builds on branch pushes. The workflow lives in `.github/workflows/release-images.yml`. Other surfaces (docs, extensions, npm packages) have their own pipelines, covered under [Other Deployment Pipelines](#other-deployment-pipelines).

## Release Strategy

Every deploy starts with a GitHub Release. The release tag encodes which app to deploy and the version:

```
{app}@{version}
```

The workflow parses the tag, determines the target app, runs the verification gate, builds the image, pushes it to the container registry, and signs it.

## Setting the Release Version

The product version is bumped **by hand in the feature PR that changes app code**, in the `YYYY.M.PATCH` format (e.g. `2026.8.14`). The Rust workspace, all TS apps except `apps/mobile`, all `shared/*`, and the private root `package.json` share one version and move in lockstep with the API - set every manifest to the same value directly (npm has no version inheritance).

After editing the manifests, run the **mandatory, in-order** post-bump regeneration chain and commit the generated artifacts alongside the manifest edits:

1. `cargo check --workspace` - refreshes `Cargo.lock`.
2. `just schemas` - regenerates `apps/api/openapi.json` + `apps/api/schema.graphql` (both embed the version).
3. `just bazel-vendor` - regenerates `vendor/` from the new `Cargo.lock`.
4. Commit `Cargo.lock`, `vendor/`, `apps/api/openapi.json`, and `apps/api/schema.graphql`.
5. `just verify-release`, then confirm `git status` is clean.

`just verify-all` does not detect schema or vendor drift - run `just verify-release` before opening the PR. Independent packages (`packages/*`, `extensions/system/*`) are not product-versioned; bump each one's own semver in the same PR that changes it. The mobile app (`apps/mobile`) is not product-versioned either: `package.json` `version` and `app.json` `expo.version` carry its own semver (starting at `1.0.0`) and always agree, while the iOS `buildNumber` / Android `versionCode` store build counters are separate, monotonically increasing integers managed by EAS - never derived from the product version or the semver string.

## How to Deploy

1. Go to **GitHub Releases** for the repository.
2. Click **Draft a new release**.
3. Create a tag following the `{app}@{version}` format.
4. Mark the release as a **pre-release** if the image should receive `beta` tags instead of `latest`.
5. Publish the release.

Tag examples:

```
api@2026.5.3
twitch-bot@2026.5.1
web@2026.5.2
discord-bot@2026.5.1
```

## Image Tags

The workflow generates multiple tags per image based on whether the release is marked as a pre-release.

### Production (stable release)

| Tag | Example | Description |
|-----|---------|-------------|
| `{version}` | `2026.5.3` | Exact version |
| `{major.minor}` | `2026.5` | Floating minor tag |
| `{year}` | `2026` | Floating year tag: the newest stable release of that year |
| `latest` | `latest` | Most recent stable release |
| `{short_sha}` | `a1b2c3d` | 7-character commit SHA |
| `{full_sha}` | `a1b2c3d...` | Full 40-character commit SHA |

### Pre-release (beta)

| Tag | Example | Description |
|-----|---------|-------------|
| `{version}` | `2026.5.3-beta.1` | Exact pre-release version |
| `beta` | `beta` | Floating beta tag |
| `{short_sha}` | `a1b2c3d` | 7-character commit SHA |
| `{full_sha}` | `a1b2c3d...` | Full 40-character commit SHA |

A version string containing `beta`, `alpha`, or `rc` is also treated as a pre-release regardless of the GitHub Release checkbox.

## Verification Gate

Before anything is published, a `Verify` job must pass:

```
bazel test  //crates/... --build_tag_filters=-manual
bazel build //apps/...   --build_tag_filters=-manual
```

The build step is a pre-push gate: the release fails before publishing if any app binary does not compile. `-manual` skips the container `_push` targets, which are build-tagged `manual`.

## Deployable Apps

Nine Rust binaries are built with Bazel (`bazel run --config=release //apps/{app}:{app}_push`) via `rules_img`:

| App | Tag Prefix |
|-----|------------|
| `api` | `api@` |
| `automation-worker` | `automation-worker@` |
| `bot-module-worker` | `bot-module-worker@` |
| `twitch-bot` | `twitch-bot@` |
| `youtube-bot` | `youtube-bot@` |
| `kick-bot` | `kick-bot@` |
| `discord-bot` | `discord-bot@` |
| `innertube-proxy` | `innertube-proxy@` |
| `crawler-twitch` | `crawler-twitch@` |

The Discord bot service authenticates to the API with `DISCORD_BOT__API__SYSTEM_KEY`. Create that key under **Admin → System Keys** in the same environment, grant `bots:internal`, and provide the one-time value to the bot service. The API does not provision System keys from config. `System access required` indicates the supplied credential is not an accepted System key; `Missing permission: bots:internal` indicates a valid key without the required grant.

### Build mode

Release images are compiled **optimised**. `--config=release` is defined in the repo `.bazelrc` as `build:release --compilation_mode=opt`, which rules\_rust turns into rustc `opt-level=3` with debuginfo stripped. Bazel's default mode, `fastbuild`, compiles at `opt-level=0`. Unoptimised code is slower, and its async state machines are several times larger, which leaves less headroom on actix's worker-thread stacks. Never push an image without `--config=release`. Local `cargo run` uses `[profile.dev] opt-level = 1`. The build mode is a hardening measure. It does not replace fixing oversized futures in code (boxing them with `Box::pin`).

PR CI (`Rust Tests`, `Rust Build`, `Clippy`, `Schema Check`) and the release Verify gate stay on `fastbuild`. The two modes write to separate output directories (`bazel-out/k8-opt` vs `bazel-out/k8-fastbuild`) and have different action keys, so they never evict each other's BuildBuddy entries. Because no CI job builds in `opt`, the Build & Push job uploads its own results to the remote cache (`--remote_upload_local_results`). A release then recompiles only the crates that changed since the previous release, not the whole dependency tree. Schema generation runs under the same config, so it reuses the API's `opt` outputs.

To check which mode a target builds in, run `bazel aquery --config=release 'mnemonic("Rustc", //apps/api:api)'` and look for `--codegen=opt-level=3`.

### API image environment defaults

`//apps/api:api_image` sets these environment variables. A host env file (e.g. `.env.api` in `dev-stack/staging/`) overrides any of them.

| Variable | Image default | Why |
|----------|---------------|-----|
| `TZ` | `Europe/Berlin` | Log and cron timestamps |
| `RUST_LOG` | `info` | Default log level |
| `LUMIO__SERVER__HOST` / `LUMIO__SERVER__PORT` | `0.0.0.0` / `3000` | Listen on the container network |
| `RUST_MIN_STACK` | `8388608` (8 MiB) | Stack size for every thread the Rust standard library spawns, including actix worker threads. The default is 2 MiB, and actix-server has no stack-size option of its own. |

`RUST_MIN_STACK` is a safety margin for deep async request paths. It does not fix oversized futures. Those are fixed in code by boxing them (`Box::pin`), and the code must stay within the 2 MiB default because tests and local runs use it.

#### Staying within the 2 MiB default

Two things decide how much stack a GraphQL request needs in an unoptimised build:

- **The depth of the root merge.** `Query` and `Mutation` in `apps/api/src/graphql/schema.rs` are `MergedObject`s, which resolve a field by polling their members as a chain of nested futures. At `opt-level=0` each link costs 25-35 KiB of stack. A flat list of 65 query types put a `ChatQuery` field about 1.7 MiB deep before its resolver ran. That is what overflowed staging on 2026.9.235. The root types are therefore a two-level tree of `QueryPartN` / `MutationPartN` groups with at most 8 members each. Add a new query or mutation type to the last part, and start a new part once that one holds 8. The SDL does not change, because the parts flatten into one `Query` / `Mutation` type.
- **The size of each resolver future.** Every byte a resolver future holds is carried by each future that wraps it. Box large inner futures (`Box::pin`), in particular each branch of a `tokio::join!` over network calls and each arm of a `match` that dispatches to per-platform async functions.

Tests guard both, and they also run in Bazel `fastbuild`: `graphql::schema::tests::root_merge_tree_stays_shallow` executes the deepest root fields on a 1 MiB stack, and the `*_stay_within_budget` tests in `graphql/chat.rs` and `lo-chat`'s `profile_service.rs` cap the future sizes of the emote and user-profile paths. If one trips, box the new future. Do not raise the budget. The cost is small. The stack is reserved virtual memory, and the kernel commits physical pages only when a thread touches them, so resident memory grows only by what a request actually uses. Setting it in the image rather than in code is deliberate: `std::env::set_var` is `unsafe` in Rust 2024, racy once threads exist, and the standard library caches the value on the first thread spawn.

Three Next.js apps are built from Dockerfiles (`docker/{app}.Dockerfile`):

| App | Tag Prefix |
|-----|------------|
| `web` | `web@` |
| `admin` | `admin@` |
| `id` | `id@` |

The `innertube-proxy` image is deployed to a trusted-IP host rather than a shared cloud edge - see [InnerTube Proxy](./innertube-proxy.md) for the placement requirement.

## Bulk Deploys

Three special tag prefixes deploy multiple apps at once:

| Tag Prefix | Deploys |
|------------|---------|
| `all@{version}` | All 12 apps (9 Rust + 3 Next.js) |
| `all-rust@{version}` | All 9 Rust apps |
| `all-web@{version}` | All 3 Next.js apps |

Example: publishing a release tagged `all@2026.5.3` builds and pushes every app image.

## Manual Dispatch

For emergency deploys or rebuilds without creating a release, the workflow supports `workflow_dispatch` with two inputs:

| Input | Description |
|-------|-------------|
| `app` | Which app to deploy - a dropdown of `all`, `all-rust`, `all-web`, or any single app from the tables above |
| `tag` | The image tag to apply (required) |

This is useful when the release flow is unavailable or when retagging an existing build.

## Signing and Provenance

Every pushed image is signed and attested before the job finishes. Signing resolves the image's immutable digest first (via its unique full-SHA tag) and operates on that digest, never on a floating tag:

- **Signature** - keyless `cosign sign` using the workflow's ambient GitHub OIDC token (the job holds `id-token: write`). No long-lived signing key exists.
- **Provenance** - `cosign attest --type slsaprovenance1` attaches a SLSA v1.0 provenance predicate recording the source repository, git ref and commit, the triggering event, the builder workflow ref, and the run's invocation URL.

## Deploy-Side Signature Verification

A signature only protects anything if the deploy checks it. A core-product image (API, web, admin, id, stats, shopify, workers, bots, `innertube-proxy`, `crawler-twitch`) is deployed only if it verifies against this identity, and only by digest:

```bash
cosign verify \
  --certificate-identity-regexp '^https://github\.com/zaflun/lumio/\.github/workflows/release-images\.yml@refs/tags/(all|all-rust|all-web|api|automation-worker|bot-module-worker|twitch-bot|youtube-bot|kick-bot|discord-bot|innertube-proxy|crawler-twitch|web|admin|id|stats|shopify)@[0-9]{4}\.[0-9]{1,2}\.[0-9]+(-[0-9A-Za-z.]+)?$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  ghcr.io/zaflun/lumio/<app>:<tag>
```

The identity is the workflow file at a **release tag** ref, `{app}@{version}` (`app` is a core image or `all` / `all-rust` / `all-web`, `version` is `YYYY.M.PATCH` with an optional `-<pre-release>` suffix). A release published from a GitHub Release, or a manual dispatch started from such a tag, passes. A manual dispatch started from a branch is signed as `…@refs/heads/<branch>` and is refused, as is a run on any other tag (for example the `@zaflun/*` npm package tags), an unsigned image, or one signed by any other workflow, repository or OIDC issuer. Use **Use workflow from → Tags** and pick a release tag for an emergency rebuild that has to be deployable.

### Where it is enforced

| Deploy path | Gate |
|-------------|------|
| Staging server (own compose files on the host, `:beta` channel) | `dev-stack/staging/verified-pull.sh pull <app> beta` verifies, pulls `ghcr.io/zaflun/lumio/<app>@sha256:…`, and tags that digest locally as `:beta`. Each core-image service carries `pull_policy: never` (the reference files in `dev-stack/staging/` and the host's copies), so `docker compose up` starts only the verified image, fails if none was pulled, and `docker compose pull` skips it. Roll back with `verified-pull.sh pull <app> <older-version> beta`. |
| Pinning a digest directly (e.g. the `innertube-proxy` and `crawler-twitch` trusted-IP hosts) | `verified-pull.sh verify <app> <tag>` prints the verified `…@sha256:…` ref for the compose `image:` line. |
| k3s cluster (planned) | An admission policy (sigstore policy-controller or Kyverno) enforcing the same identity is an acceptance criterion of the k3s cutover. |

The compose files in `dev-stack/staging/` are reference copies; the host runs its own. Third-party infrastructure images (PostgreSQL, Redis, brokers, Prometheus, Grafana) are not built by `release-images.yml` and are not covered by this gate.

The gate checks the documented path. It is not an admission controller: whoever has shell access to the host can still `docker pull` a tag or start any image by hand. Admission-time enforcement arrives with the k3s cutover. The full operator steps are in `dev-stack/staging/README.md` → *Signature verification*.

## Schema Artifacts

Releases that include the API (`api`, `all`, or `all-rust`) additionally generate and attach the API contract to the GitHub Release:

```
bazel run --config=release //apps/api:generate-openapi -- openapi.json
bazel run --config=release //apps/api:generate-schema  -- schema.graphql
```

Both files are uploaded to the release with `--clobber`, so each API release carries the exact OpenAPI and GraphQL SDL it shipped.

## Container Registry

All images are pushed to GitHub Container Registry (GHCR):

```
ghcr.io/{org}/lumio/{app}
```

For example:

```
ghcr.io/zaflun/lumio/api:2026.5.3
ghcr.io/zaflun/lumio/twitch-bot:latest
ghcr.io/zaflun/lumio/web:beta
```

Authentication uses the `GITHUB_TOKEN` provided by GitHub Actions with `packages: write` permission.

## Environments

Two different promotion models are in use, and they must not be conflated.

### Container apps (API, workers, bots, web, admin, id)

These are promoted by **release channel**, not by branch. `release-images.yml` never runs on a branch push - only on a published GitHub Release or a manual dispatch. The channel is decided by the pre-release flag:

| Release kind | Floating tag | Meaning |
|--------------|--------------|---------|
| Pre-release | `beta` | Pre-release channel |
| Full release | `latest` | Full release channel |

Consumers pin an exact `{version}`, follow a stable `{major.minor}` or `{year}` line, or follow `beta` / `latest`. Which environment a given image lands in is decided by the deployment target that pulls it, and is convention-based rather than enforced by this workflow.

### Docs family (docs, developer-docs, extension-apps)

Only these deploy on branch and tag pushes, and their branch-to-environment mapping is enforced in CI:

| Branch / Tag | Environment |
|-------------|-------------|
| `next` | Staging |
| `main` | Production preview |
| Tag `20*` (e.g. `2026.5.3`) | Production |

See the [Installation guide](../getting-started/installation.md) for the full domain table per environment.

## Other Deployment Pipelines

Container images are only one of several release paths. The rest are driven by their own workflows:

| Surface | Workflow | Trigger |
|---------|----------|---------|
| Docs site | `deploy-docs.yml` | Push to `next` / `main`, tag `20*` |
| Developer docs | `deploy-developer-docs.yml` | Push to `next` / `main`, tag `20*` |
| Extension supervisor + runtime | `deploy-extension-apps.yml` | Push to `next` / `main` or tag `20*`, restricted to changes under `apps/extension-supervisor/` or `apps/extension-runtime/`; also manual |
| System extensions | `system-extensions.yml` | Tag `ext-{name}@{version}` (e.g. `ext-chat-box@1.0.3`); also manual, per extension or `all` |
| Public npm packages | `publish-npm.yml` | Tag `@zaflun/{package}@{version}`; also manual, per package or `all` |

The npm workflow publishes one of the five public `@zaflun/*` packages, or all of them in dependency order, through npm Trusted Publishing (no npm token), and supports a `dry_run` input that builds and tests without publishing. Those packages carry their own independent semver rather than the product version - see [npm Publishing](./npm-publishing.md).

`system-extensions.yml` runs on the self-hosted EX44 runner (rollback via the repository variable `RELEASE_RUNNER`); `publish-npm.yml` stays on `ubuntu-latest` because npm Trusted Publishing only accepts GitHub-hosted runners - see [CI Runner](./ci-runner.md).

## Security Audit

A nightly security audit runs via `.github/workflows/security-audit.yml` (cron: `0 3 * * *` UTC). It scans both dependency ecosystems on **both** `main` (what is live) and `next` (what releases are cut from), as a `ref: [main, next]` matrix, because a scheduled trigger alone would only ever check out the default branch:

| Check | Tool | Scope | Accepted-risk allowlist |
|-------|------|-------|-------------------------|
| Rust dependencies | `cargo audit` | All vulnerability advisories (`.vulnerabilities.count`) | `.cargo/audit.toml` |
| npm dependencies | `pnpm audit` | High and critical severity | `pnpm.auditConfig.ignoreGhsas` in the root `package.json` |

**Failure semantics:** each matrix leg **fails** when it finds vulnerabilities **or** when the audit itself breaks (tool crash, unparseable JSON report, an earlier step failing). A red nightly run therefore always means "look at this"; a green one means every leg produced a clean, parseable report.

**Alert flow:**

- Each failing leg posts its own Discord alert via `DISCORD_SECURITY_WEBHOOK_URL`, labelled with the branch, listing the advisories, or flagged as an audit error with the tail of the tool's stderr.
- A daily summary always posts: either "All clear" (green), or "Action required" (yellow) with the Rust and npm job results.

The workflow also supports manual `workflow_dispatch` for on-demand scans.

---

## Developer Guide / Bazel Build System

Source: https://docs.lumio.vision/developer-guide/bazel

# Bazel Build System

Lumio uses a dual build system: **Cargo for local development**, **Bazel for CI and container images**. Developers write and test code with standard Cargo commands locally. Bazel takes over in CI where its remote caching and incremental target detection provide significant speed improvements.

## Why Bazel

- **Remote caching** via BuildBuddy -- unchanged targets are not rebuilt across CI runs
- **Incremental target detection** via bazel-diff -- only affected targets are tested on PRs
- **Hermetic builds** -- reproducible container images from pinned toolchains and vendored dependencies

## Architecture

```
lumio/
├── MODULE.bazel                         # Root module definition
├── .bazelrc                             # Local Bazel settings
├── .github/actions/setup-bazel/         # Composite action: generates the CI bazelrc
├── misc/toolchains/
│   ├── rust.MODULE.bazel                # Rust toolchain (edition 2024, pinned version)
│   ├── proto.MODULE.bazel               # Protobuf toolchain
│   ├── v8.MODULE.bazel                  # V8 prebuilt static library
│   ├── docker.MODULE.bazel              # Base image pull (runtime-base, by `latest` tag)
│   └── BUILD.bazel                      # cc_library for V8 native linking
├── vendor/cargo/                        # Vendored crate BUILD files (~814)
│   ├── BUILD.actix-web-4.13.0.bazel
│   ├── BUILD.tokio-1.*.bazel
│   └── ...
├── crates/*/BUILD.bazel                 # One BUILD per internal crate
└── apps/*/BUILD.bazel                   # One BUILD per app (binary + image targets)
```

The root `MODULE.bazel` includes four toolchain modules and pins the `rules_rust` fork via `git_override`.

There is no checked-in `.bazelrc.ci`. `.bazelrc` deliberately carries no `try-import` for it -- CI settings are generated at runtime by `.github/actions/setup-bazel/action.yaml` and handed to `bazel-contrib/setup-bazel` via its `bazelrc` input.

## zaflun/rules\_rust Fork

Lumio uses a fork of `rules_rust` at `github.com/zaflun/rules_rust`. The fork fixes two issues in the upstream repository:

1. **Sandbox path rotation for `cargo_build_script`** -- the upstream `OUT_DIR` handling breaks when Bazel rotates sandbox paths between actions. The fork stabilizes `OUT_DIR` so build scripts (e.g., `utoipa-swagger-ui` asset embedding) produce deterministic outputs.
2. **`cargo_runfiles` data file mapping** -- the upstream mapping does not resolve data dependencies (e.g., V8 binding files) correctly in sandboxed builds. The fork patches the runfiles lookup.

The fork publishes **prebuilt `cargo-bazel` binaries** via GitHub Releases for Linux (x86\_64, aarch64), macOS (aarch64), and Windows (x86\_64, aarch64). These are fetched as `http_archive` dependencies in `MODULE.bazel` so that the vendor step does not require building `cargo-bazel` from source.

## Vendored Crates

All external Rust dependencies are vendored into `vendor/cargo/` as auto-generated `BUILD.{crate}-{version}.bazel` files (~814 of them). This avoids network fetches during builds and ensures reproducibility. The generated repository is exposed as `@crate_index` (wired up in `misc/toolchains/rust.MODULE.bazel` via the `//vendor:cargo_ext.bzl` extension).

**Update workflow** after changing `Cargo.lock`:

```bash
bazel run //vendor:cargo_vendor
```

This regenerates all `BUILD.*.bazel` files in `vendor/cargo/` using `crate_universe`. The vendored files are committed to the repository.

## BUILD.bazel Patterns

### Crate (library + tests)

Every internal crate follows this pattern:

```python
exports_files(["Cargo.toml"])

load("@rules_rust//rust:defs.bzl", "rust_library", "rust_test")

rust_library(
    name = "lo-common",
    srcs = glob(["src/**/*.rs"]),
    edition = "2024",
    deps = [
        "@crate_index//:actix-web",
        "@crate_index//:serde",
        "@crate_index//:serde_json",
    ],
    visibility = ["//visibility:public"],
)

rust_test(
    name = "lo-common_test",
    crate = ":lo-common",
)
```

The `exports_files(["Cargo.toml"])` line is **required** -- the vendor toolchain reads `Cargo.toml` metadata from every workspace member. Omitting it causes vendor failures.

### App (binary + container image)

App BUILD files define a `rust_binary`, then layer it into a container image:

```python
load("@rules_img//img:image.bzl", "image_manifest")
load("@rules_img//img:layer.bzl", "image_layer")
load("@rules_img//img:push.bzl", "image_push")
load("@rules_rust//rust:defs.bzl", "rust_binary")

rust_binary(
    name = "api",
    srcs = glob(["src/**/*.rs"]),
    edition = "2024",
    deps = ["//crates/lo-common", ...],
)

image_layer(
    name = "api_layer",
    tags = ["manual"],
    srcs = {
        "/usr/local/bin/lumio-api": ":api",
        "/app/config/default.toml": "config/default.toml",
        "/app/config/production.toml": "config/production.toml",
        "/app/config/staging.toml": "config/staging.toml",
    },
)

image_manifest(
    name = "api_image",
    tags = ["manual"],
    base = "@runtime_base",
    layers = [":api_layer"],
    entrypoint = ["/usr/bin/tini", "--", "/usr/local/bin/lumio-api"],
    env = {
        "TZ": "Europe/Berlin",
        "RUST_LOG": "info",
        "LUMIO__SERVER__HOST": "0.0.0.0",
        "LUMIO__SERVER__PORT": "3000",
    },
    user = "1001",
    visibility = ["//visibility:public"],
)

image_push(
    name = "api_push",
    tags = ["manual"],
    image = ":api_image",
    registry = "ghcr.io",
    repository = "zaflun/lumio/api",
    tag = "{{.TAG}}",
    build_settings = {"TAG": "//misc:push_tag"},
    visibility = ["//visibility:public"],
)
```

### Push tag

`push_tag` is a repo-local `string_flag` (`//misc:push_tag`, declared in `misc/BUILD.bazel`),
**not** a `rules_img` setting - there is no `@rules_img//img/settings:push_tag`. Every
`image_push` target wires it in via `build_settings` and expands it with `tag = "{{.TAG}}"`;
`release-images.yml` overrides it per tag with `--//misc:push_tag=<tag>`. Without the `tag`
attribute `rules_img` pushes by digest only and no tag is created.

### Base image

The base image is `ghcr.io/zaflun/lumio/runtime-base` (Ubuntu 26.04), pulled by the
`latest` tag in `misc/toolchains/docker.MODULE.bazel`. Because it is pulled by tag rather than
by digest, the `pull` rule needs `unsafe_allow_tag_without_digest = True` - `rules_img` refuses
a tag-only pull otherwise and fails with `missing valid digest, please specify the digest
explicitly`. The tag is resolved to a digest at fetch time, so the image is not reproducible
across time; `build-runtime-base.yml` rebuilds it daily.

**The base image index must not contain attestation manifests.** `build-runtime-base.yml`
therefore builds with `--provenance=false --sbom=false`. Without those flags `docker buildx`
adds one `unknown/unknown` attestation manifest per platform to the OCI index. `rules_img`'s
`image_import` iterates *every* child manifest of an index and requires a matching
`config.rootfs.diff_ids` entry for each layer; an attestation manifest has one in-toto layer
but an empty (`{}`) config, so the import aborts with:

```
Error in fail: layer index out of range for config: 0
```

and **every** `//apps/*:*_push` target becomes unanalysable - the failure surfaces at
`@@+pull+runtime_base//:image`, not in the app being pushed. A workflow fix alone does not
help: the already-published image must be rebuilt, and `latest` is only re-tagged on `main`,
so `build-runtime-base.yml` has to run from `main` before `release-images.yml` can succeed.

### Manual tags

Every `image_manifest` / `image_push` target carries `tags = ["manual"]`, so wildcards
like `bazel build //apps/...` never expand to them, and `ci.yml`'s Bazel jobs additionally
pass `--build_tag_filters=-manual`. Image targets are therefore built only when named
explicitly - by `just bazel-images` locally, or by `release-images.yml` on a release.
No PR check analyses them, so a broken base image surfaces at release time, not in CI.

## Adding a New Crate

1. Create the crate directory under `crates/` with `Cargo.toml` and `src/`.
2. Add it to the workspace `[members]` in the root `Cargo.toml`.
3. Create `crates/{name}/BUILD.bazel` following the library + test pattern above. Include `exports_files(["Cargo.toml"])` at the top.
4. Run `bazel run //vendor:cargo_vendor` to regenerate vendored BUILD files if the crate introduces new external dependencies.
5. Verify the build: `bazel build //crates/{name}:...`
6. If the crate is a dependency of a deployable app, add it to the app's `deps` in the app's `BUILD.bazel`.

Bazel deps are **explicit** -- adding a dependency in `Cargo.toml` does not add it to the corresponding `BUILD.bazel`. A green `cargo check` therefore does not imply a green Bazel build; hand-add every new dep to the `deps` list of the affected `rust_library` / `rust_binary` target.

## V8 Integration

Crates and apps that depend on `deno_core` (the V8 JavaScript engine) require special linking. The V8 engine is distributed as a prebuilt static library for `x86_64-unknown-linux-gnu` only (matching the deployment fleet), fetched from the `denoland/rusty_v8` releases.

**Toolchain setup** (`misc/toolchains/v8.MODULE.bazel`):

```python
http_archive(
    name = "v8_prebuilt",
    build_file_content = 'exports_files(["librusty_v8.a"], visibility = ["//visibility:public"])',
    sha256 = "f48762ca10d1f1fc605a441c5ae430ec8ce1e9e80f14d78fbc42cb878c30b476",
    urls = ["https://github.com/denoland/rusty_v8/releases/download/v150.4.0/librusty_v8_simdutf_release_x86_64-unknown-linux-gnu.a.gz"],
)
```

**Linking** -- the `cc_library` that wraps the archive is declared once, publicly, in `misc/toolchains/BUILD.bazel`. App BUILD files do not redeclare it; they reference the shared target from the binary's `deps`:

```python
# misc/toolchains/BUILD.bazel
load("@rules_cc//cc:cc_library.bzl", "cc_library")

cc_library(
    name = "v8_native",
    srcs = ["@v8_prebuilt//:librusty_v8.a"],
    linkstatic = True,
    linkopts = ["-lstdc++", "-ldl", "-lpthread"],
    visibility = ["//visibility:public"],
)

# apps/bot-module-worker/BUILD.bazel
rust_binary(
    name = "bot-module-worker",
    deps = [
        "//crates/lo-bot-module-worker",
        "//misc/toolchains:v8_native",
        ...
    ],
)
```

`//misc/toolchains:v8_native` is in the `deps` of every V8-linking binary: `api`, `automation-worker`, `bot-module-worker`, and the five platform bots.

**Vendor BUILD for the `v8` crate** -- the vendored `BUILD.v8-*.bazel` uses `$(execpath)` to resolve the binding file path at build time:

```python
rustc_env = {
    "RUSTY_V8_SRC_BINDING_PATH": "$(execpath gen/src_binding_simdutf_release_x86_64-unknown-linux-gnu.rs)",
},
```

## Key Commands

| Command | Description |
|---------|-------------|
| `just bazel-build` | `bazel build //crates/... //apps/...` |
| `just bazel-test` | `bazel test //crates/...` |
| `just bazel-images` | Build the container images for `api`, `bot-module-worker` and the five platform bots |
| `just bazel-clippy` | Run clippy over `//crates/...` via the `rust_clippy_aspect` |
| `just bazel-vendor` | `bazel run //vendor:cargo_vendor` |

`just bazel-images` does **not** cover `automation-worker` or `innertube-proxy`; build those explicitly (`bazel build //apps/automation-worker:automation-worker_image`) when you need them locally.

Direct Bazel invocations:

```bash
# Build a single crate
bazel build //crates/lo-common

# Test a single crate
bazel test //crates/lo-common:lo-common_test

# Build a specific app image
bazel build //apps/api:api_image

# Push an image (requires GHCR authentication). Always optimised: --config=release
bazel run --config=release //apps/api:api_push --//misc:push_tag="2026.5.3"
```

## BuildBuddy

Remote caching is provided by [BuildBuddy](https://buildbuddy.io). The `.github/actions/setup-bazel` composite action generates the CI bazelrc at runtime and passes it to `bazel-contrib/setup-bazel`. The remote-cache block is emitted only when the `BUILDBUDDY_API_KEY` secret is present -- without it the job logs a notice and builds without a remote cache:

```
common --remote_cache=grpcs://remote.buildbuddy.io
common --bes_backend=grpcs://remote.buildbuddy.io
common --bes_results_url=https://app.buildbuddy.io/invocation/
common --remote_timeout=3600
common --remote_cache_compression
```

The auth header (`common --remote_header=x-buildbuddy-api-key=…`) is not part of that block. It is written to a job-scoped `$RUNNER_TEMP/buildbuddy-auth.bazelrc`, which the generated rc only `import`s by path, and every Bazel job ends with `.github/actions/setup-bazel/teardown.sh`, which removes the key and asserts none is left on disk. See [CI Runner](./ci-runner.md).

**Cache write policy:**

| Context | Writes |
|---------|--------|
| Base default (every job) | Read-only -- the generated bazelrc always sets `common --noremote_upload_local_results` |
| In-org `pull_request` | Read-write -- the `Rust Tests` / `Rust Build` jobs append `--remote_upload_local_results` when `github.event.pull_request.head.repo.full_name == github.repository` |
| `push` to `main` | Read-write -- same flag; `main` is the promotion pointer |
| Self-hosted CI runner, in-org | Additionally `Schema Check` and `Clippy` upload (same in-org condition). On the persistent runner an action one job built is a *local* action-cache hit for the next job of that runner user, and Bazel never uploads local hits, so without this the other runner instances never saw it. See [CI Runner](./ci-runner.md) |
| `release-images.yml` Build & Push | Read-write -- the Rust `_push` runs pass `--remote_upload_local_results` next to `--config=release`. No CI job builds `compilation_mode=opt`, so otherwise every release would recompile the whole tree. Releases are published or dispatched in-org by users with write access |

There is no push-to-`next` run any more (ZAF-1070): every one was cancelled by hand
after each merge, so it seeded nothing and cost ~220-360 job-min/day for zero signal.
In-org PR runs are the cache seeders now. Fork PRs cannot poison the cache -- `secrets.BUILDBUDDY_API_KEY`
is not exposed to fork `pull_request` runs (and `pull_request_target` is unused), so
setup-bazel emits no remote-cache block for a fork and the upload flag is a no-op there;
the `head.repo == repository` guard is defence-in-depth on top of that.

The same action logs in to GHCR so the `@runtime_base` pull succeeds. On GitHub-hosted runners it also installs the system deps Bazel needs (`libssl-dev`, `clang`, `lld`) and provisions a 4 GB swapfile; on the self-hosted CI runner it checks those prerequisites instead and sizes `--jobs` / `--local_resources` and a persistent disk cache for the host. See [CI Runner](./ci-runner.md).

## Troubleshooting

### OpenSSL in sandbox

Some crates (e.g., `openssl-sys`) need environment variables to find system libraries inside the Bazel sandbox. If builds fail with OpenSSL linker errors, check that `action_env` settings in `.bazelrc` expose the necessary paths.

### Missing `exports_files` for `Cargo.toml`

Every crate's `BUILD.bazel` must include `exports_files(["Cargo.toml"])`. Without it, the vendor toolchain cannot read crate metadata and `bazel run //vendor:cargo_vendor` fails with a missing-file error.

### `layer index out of range for config: 0`

An image target fails during **analysis** with this `rules_img` error:

```
ERROR: in image_import rule @@+pull+runtime_base//:image:
Error in fail: layer index out of range for config: 0
```

The index that `latest` resolves to contains a buildx attestation manifest.
`image_import` walks every child manifest of an index and needs one `config.rootfs.diff_ids`
entry per layer; an attestation manifest has an in-toto layer but an empty config, so it never
matches. The fix is to republish `latest` without attestations -- `build-runtime-base.yml`
already passes `--provenance=false --sbom=false`, but it only tags `latest` from `main`, so that
workflow has to run from `main` before the pull resolves to a clean index. See
[Base image](#base-image).

### `UNAUTHORIZED: authentication required` pulling `@runtime_base`

`ghcr.io/zaflun/lumio/runtime-base` is a private package, so analysing any image target locally
requires `docker login ghcr.io` with a token that has `read:packages`. A GitHub App installation
token is **not** accepted by GHCR -- use a classic PAT. Without it, `bazel build` on
`//apps/*:*_image` or `//apps/*:*_push` cannot fetch the base image; every other target builds
fine, so this only blocks image work.

### V8 linking failures

V8 linking requires:

1. The prebuilt `librusty_v8.a` archive matching the `deno_core` version in `Cargo.lock`.
2. A `cc_library` target in the app's `BUILD.bazel` that links the archive with `-lstdc++ -ldl -lpthread`.
3. The `v8` vendor BUILD must have the correct `$(execpath)` for the binding source file.

If the `deno_core` or `v8` crate version changes in `Cargo.lock`, update the SHA and URL in `misc/toolchains/v8.MODULE.bazel` to match the corresponding `rusty_v8` release.

---

## Developer Guide / CI Runner

Source: https://docs.lumio.vision/developer-guide/ci-runner

# CI Runner

Every job in `.github/workflows/ci.yml`, `.github/workflows/release-images.yml` and `.github/workflows/system-extensions.yml` runs on the self-hosted runner labelled **`zcloud-runner-ex44`** (a Hetzner EX44: Intel i5-13500, 14 cores / 20 threads, 64 GB RAM, 2× 512 GB NVMe, Ubuntu 26.04 with glibc 2.43). `zaflun/lumio` is private, so jobs on a self-hosted runner bill no GitHub Actions minutes. Every other workflow (docs deploys, `publish-npm.yml`, runtime-base build, security audit, …) still runs on `ubuntu-latest`. `publish-npm.yml` has to stay there: it publishes through npm Trusted Publishing, which only accepts GitHub-hosted runners.

## Runner selection and rollback

Each `ci.yml` job carries

```yaml
runs-on: ${{ vars.CI_RUNNER || 'zcloud-runner-ex44' }}
```

The job targets the runner's **custom label alone**. It does not also require `self-hosted` / `linux` / `x64`, because a runner registered with `--no-default-labels` would never match those.

**Rollback without a PR:** set the repository variable `CI_RUNNER` to `ubuntu-latest` (*Settings → Secrets and variables → Actions → Variables*). The next run uses GitHub-hosted VMs again. Delete the variable to return to the EX44.

`release-images.yml` has its own variable, **`RELEASE_RUNNER`**, with the same default and the same rollback (`ubuntu-latest`). It is separate from `CI_RUNNER` so that releases can move back to hosted VMs without touching PR CI. Releases use the same `zcloud-runner-ex44` instances as PR CI; there is no dedicated release instance. `system-extensions.yml` reads the same `RELEASE_RUNNER` variable, so one switch moves both release paths. Its jobs install Node and pnpm under `$RUNNER_TEMP` and check out without persisted credentials, like the release jobs. See [Release images](#release-images).

## Hosted vs. self-hosted behaviour

`.github/actions/setup-bazel` branches on `runner.environment`. The hosted path behaves as it always has. The self-hosted path is built for a persistent host:

| Concern | `ubuntu-latest` (hosted) | `zcloud-runner-ex44` (self-hosted) |
|---|---|---|
| Swap | 4 GB `/mnt/swapfile` per job | none (64 GB RAM) |
| System packages | `apt-get install libssl-dev clang lld` per job | none; a prerequisite check fails with one `::error::` listing everything missing |
| Bazelisk | preinstalled on the image | `bazel-contrib/setup-bazel` downloads Bazelisk `1.29.0` into the tool cache |
| `--jobs` / `--local_resources` | `--jobs=2`, `ram=6144` | `--jobs=HOST_CPUS*.3`, `cpu=HOST_CPUS*.3`, `ram=HOST_RAM*.25` (6 jobs, ~16 GB per instance on the EX44, sized for 6 instances) |
| Local disk cache | off (`--disk_cache=`) | `~/.cache/bazel-disk`, capped at 150 GB (pruned to 120 GB, least recently used first) |
| Repository cache | restored from the Actions cache | `~/.cache/bazel-repo`, persistent |
| BuildBuddy remote cache | read in every job; Rust Build / Rust Tests upload in-org | the same, plus Schema Check and Clippy upload in-org, so the six instances share their results |
| API test output root | moved to `/mnt` via `~/.bazelrc` | unchanged (no `sudo`, no `~/.bazelrc` append) |
| DB-backed API tests | `--jobs=2` limits them to two binaries | API Integration Tests starts its Postgres service with `max_connections` 400, durability off (`fsync`, `synchronous_commit`, `full_page_writes` — as on the host test stack; with fsync on, each per-test template clone fsyncs a whole database and the binaries time out) and `authentication_timeout` 10 s, all via `POSTGRES_INITDB_ARGS`, with its data directory on a tmpfs (on the shared disk, clone checkpoints stalled for up to 80 s and tests failed with `PoolTimedOut`). A step checks those settings and fails the job if they are missing. The job links every test binary in a `bazel build` before `bazel test` runs any of them, so no linking competes with the DB tests. It runs up to 12 binaries × 4 threads (`--jobs` caps it lower); API tsdb Migration Test stays at 4 × 4 under the default 100 connections |

On both paths:

- **The BuildBuddy key never lands in `$HOME`.** It is written to `$RUNNER_TEMP/buildbuddy-auth.bazelrc` (mode `0600`), which `~/.bazelrc` only `import`s by path. The runner empties `$RUNNER_TEMP` at the start and end of every job.
- **Every setup-bazel job ends with a teardown step** (`.github/actions/setup-bazel/teardown.sh`, `if: always()`). It stops the Bazel server, redacts the key from Bazel's `java.log` (the Bazel client hands every rc option to the server, and the server logs it), deletes the auth rc and, on the self-hosted path, caps the disk cache. Then it **fails the job** if the key is still in any file under `$HOME`, or if `~/.bazelrc` gained extra `startup` lines.
- Scratch files live under `$RUNNER_TEMP`, never under fixed `/tmp` paths.
- The postgres / TimescaleDB service containers publish `5432` on a **dynamic** host port; `DATABASE_URL` reads it from `job.services.<name>.ports['5432']`.

The ZAF-1693 split (`api_lib`, then `api_test`, then the rest, as separate Bazel invocations) stays on both paths.

BuildBuddy keys include the C/C++ toolchain, which Bazel configures from the host's `clang`. Results built on `ubuntu-latest` therefore do not match the EX44's, and the reverse is also true. The remote cache is shared between the EX44 instances, not between the EX44 and hosted runners.

Because the instances run as different OS users, a cached action must not write to an absolute path baked in by whoever built it first. `sailfish`'s template derive did exactly that (its proc-macro writes to the build-time `OUT_DIR`, inside the building user's output base), so `vendor/BUILD.bazel` builds `sailfish-compiler` with its `hermetic` feature under Bazel. That feature compiles templates in memory. If a crate fails on the EX44 with `PermissionDenied` under `/home/<other runner user>/`, fix that crate the same way.

## Release images

`release-images.yml` signs and pushes production images from the same persistent host that runs PR CI, as the same OS users. A PR job can write to those users' `$HOME` and holds a writable BuildBuddy key, so the release builds with nothing inherited from earlier jobs:

- **Run-scoped homes.** The first step of both jobs points `DOCKER_CONFIG`, `RUNNER_TOOL_CACHE` and `BAZELISK_HOME` at `$RUNNER_TEMP`, and cosign installs to `$RUNNER_TEMP/cosign`. Docker CLI plugins and credential helpers, the GHCR login, Bazelisk, Node, pnpm and cosign therefore never come from, or land in, the persistent `$HOME`. Build & Push asserts that `docker buildx` resolves to a system plugin directory and that Bazel's install base is under `$RUNNER_TEMP`.
- **Bazel runs isolated.** Both jobs call `setup-bazel` with `isolated: "true"`: no local disk cache (`--disk_cache=`), and an output base, install base (`startup --install_base`) and repository cache under `$RUNNER_TEMP`, with `--repo_env=DOCKER_CONFIG` so the `@runtime_base` pull uses the run's login. Their teardown (`BAZEL_ISOLATED=true`) runs `bazel clean --expunge` and deletes all three directories.
- **BuildBuddy stays on.** The release reads the remote cache like every CI job and uploads its own `--config=release` (`opt`) results (`--remote_upload_local_results`). In-org PR jobs hold a writable key, so a remote action result is trusted the same way as on PR CI (founder decision, ZAF-1788).
- **Web images build in a BuildKit builder of their own.** The job creates `lumio-release-<run id>-<attempt>` (`docker-container` driver, BuildKit on a fixed version tag), pushes from it directly with `--provenance=false --sbom=false` (a plain image manifest; provenance comes from cosign), prunes it after each app and removes it in an `if: always()` step.
- **Sign the built digest, then promote.** Each image is pushed under its full-SHA tag only. cosign signs and attests the digest the build reported (buildx `--metadata-file`; for Rust the rules_img `image_manifest` `digest` output), after checking that the registry's `:<full sha>` agrees. Only then, as the last action of the step, do the other tags move. A promote fetches the manifest by digest and `PUT`s the same bytes under each tag through the registry API, so the tag points at exactly the signed digest. `docker buildx imagetools create` is not used for this, because it wraps a single manifest in a new index with a different digest. A run that stops before the promote leaves every floating tag on the previous signed digest.
- **One release at a time.** Build & Push is in the concurrency group `release-images` with `cancel-in-progress: false`. `all`, `all-rust` and `api` push the same images, so a per-app group would not serialise them. GitHub keeps one pending run per group.
- **Least privilege.** Verify runs with `contents: read` and `packages: read`; only Build & Push gets `packages: write`, `id-token: write` and `contents: write`. Both check out with `persist-credentials: false`.
- **Every job has `timeout-minutes`** (Verify 90, Build & Push 180).

The tag set (full release: version, `YYYY.M`, `YYYY`, `latest`, short SHA, full SHA; pre-release: version, `beta`, short SHA, full SHA), the keyless cosign signature, the SLSA provenance attestation (both by digest) and the schema upload are the same on both runner kinds.

No runner user holds host root. Each one runs its own rootless Docker daemon instead of being in group `docker`, so a PR job cannot reach the host or another instance through Docker (`docker run -v /:/h alpine ls /h/root` fails). The measures above protect a release from leftovers of earlier jobs on the same user. A PR job on the same instance can still read that user's runner credentials; the founder accepted that residual risk (ZAF-1791).

### glibc guard

Bazel links the Rust binaries against the **build host's** glibc, but they run on `runtime-base`'s glibc. If the host's is newer, the container dies at start with ``version `GLIBC_2.xx' not found``, and neither Bazel nor the push notices. Before it pushes anything, Build & Push therefore builds every Rust `_push` target, reads the newest `GLIBC_` symbol version the packed binary needs (`objdump -T`) and compares it with `getconf GNU_LIBC_VERSION` in `ghcr.io/zaflun/lumio/runtime-base:latest`. If the base is older, the job fails with a `glibc guard` error and pushes nothing.

`runtime-base` is Ubuntu 26.04 (glibc 2.43), the same release as the EX44; an `api` built there needs `GLIBC_2.43` (`atan2f`). When the runner's OS moves, move `docker/runtime-base.Dockerfile` to the same release in the same change. `latest` is only re-tagged from `main`, so the base must reach `main` and `build-runtime-base.yml` must run there before releases from the new runner can pass the guard. A rollback to `ubuntu-latest` (glibc 2.39) always passes.

## Runner prerequisites

The runner is provisioned once, by hand. CI installs nothing with `sudo`, and no step on the self-hosted path calls `sudo`, so the runner user does **not** need passwordless sudo.

1. **GitHub Actions runner** as a systemd service (`./svc.sh install <user>`) under a dedicated, unprivileged user, registered with the label `zcloud-runner-ex44`.
2. **Rootless Docker per runner user.** The user is **not** in group `docker` (that group is host root) and has no sudo. Each user runs its own daemon (`dockerd-rootless-setuptool.sh install`, `loginctl enable-linger <user>`, a subuid/subgid range), and the runner's `.env` sets `DOCKER_HOST=unix:///run/user/<uid>/docker.sock`. Packages: `docker-ce-rootless-extras`, `uidmap`, `dbus-user-session`, `slirp4netns`. A systemd drop-in on the runner unit waits for that socket after a reboot. The API test jobs start `postgres:18-alpine` / `timescale/timescaledb:latest-pg18` service containers, and setup-bazel runs `docker/login-action` for the `@runtime_base` pull; both work unchanged under rootless.

   **Each user gets its own host port block** for published container ports: `61000 + 600 × N` to `+599`, where N is the instance number (`zaflun` 0, `zaflun1` 1, …). Every rootless daemon allocates dynamic ports on its own, so without disjoint blocks two service jobs on different instances pick the same port and one fails with `RootlessKit PortManager.AddPort(): … bind: address already in use`. The block is set by a drop-in on the user's `docker.service` (`DOCKERD_ROOTLESS_ROOTLESSKIT_DETACH_NETNS=false`, plus a `DOCKERD` wrapper that sets `net.ipv4.ip_local_port_range` in the daemon's network namespace before `dockerd` starts). The blocks sit above the host's ephemeral range (32768–60999).
3. **Packages** (Debian / Ubuntu):

   ```bash
   sudo apt-get install -y \
     git curl ca-certificates jq unzip tar zstd gzip xz-utils \
     build-essential clang lld libssl-dev pkg-config python3
   ```

   The Docker Engine must include the `buildx` plugin (`docker-buildx-plugin`); `release-images.yml` creates a BuildKit builder with it. `objdump` (from `binutils`, part of `build-essential`) is used by the release glibc guard.

   `.bazelrc` forces `CC=clang`, links with `-fuse-ld=lld` and takes OpenSSL from `/usr/include` + `/usr/lib/x86_64-linux-gnu`.

Not needed on the host:

- **Bazelisk** — `bazel-contrib/setup-bazel` downloads it (`bazelisk-version`).
- **rustup** — `dtolnay/rust-toolchain` (Rustfmt job) bootstraps rustup via `sh.rustup.rs` when it is missing. It needs `curl`.
- **Node 24 / pnpm** — `actions/setup-node` and `pnpm/action-setup` download them.

These actions write to the runner's tool cache, `RUNNER_TOOL_CACHE` (default `<runner dir>/_work/_tool`), which must stay writable by the runner user.

**Disk:** plan for ~200 GB free on the runner user's home filesystem: the Bazel output base `~/.bazel` (~25 GB with the API integration test binaries), the disk cache (≤ 150 GB), the repository cache, plus the pnpm store and Docker images.

The prerequisite check in `setup-bazel` tests exactly this list (commands, OpenSSL headers and library, and that the Docker daemon is reachable **and rootless**) and names the missing apt package for each.

## More than one runner instance

One runner instance runs one job at a time. The EX44 runs **6 instances** (`zcloud-runner-ex44`, `zcloud-runner-ex44-1` … `-5`), all with the same label, so GitHub spreads the ~25 `ci.yml` jobs across them. Give each instance **its own OS user**: `setup-bazel` rewrites `~/.bazelrc` on every job, and two instances sharing a `$HOME` would overwrite each other's rc and share one Bazel output base. Separate users also get separate disk caches.

The per-instance Bazel fractions in `setup-bazel` (`HOST_CPUS*.3`, `HOST_RAM*.25`) assume 6 instances, of which up to 4 run Bazel at once next to the Node jobs. At `HOST_CPUS*.5` the host ran 30–40 Bazel actions on 20 threads and starved Vitest. Change the instance count and you need to change those fractions too. On the EX44 the TypeScript Tests job also runs Vitest with `--testTimeout=20000` instead of the 5 s default.

## Disk housekeeping

Cleaned automatically:

- `$RUNNER_TEMP`: the runner empties it before and after every job.
- The checkout: `actions/checkout` runs `git clean -ffdx` in it.
- Service containers and their network: the runner removes them at job end.
- The Bazel disk cache: `teardown.sh` caps it per user.

Not cleaned automatically, and growing per runner user: `~/.bazel` (output base), `~/.cache/bazel-repo`, the pnpm store, `_work/_tool`, and old Docker images. Prune them with a root cron job on the host (`/usr/local/sbin/ci-runner-cleanup.sh`, five times a day on the EX44), not from a CI job, because a job would hit the running jobs of the other instances. The cron job should:

- find the runner users as the owners of `/home/*/*/.runner` (the file `./config.sh` creates),
- skip every user whose `Runner.Worker` process is running,
- delete the whole `~/.cache/bazel-repo` together with `~/.bazel` when the repository cache is larger than 15 GB. Never delete individual files in it by age: since Bazel 8 it also holds the extracted contents of external repositories (`contents/`), whose files keep the archive's old timestamps. An age-based `find -delete` strips `BUILD` files out of those repositories, and every later build fails with `'…' is not a package`.
- run `pnpm store prune`,
- delete it the same way when `~/.bazel` is larger than 35 GB,
- prune each user's own Docker daemon (its store is `~/.local/share/docker`, so image storage exists once per instance): stopped containers, volumes, and images and build cache older than 3 days; when the store is larger than 15 GB, `docker system prune -af --volumes` for that user.

---

## Developer Guide / Logging

Source: https://docs.lumio.vision/developer-guide/logging

# Logging

Lumio's frontend apps share a single env-aware structured logger from the `@lumio/logger` workspace package. It wraps `console.*` so log lines land in the SSR terminal and the browser DevTools console alike, and forwards `error` / `warn` events to Sentry when an integration is wired up. The same package also ships a ready-made Next.js request-logging helper.

The Rust API and bots stay on `tracing` + `lo-telemetry`; this logger is **frontend-only**. For the Rust side's selected ingest-error file, see [Rust services: diagnostics file](#rust-services-diagnostics-file).

## Package layout

| File | Purpose |
|------|---------|
| `shared/logger/src/index.ts` | Default logger (`logger`), factory (`createLogger`), Sentry binding (`bindSentry`). |
| `shared/logger/src/middleware.ts` | `createRequestLoggerMiddleware` - a self-contained request logger for a `proxy.ts` that has no other work to do. |

The package exports both entry points:

```ts
import { logger, createLogger, bindSentry } from "@lumio/logger";
import { createRequestLoggerMiddleware } from "@lumio/logger/middleware";
```

## Environment

The logger reads two env vars to decide what to print:

| Variable | Server | Browser | Allowed values | Default |
|----------|--------|---------|---------------|---------|
| `LUMIO_ENV` / `NEXT_PUBLIC_LUMIO_ENV` | yes | yes | `development` \| `staging` \| `production` | `development` |
| `LUMIO_LOG_LEVEL` / `NEXT_PUBLIC_LUMIO_LOG_LEVEL` | yes | yes | `debug` \| `info` \| `warn` \| `error` | per env (see below) |

`NEXT_PUBLIC_*` wins over the bare name in both cases (it is the only form the browser bundle can see, and Next.js inlines it at build time). If neither env var is set, `resolveEnv()` falls back to `NODE_ENV`, and to `development` if that is not one of the three recognised values. An unrecognised `*_LOG_LEVEL` value is ignored rather than erroring.

Default thresholds when `*_LOG_LEVEL` is absent:

- `development` → `debug` (everything)
- `staging` → `info` (no `debug`)
- `production` → `warn` (only warnings + errors)

`LUMIO_ENV` also tags Sentry events so staging and production stay on separate dashboards.

## Levels

```ts
logger.debug("...", context);
logger.info("...", context);
logger.warn("...", context);            // → Sentry capture-message
logger.error("...", error, context);    // → Sentry capture-exception
```

`error` always logs regardless of the configured threshold - errors signal real user-visible problems and must not be silenced. The other three respect the threshold.

`context` is an arbitrary `Record<string, unknown>` that gets JSON-serialised and appended to the line. It also flows through to Sentry as the `extra` payload.

## Named loggers

Use `createLogger({ name })` or `logger.child(scope)` to prefix every line with a `[scope]` tag. Useful for tracing which component produced which log.

```ts
const log = logger.child("chat-page");
log.info("Loading chat", { userId });
// → [chat-page] Loading chat {"userId":"…"}

const sender = log.child("sender");
sender.error("Failed to send", err, { platform: "twitch" });
// → [chat-page:sender] Failed to send {"platform":"twitch"} <err>
```

## Per-request access logging (`proxy.ts`)

`apps/{web,admin,id}/src/proxy.ts` (Next 16's file rename of `middleware.ts`) each own auth, token refresh, and request logging in one `proxy()` function, so none of them mounts `createRequestLoggerMiddleware` - they build a named logger with `createLogger({ name: "web" })` and emit the access line themselves at the top of `proxy()`:

```ts
const log = createLogger({ name: "web" });

export async function proxy(request: NextRequest) {
  const { pathname } = request.nextUrl;
  const ip = resolveClientIp(request);

  log.info(`${request.method} ${pathname}`, {
    ip,
    user_agent: request.headers.get("user-agent") ?? "-",
    elapsed_ms: 0,
  });
  // … auth / refresh / popout-token handling
}
```

Output:

```
[web] GET /dashboard/chat {"ip":"91.99.42.7","user_agent":"Mozilla/5.0…","elapsed_ms":0}
```

The line is emitted **before** the request is handled, so `elapsed_ms` is always `0` - treat it as an access log, not a latency metric.

Resolution order for the client IP (identical in the apps and in `createRequestLoggerMiddleware`):

1. `cf-connecting-ip` (Cloudflare proxy)
2. `x-real-ip` (Caddy / nginx / Hetzner LB)
3. First entry of `x-forwarded-for`
4. `request.ip` (only some runtimes expose it)
5. `"unknown"`

`createRequestLoggerMiddleware` additionally classifies the address as `ip_family`: `ipv4`, `ipv6`, or `unknown`, with IPv4-mapped IPv6 (`::ffff:1.2.3.4`) counted as `ipv4`. The apps' own inline logging does not emit that field.

All three apps share the same `matcher`, which skips Next internals and static image assets so hot-reload chatter doesn't drown the log:

```ts
export const config = {
  matcher: [
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)",
  ],
};
```

> **Note** - Next.js 16 expects the export to be named `proxy`, not `middleware`, and refuses to boot if a `middleware.ts` sits alongside it. Fold request-interception logic into `proxy.ts` rather than adding a second file.

## Sentry binding

`bindSentry()` wires the logger to a Sentry-compatible binding. Each Next.js app does this once at boot - server-side via `src/instrumentation.ts`, browser-side via `sentry.client.config.ts`. After binding, `logger.error` and `logger.warn` automatically forward to `Sentry.captureException` / `Sentry.captureMessage` (translating `warn` → Sentry's `warning` severity along the way).

In the browser the binding is **consent-gated**: Sentry only initializes once the user has granted the Functional cookie category, and `bindSentry(null)` unbinds it when consent is withdrawn. Server-side binding is unconditional.

The binding is optional - without a DSN, the logger still works as a plain console logger. See [Error Tracking](./error-tracking.md) for the full Sentry setup.

## Best practices

- **Never log secrets.** Tokens, passwords, OAuth secrets, session cookies - none of them should land in `context`. Sentry's `beforeSend` strips `Authorization` / `Cookie` headers, but the `context` object is up to the caller.
- **One scope per concern.** Pick a stable `name` per component / route so log filtering downstream (Loki, Grafana, Sentry) groups cleanly. Avoid stamp-of-the-day dynamic prefixes.
- **Errors as `Error` objects.** Prefer `throw new Error("msg")` and `logger.error("Failed", err, ctx)` over stringifying - Sentry's stack-frame symbolication relies on the `Error` instance.
- **`debug` is debug-only.** Production threshold defaults to `warn`; anything you put in `debug` will silently disappear in prod, which is the point. Don't put critical state-tracking there.

## Verifying it works

Local dev:

```sh
just dev-web
# in another terminal, hit a page:
curl http://localhost:4000/
# → terminal shows: [web] GET / {"ip":"127.0.0.1","user_agent":"curl/…","elapsed_ms":0}
```

Throw a test error inside a Server Action / route handler:

```ts
import { logger } from "@lumio/logger";

export async function POST() {
  try {
    throw new Error("test");
  } catch (err) {
    logger.error("test handler failed", err, { hint: "expected" });
    return new Response("ok", { status: 200 });
  }
}
```

Terminal shows the error + stack; if a Sentry DSN is configured (`SENTRY_DSN` or `LUMIO_PUBLIC_SENTRY_DSN`), the event also lands in Sentry under the matching `environment` tag.

## Rust services: diagnostics file

Every Rust service sets up logging through `lo_telemetry::init_tracing(&config.logging, "<service>")`: `api` (plus `api-migrate` / `api-geoip-update`), `twitch-bot`, `kick-bot`, `youtube-bot`, `discord-bot`, `crawler-twitch`, `bot-module-worker` and `automation-worker`. The function installs these `tracing` layers, and **each one has its own filter**:

| Layer | Filter | Output |
|-------|--------|--------|
| stdout (`[logging] format`: `json` \| `pretty`) | `RUST_LOG`, else `[logging] level` | container stdout |
| Sentry (`BreadcrumbLayer`, `ErrorLayer`, `SpanLayer`) | the same filter as stdout; then `[sentry] event_level` decides event vs. breadcrumb, and spans from `info` up become transactions | Sentry, when `[sentry]` is configured (see [Error Tracking → Rust backend](./error-tracking.md#rust-backend-lo-telemetry)) |
| diagnostics file (only when `[logging.diagnostics] enabled`) | the diagnostics selection below | `<dir>/<service>.<date>.jsonl` |

Because each layer filters independently, the file can capture a line that stdout drops. For example, production runs `level = "warn"`, but the `info` capture lines below still reach the file. `RUST_LOG` does not affect the file.

### Selection

With `all_warnings = true` (the default) the directive starts with a bare `warn` default, so every `warn` and `error` line of every component lands in the file: auth, database, cache, billing, routes, WebSocket, workers and ingest. Set `all_warnings = false` to go back to the platform sets alone.

On top of that, the directive is built from three per-platform target sets. Each target is selected at `warn`, and each platform's capture target at `info`:

| Toggle | Targets (`warn`) | Capture target (`info`) |
|--------|------------------|-------------------------|
| `twitch` | `twitch_irc`, `lo_twitch_irc`, `lo_twitch_api`, `api::workers::twitch_eventsub`, `api::workers::twitch_irc_tags`, `twitch_bot` | `ingest_diag::twitch` |
| `kick` | `lo_kick_api`, `api::workers::kick` (prefix, so it covers every `kick_*` worker), `api::services::kick_webhook_events`, `api::routes::webhooks`, `kick_bot` | `ingest_diag::kick` |
| `youtube` | `lo_youtube_api`, `api::workers::youtube`, `api::workers::innertube_credentials`, `api::routes::webhooks`, `youtube_bot` | `ingest_diag::youtube` |

Target matching is prefix-based (`starts_with`). `api::routes::webhooks` would therefore also match `api::routes::webhooks_payments`, and `all_warnings` selects every target anyway. Whenever `all_warnings`, Kick or YouTube is on, the selection adds `api::routes::webhooks_payments=off`. Payment-webhook logs carry billing data and never reach the file.

`filter` is a comma-separated `EnvFilter` directive string that is merged **after** the platform sets. A directive whose target a platform set already names replaces that entry, a bare level (`error`, `info`, …) replaces the `all_warnings` default, and any other directive is appended. The merge happens by target in code, not by string concatenation, so precedence is deterministic. The toggles switch a whole platform on or off; `filter` fine-tunes. Examples:

- `twitch_irc=off`: drops the `twitch-irc` library warnings and keeps the rest of the Twitch set.
- `lo_kick_api=debug`: raises one target's level.
- `error`: only errors from every component (plus the platform sets and capture lines).
- `ingest_diag=info` with `all_warnings` and all three toggles off: only the capture lines.

### The `ingest_diag::<platform>` convention

A log line that exists to capture the payload of something ingest does not understand yet uses the stable target `ingest_diag::<platform>` instead of its module path. The filter then selects it by intent, not by file location. Each line fires on the **first sighting per process** of a given type. The set is capped at 64 types, and lines are never lost to the cap. Repeats log at `debug` on the module target, or not at all.

| Platform | Line | Fields |
|----------|------|--------|
| Twitch | Unrecognized `channel.chat.notification` `notice_type`: one that is neither mapped nor in the worker's list of types Twitch documents (`DOCUMENTED_UNMAPPED_NOTICE_TYPES`). Twitch's catch-all `unknown` is logged (`api::workers::twitch_eventsub`) | `notice_type`, `event` (raw EventSub event) |
| Kick | Unhandled webhook event type (`api::services::kick_webhook_events`). The module-level `warn!` stays the stdout signal | `event_type`, `data` (raw event data) |
| YouTube | InnerTube chat item whose renderer no typed field matched (`lo_youtube_api::innertube::parser`). `ChatItem::other` (`#[serde(flatten)]`) keeps the unknown renderer key | `renderer`, `item` (renderer body) |

When you add a new "unknown type, dropping" path, give it the same treatment: a bounded first-sighting set plus `info!(target: "ingest_diag::<platform>", …)`.

### Keys

All keys live under `[logging.diagnostics]`, in every service's `config/default.toml`. Each key can be set from TOML or ENV (`<PREFIX>__LOGGING__DIAGNOSTICS__<KEY>`, prefixes listed in [Installation](../getting-started/installation.md#diagnostics-file-rust-services)).

| Key | Default | Meaning |
|-----|---------|---------|
| `enabled` | `false` | Master switch. While off, no file and no directory is created. |
| `dir` | `data/diagnostics` | Target directory, relative to the working directory (`/app` in containers). |
| `all_warnings` | `true` | Select every `warn`/`error` line of every target (bare `warn` default). |
| `twitch` / `kick` / `youtube` | `true` | Add that platform's target set. |
| `filter` | `""` | Extra `EnvFilter` directives (see above). A single scalar string, never a list key. |
| `rotation` | `daily` | `daily` (`<service>.YYYY-MM-DD.jsonl`) or `hourly` (`<service>.YYYY-MM-DD-HH.jsonl`). Rotation boundaries are UTC. |
| `max_files` | `14` | Rotated files kept per service, which is the retention bound (14 days with daily rotation). Must be ≥ 1. Old files are pruned whenever a new file is opened, so a service that is switched off leaves its last files on disk until they are removed by hand. |
| `format` | `json` | `json`: one `fmt::layer().json()` object per line, `.jsonl`. `compact`: one text line, `.log`. |
| `redact_user_fields` | `false` | Replaces viewer names and message text with `"[redacted]"` **in the file only**. |

The writer is `tracing-appender` behind a **non-blocking, lossy** channel. A stalled disk drops diagnostics lines instead of blocking a Tokio worker. The `TelemetryGuard` returned by `init_tracing` flushes the channel when it is dropped, so hold it for the whole process (`let _telemetry = …`).

### Redaction

With `redact_user_fields = true`, the file layer redacts:

- **Top-level fields** whose key names a person or what they wrote: keys ending in `user_name`, `user_login`, `display_name` or `author_name`, plus `username`, `login`, `slug`, `sender`, `author`, `text`, `content`, `chat_message`, `message_text`, `system_message`. Matching ignores case, `_` and `-`. tracing's own `message` field (the log text) is exempt.
- **JSON documents logged as a field** (`event = %json`), redacted recursively. Under a matching key (here `message` counts too), every string leaf becomes `"[redacted]"`, except `id`, `*_id` and `type`.

IDs, event types, numbers, unknown keys and the document structure stay, so "what does this new event look like" still works. Stdout is never redacted.

### Fail-open

The service never refuses to start because of the diagnostics file. Each of these cases logs one `warn!`, `Diagnostics file disabled, continuing on stdout only: <reason>`, naming the key, and the service runs with stdout and Sentry only:

- `dir` is not writable
- `filter` does not parse
- `rotation` or `format` has an unknown value
- `max_files = 0`
- the selection is empty (`all_warnings` and all three platforms off, `filter` empty)

### Where it runs and how to read it

On staging, `api`, `twitch-bot`, `kick-bot` and `youtube-bot` enable the file in their `staging.toml`, and `api` also in its `production.toml`. The bots have no `production.toml`, so production enables them through `<PREFIX>__LOGGING__DIAGNOSTICS__ENABLED=true`. The image creates `/app/data/diagnostics`, owned by uid 1001. Every staging compose file bind-mounts `${DIAGNOSTICS_DIR:-./data/diagnostics}` there; without the mount the file would disappear with the container. The host directory must belong to uid 1001 (`sudo install -d -o 1001 -g 1001 data/diagnostics`; see `dev-stack/staging/README.md`).

```bash
jq -c 'select(.target | startswith("ingest_diag"))' data/diagnostics/*.jsonl
jq -c 'select(.level == "ERROR")' data/diagnostics/kick-bot.*.jsonl
```

The diagnostics file is telemetry. It emits no audit event and needs no permission.

---

## Developer Guide / Error Tracking (Sentry)

Source: https://docs.lumio.vision/developer-guide/error-tracking

# Error Tracking (Sentry)

Lumio's four Next.js apps - `apps/web`, `apps/admin`, `apps/id`, `apps/shopify` - each ship with a `@sentry/nextjs` integration. `apps/stats` has none. The Rust backend is on `sentry-rust` via `lo-telemetry`, covered in [Rust backend](#rust-backend-lo-telemetry) at the end of this page.

When no DSN is configured, the integration is a no-op - apps boot normally, no events are sent. Local dev typically leaves the DSN blank; staging and production supply it via the container environment at **run time** (`LUMIO_PUBLIC_SENTRY_DSN`, see [Environment variables](#environment-variables)).

> **Browser Sentry is consent-gated (web, ID) or off (admin, Shopify):**
> A DSN alone is **not** enough. Sentry is classified as a *Functional* cookie in the published policy (§ 25 TDDDG / GDPR), so the browser SDK stays fully inert - no `Sentry.init`, no capture, no storage writes, no network traffic - until the user grants `functional` consent. `apps/web` and `apps/id` each keep the lifecycle logic in `src/lib/sentry-consent.ts` (`syncSentryConsent()`).
> 
> The DSN reaches the browser at request time: the root layout (a server component) calls `getBrowserSentryConfig()` from `src/lib/config.ts` and passes `dsn` and `environment` as props to `<SentryConsentSync />`. The release images are built without a DSN, and a `NEXT_PUBLIC_*` value is frozen at `next build`, so a DSN read from `process.env.NEXT_PUBLIC_SENTRY_DSN` in browser code would always be empty in a deployed image.
> 
> `<SentryConsentSync />` boots the SDK and re-runs the sync when the preference changes at runtime; a cross-tab `storage` listener tears the client down on withdrawal in another tab. It is mounted inside `ConsentProvider` in `apps/web/src/app/(main)/layout.tsx` and in the root layout of `apps/id`. Consent is read from the `lumio_cookie_consent` localStorage key via `getStoredConsent()` from `@lumio/cookies-consent` - that stored choice is the single source of truth, even on routes where `ConsentProvider` runs in exempt mode.
> 
> `<SentryConsentSync />` is the entry point that actually matters: Next 16 builds with Turbopack, and `@sentry/nextjs` only injects `sentry.client.config.ts` into webpack builds. Under `next dev` / `next build` that file is never loaded, so anything placed only there does not run in the browser.
> 
> The extension Supervisor and Runtime frames follow the same rule - see [Extension Supervisor and Runtime](#extension-supervisor-and-runtime).
> 
> `apps/admin` has no consent banner, so it runs **no** browser Sentry at all: its `sentry.client.config.ts` is intentionally empty. Server-side capture (`src/instrumentation.ts`) is unaffected. Give the admin app a consent surface before adding a browser `Sentry.init` there.
> 
> `apps/shopify` follows the admin pattern for the same reason. Its embedded page renders inside the Shopify admin iframe and has no consent surface, so `sentry.client.config.ts` is empty and the CSP that `src/proxy.ts` sets has no Sentry origin in `connect-src`. Only the server runtime reports errors: the HMAC check and CSP in `src/proxy.ts`, the page's server render and the `src/app/api/*` forward routes.

## Files per app

Each of `apps/{web,admin,id,shopify}/` has the same five files (paths relative to the app):

| File | Loaded by | Purpose |
|------|-----------|---------|
| `next.config.ts` | build | Wraps `withSentryConfig` (source-map upload, build-time injection) |
| `sentry.client.config.ts` | browser (webpack builds only) | In `apps/web` and `apps/id` a one-line delegate to `syncSentryConsent()` (build-inlined DSN only); empty in `apps/admin` and `apps/shopify`. Turbopack never loads it - see the caution above |
| `src/sentry.server.config.ts` | Node runtime | SSR / route-handler / Server-Action capture |
| `src/sentry.edge.config.ts` | Edge runtime | Edge route handlers |
| `src/instrumentation.ts` | server | `register()` imports the right runtime config and binds the logger (`apps/shopify` has no `@lumio/logger`, so nothing to bind); also exports `onRequestError = Sentry.captureRequestError` |

> **`instrumentation.ts` belongs in `src/`:**
> All four apps use the `src/` layout (`src/app`, `src/proxy.ts`). Next.js looks up `instrumentation.ts` - like `proxy.ts` and `instrumentation-client.ts` - only in the folder that holds `app/`, so here in `src/`. A copy in the app root is ignored without a warning: `register()` never runs, and server-side Sentry, the logger binding and `onRequestError` are all off whatever DSN is set. `apps/web/__tests__/next-convention-files.test.ts` fails if a convention file sits in the app root of `web`, `admin`, `id`, `stats` or `shopify`, and checks that `web`, `admin`, `id` and `shopify` register their runtime configs from `src/instrumentation.ts`. After `next build` the server output contains `.next/server/instrumentation.js`; if that file is missing, the hook was not found.

Configuration is duplicated across the four apps on purpose - the apps evolve independently. The browser side differs on purpose: `apps/web` and `apps/id` are consent-gated, `apps/admin` and `apps/shopify` have no browser Sentry, and none of them uses Session Replay. The server and edge configs are identical in web, admin and ID; `apps/shopify` has the same settings with a stricter scrub (see [What gets stripped](#what-gets-stripped)).

## Environment variables

| Variable | Where | Purpose |
|----------|-------|---------|
| `LUMIO_PUBLIC_SENTRY_DSN` | Run time (browser + server) | Public DSN. Read per request by the root layout and handed to the browser SDK (web and ID, after Functional consent); also the server fallback. This is the name to set on deployed containers. `apps/web` also adds its ingest origin to the CSP `connect-src`. |
| `NEXT_PUBLIC_SENTRY_DSN` | Build time | Local-dev fallback for `LUMIO_PUBLIC_SENTRY_DSN`. Inlined at `next build`, so setting it on a container of a prebuilt image has no effect. |
| `SENTRY_DSN` | Server only | Optional - falls back to `LUMIO_PUBLIC_SENTRY_DSN`, then `NEXT_PUBLIC_SENTRY_DSN`. Useful when you want the SSR / Edge runtimes on a different project than the browser. In `apps/admin` and `apps/shopify` it is the only DSN that matters (no browser SDK). |
| `SENTRY_ORG` | Build (CI) | Sentry org slug - required for source-map upload. Leave blank locally. |
| `SENTRY_PROJECT` | Build (CI) | Sentry project slug - same. |
| `SENTRY_AUTH_TOKEN` | Build (CI) | Auth token for source-map upload. Generate one in Sentry → Settings → Auth Tokens. |
| `LUMIO_ENV` / `NEXT_PUBLIC_LUMIO_ENV` | Both | Tags every event with the environment (`development` / `staging` / `production`). Falls back to `NODE_ENV`. The browser SDK gets `LUMIO_ENV` from the root layout at request time, like the DSN. |

Source-map upload only runs when `SENTRY_AUTH_TOKEN` + `SENTRY_ORG` + `SENTRY_PROJECT` are all set - typically only in CI for staging / production builds.

## What gets captured

- **Unhandled exceptions** in browser code (React error boundaries, Promise rejections, sync throws) - web and ID only, and only after Functional consent. Never in admin or Shopify.
- **SSR / route-handler errors** through the `onRequestError` export in `src/instrumentation.ts` (Sentry's recommended hook).
- **Anything emitted via `logger.error(...)` or `logger.warn(...)`** - the logger calls `Sentry.captureException` / `Sentry.captureMessage` when bound. See [Logging](./logging.md) for the binding details.

## What gets stripped

`beforeSend` in every runtime config deletes the `authorization` and `cookie` keys from `event.request.headers` before the payload leaves the process. In the Next.js apps, `sendDefaultPii: false` keeps Sentry's automatic IP / user-agent collection off, so cookie-issued JWTs and popout tokens never end up in Sentry; the extension frames get the same from `dataCollection` (see [Extension Supervisor and Runtime](#extension-supervisor-and-runtime)).

`apps/shopify` strips more, in `src/lib/sentry-scrub.ts`, through both `beforeSend` and `beforeSendTransaction`. The embedded page is opened with Shopify's launch query, and the forward routes carry Lumio and order data:

- the `authorization` and `cookie` headers (any casing), `request.cookies` and `request.data` (no request body is ever attached);
- the query params `id_token`, `hmac`, `session`, `code` and `state` are replaced with `[Filtered]` in `request.url` and `request.query_string`, and in the string values of span data and breadcrumb data (where transactions repeat the URL as `url.full` / `http.query`).

`apps/shopify/__tests__/sentry-scrub.test.ts` covers it with a URL that carries all five params.

If you want to enrich events with explicit user info (e.g. account ID), set it manually after login:

```ts
import * as Sentry from "@sentry/nextjs";

Sentry.setUser({ id: account.id, ip_address: undefined });
```

`ip_address: undefined` opts out of Sentry's IP capture even if `sendDefaultPii` ever flips on later.

## Session Replay

**Not enabled in any app.** Replay was removed from `apps/web` under ZAF-91 and from `apps/id` / `apps/admin` under ZAF-2681 - it is the highest-PII component, and the privacy policy states that Lumio does not use it. Do not re-add it, even consent-gated, without a disclosed processing entry in the policy first.

## Performance traces

`tracesSampleRate` is `0.1` when `NODE_ENV === "production"` (10 % of transactions) and `1.0` everywhere else, in all four apps on both the browser and server sides.

## Suppressed noise

`denyUrls` on the browser side is the same list in all three apps:

```ts
denyUrls: [/extensions\//i, /^chrome:\/\//i, /^moz-extension:\/\//i, /^safari-web-extension:\/\//i]
```

Note the second entry matches the `chrome://` internal scheme, not `chrome-extension://` - the generic `/extensions\//i` pattern is what catches Chrome extension frames. Add entries when you see recurring noise from a specific extension or third-party script.

## Adding a new captured event manually

Most code should just throw / call `logger.error`. For business-event tracking (e.g. "user upgraded plan"), use Sentry's `addBreadcrumb` or `captureMessage` directly:

```ts
import * as Sentry from "@sentry/nextjs";

Sentry.captureMessage("user upgraded plan", {
  level: "info",
  extra: { account_id: accountId, plan_slug: plan.slug },
});
```

These don't surface as errors but let you search them in Sentry's "Issues" tab when triaging.

## Debugging the integration locally

Set the DSN in `.env.local`:

```
NEXT_PUBLIC_SENTRY_DSN=https://<key>@o<org>.ingest.sentry.io/<project>
LUMIO_ENV=development
```

`LUMIO_PUBLIC_SENTRY_DSN` works the same way. In `apps/web` and `apps/id` you must **also** accept the Functional cookie category in the consent banner (or the browser SDK stays inert and nothing is sent). To reset, clear the `lumio_cookie_consent` localStorage key and reload.

Then trigger an error from any client component:

```tsx
"use client";

import { useEffect } from "react";

export default function DebugPage() {
  useEffect(() => {
    throw new Error("sentry smoketest");
  }, []);
  return null;
}
```

Reload the page, open Sentry → Issues, the event should land within a few seconds with `environment: development`. Filter that out before shipping or the dashboard fills with smoketest noise.

## Extension Supervisor and Runtime

`apps/extension-supervisor` and `apps/extension-runtime` run in the browser as iframes inside the dashboard and inside OBS overlays and widgets. Each has `@sentry/browser` with a build-time DSN (`SENTRY_DSN_SUPERVISOR` / `SENTRY_DSN_RUNTIME`), and neither can read the user's consent itself, so the host page decides:

- `ExtensionWorkerManager` sends `errorTracking: true` in the Supervisor `init` message only when the host sets its `errorTracking` prop **and** `getStoredConsent()` grants Functional consent. Only dashboard hosts set the prop (widget editor, extension designer). The OBS hosts `/overlay` and `/widget` have no consent surface and never set it, so Sentry stays off there.
- The Supervisor calls `Sentry.init` only on such an `init`, and adds `errorTracking=1` to the Runtime frame URL (dropping any such parameter already in `extensionUrl`). The Runtime calls `Sentry.init` only with that parameter.
- Without it, both frames' `Sentry.captureMessage` calls are no-ops. The decision is taken when the frame starts; a frame started before the user withdraws consent keeps it until it is reloaded. No Session Replay in either frame.

Both frames are on `@sentry/browser` 11, which has no `sendDefaultPii`. Its replacement `dataCollection` collects user info, cookies and request/response bodies when left unset, so both `Sentry.init` calls pin it to the restrictive baseline: no user info, cookies, bodies, GenAI/MCP inputs and outputs, database query data, queue data or GraphQL documents, and IP-revealing headers and query parameters (`forwarded`, `-ip`, `remote-`, `via`, `-user`) denied. Do not drop or loosen that block. The Next.js apps are still on `@sentry/nextjs` 10 and keep `sendDefaultPii: false`.

## Rust backend (`lo-telemetry`)

Every Rust service calls `lo_telemetry::init_sentry(&config.sentry, "<service>")` before `init_tracing`. Sentry stays off unless `[sentry] enabled = true` **and** `dsn` is set; config keys and ENV names are in [Installation → Error tracking (Rust services)](../getting-started/installation.md#error-tracking-rust-services). The service names are the same as the diagnostics file's: `api`, `twitch-bot`, `kick-bot`, `youtube-bot`, `discord-bot`, `crawler-twitch`, `bot-module-worker`, `automation-worker` and `innertube-proxy`. The proxy has no TOML config and builds its `[sentry]` / `[logging]` values from env vars, see [InnerTube Proxy → Logging and error tracking](./innertube-proxy.md#logging-and-error-tracking).

### Events and breadcrumbs

`init_tracing` installs three Sentry `tracing` layers from `sentry::integrations::tracing`, each behind the stdout filter (`RUST_LOG` / `[logging] level`) plus a filter of its own: `BreadcrumbLayer` (breadcrumbs), `ErrorLayer` (events) and `SpanLayer` (spans from `info` up become transactions, sampled by `[sentry] traces_sample_rate`). There is no `LogLayer`, so no Sentry structured logs are sent. For every line that passes the stdout filter, `[sentry] event_level` decides:

| Level | `event_level = "warn"` (default) | `event_level = "error"` |
|-------|----------------------------------|-------------------------|
| `error` | event + breadcrumb | event + breadcrumb |
| `warn` | event + breadcrumb | breadcrumb |
| `info` | breadcrumb | breadcrumb |
| `debug` / `trace` | nothing | nothing |

The breadcrumb layer runs before the error layer, so an event's own line is already its last breadcrumb. `init_tracing` reads `event_level` once, from the value `init_sentry` stored; that is why `init_sentry` must run first. With Sentry off the layers keep the library default (`error` → event, `warn`/`info` → breadcrumb).

Panics are captured by the default `sentry` panic integration.

Lines from the `twitch_irc` library (`twitch_irc` and its submodules) are breadcrumbs only, whatever their level (`BREADCRUMB_ONLY_TARGETS` in `crates/lo-telemetry/src/sentry_events.rs`). The library logs every dropped pool connection, missing PONG and server `RECONNECT` at `error` and rebuilds the connection itself. A lasting outage is reported by the silence watchdog in `lo-twitch-irc` (`crates/lo-twitch-irc/src/silence.rs`): when a client has joined channels and receives nothing for 5 minutes, it logs `error` "Twitch IRC receives nothing while channels are joined, connections keep failing" once per outage, under its own `lo_twitch_irc` target. twitch-irc pings every open connection every 30 s and forwards the PONG, so a healthy pool is never silent that long.

### Reconnect loops

An upstream WebSocket that drops and reconnects is expected behaviour, not an error. A worker logs a single drop or failed reconnect at `info`, and `error` only when the reconnect keeps failing: at `RECONNECT_ERROR_THRESHOLD` (5) consecutive failures and every further 5, decided by `lo_common::reconnect_failure_is_persistent`. The escalation has its own fixed message, so it groups into one Sentry issue:

| Worker | Drop / single failure (`info`) | Lasting failure (`error`) |
|--------|-------------------------------|---------------------------|
| StreamElements (`api::workers::streamelements`) | `StreamElements connection lost, reconnecting` | `StreamElements reconnect keeps failing` |
| Twitch EventSub (`lo_twitch_api::eventsub`, `api::workers::twitch_eventsub`) | `EventSub WebSocket read error, reconnecting`, `EventSub keepalive timeout exceeded, reconnecting`, `Failed to connect to EventSub, retrying` | `EventSub reconnect keeps failing` |
| Kick bot Pusher chat (`kick_bot::bot`) | `Failed to connect to Kick WebSocket — retrying`, `Kick WebSocket error — reconnecting`, `Kick WebSocket closed by server — reconnecting` | `Kick WebSocket reconnect keeps failing` |

The StreamElements and Kick bot counters reset when a connection stayed up for 60 s (the Kick bot counts failed connects and connections that ended sooner), the EventSub counter when a new session took its subscriptions. Every line carries `consecutive_failures`. New reconnect loops follow the same pattern.

### GraphQL request log levels

`POST /v1/gql` logs one line per request. A response with errors gets its level from the errors' `extensions.code`, not from their message (`classify_error_log_level` in `apps/api/src/graphql/mod.rs`):

| Errors in the response | Level | Message |
|------------------------|-------|---------|
| Every error is the uncoded `Authentication required` literal (unauthenticated popout pages) | `debug` | `GraphQL auth-required (unauthenticated request)` |
| Every error has an expected client code: `NOT_FOUND`, `UNAUTHORIZED`, `UNAUTHENTICATED`, `VALIDATION_ERROR`, `BAD_REQUEST`, `PLAN_LIMIT_REACHED`, `FEATURE_DISABLED` (the `Authentication required` literal also counts) | `info` | `GraphQL request with expected client errors` |
| Anything else: a server fault, `FORBIDDEN`, an error without a code, or a mix of expected and unexpected | `warn` | `GraphQL request with errors` |

So a missing history report or a dead refresh token is a breadcrumb, not a Sentry issue. `FORBIDDEN` stays `warn` on purpose: a refused permission check is a security signal. A resolver error only gets an expected level if it carries a code, so new resolvers map their failures through `ApiError` + `crate::graphql::errors::to_graphql_error`. Resolvers that answer with a bare message such as `Overlay not found` or `No active account` use `crate::graphql::errors::{not_found, unauthorized, bad_request}` instead: they add the code of the REST twin's `ApiError` variant and leave the message unchanged. A bare `async_graphql::Error::new(…)` has no code and is logged at `warn`, so keep it for real faults (e.g. a row missing right after it was written). `graphql_requests_total{outcome="error"}` counts every response with errors, whatever its log level.

### What every event carries

- `release = "<service>@<version>"`, with the workspace product version, so a regression can be tied to a release. `server_name` is the service name. The release workflow fills that release with commits and debug files, see [Releases, commits and debug files](#releases-commits-and-debug-files).
- Tags `service` and `target` (the log target, e.g. `api::workers::twitch_eventsub`), plus these fields when the log line has them: `platform`, `sub_type`, `notice_type`, `event_type`, `error_kind`. IDs (`account_id`, `channel_id`, `user_id`, …) stay in the *Rust Tracing Fields* context and are never tags, because tags must stay low-cardinality.
- Fingerprint `[target, message template]`, where the template is the message with every digit run replaced by `<n>`. "Pool connection 3 has failed" and "Pool connection 7 has failed" are one issue. The stack trace stays on the event.

### What gets stripped

`before_send` and `before_breadcrumb` always remove viewer names and message text from the event's fields and breadcrumb data. They use the same key lists as the diagnostics file's `redact_user_fields` (`crates/lo-telemetry/src/redact.rs`), including JSON documents logged as a field. This cannot be switched off. IDs, event types and numbers stay. The log message itself is not rewritten, so never interpolate a viewer name into the message string: log it as a field.

### Volume guard

One bad token can log the same error dozens of times per start, e.g. one `Failed to create EventSub subscription` per subscription type. The guard sends at most `max_events_per_fingerprint` (default 10) events per fingerprint per `fingerprint_window_secs` (default 60). The rest is dropped and counted. The first event of the next window carries the count as `suppressed_count` in the *Volume Guard* context. The guard lives in the process (no Redis), remembers up to 1024 fingerprints (least recently seen is evicted) and fails open. `max_events_per_fingerprint = 0` switches it off.

### Releases, commits and debug files

`release-images.yml` (Build & Push job) has a step *Sentry release, commits and debug files*. It runs after every image of the run is pushed, signed and promoted, for each Rust app the run built:

1. **Release.** It creates the release `<app>@<version>` in the Sentry project `<app>`, or reuses it if the SDK already created it with the first event. `<version>` is `[workspace.package] version` from the root `Cargo.toml`: the `CARGO_PKG_VERSION` the binary reports. It is not the release tag or the `workflow_dispatch` input. The step also finalizes the release.
2. **Commits.** `sentry-cli releases set-commits <release> --commit zaflun/lumio@<sha>` uses the GitHub integration of the Sentry org. Sentry computes the range from the previous release; a release without a predecessor gets the last 20 commits. A shipped commit whose message contains `Fixes <SHORT-ID>` resolves that Sentry issue with the release. Sentry fetches the commits in the background, so the step waits (up to 120 s) until the release reports them before it moves to the next app. Back-to-back fetches for all apps of one run left `api@2026.10.317` with 0 commits. Every app's release gets the same commits, and Sentry resolves a `Fixes` issue in the **last** release that received the commit. That is why `api`, which owns the issues, is always processed last.
3. **Debug file.** It splits the debug info off the app's **unstripped** binary (`objcopy --only-keep-debug --compress-debug-sections=zlib`) and uploads that *debug companion* with `sentry-cli debug-files upload`. The companion has the binary's GNU build-id and therefore the same debug id. The unstripped `api` binary is about 1 GB, the companion only a fraction of it. Symbolication then shows file and line for Rust frames.

**No deploy is reported.** The workflow pushes images and moves the `beta`/`latest` channel tags; it does not deploy. Staging pulls `:beta` on the host (`dev-stack/staging/verified-pull.sh`). The SDK's `environment` already tells staging and production events apart.

**Apps without a Sentry project** are skipped with a warning. Every Rust app in `RUST_APPS` has a project today. A new app needs a project named exactly like the app (the service name).

**Upload size limit.** `sentry-cli` uploads debug files in 8 MiB chunks, several per request; the server's `GET /api/0/organizations/<org>/chunk-upload/` reports `chunkSize` and `maxRequestSize` (32 MiB). Every proxy in front of Sentry must accept request bodies of that size. A proxy with nginx's default `client_max_body_size 1m` answers `413 Request Entity Too Large`, and the step logs `debug-files upload failed`.

**Where the debug info comes from.** `--config=release` (`.bazelrc`) adds `-Cdebuginfo=line-tables-only -Cstrip=none` through `@rules_rust//rust/settings:extra_rustc_flag`. rules_rust appends these after its `opt` defaults (`-Cdebuginfo=0 -Cstrip=debuginfo`), so they win. Line tables are the smallest level that still maps an address to file and line, inlined frames included. The `rust_binary` therefore keeps its line tables. Each app's `image_layer` packs `:<app>_stripped` instead: the `strip_debug` rule (`misc/strip_debug.bzl`) runs the C++ toolchain's `objcopy --strip-debug`. That removes the DWARF sections and keeps the symbol table, the GNU build-id note and `.eh_frame`. The image binary has the same Sentry debug id as the uploaded file, and in-process backtraces keep their function names. **The debug info never enters the image.** CI (`fastbuild`) is not affected: the flags only live in `--config=release`, and the `_stripped` targets are `manual`.

**Token and settings.** The step reads three repository settings:

| Setting | Kind | Value |
|---------|------|-------|
| `SENTRY_RELEASE_TOKEN` | secret | A Sentry **Organization Auth Token** (organization settings, *Organization Tokens*). Its only scope is `org:ci`: create releases, set commits, upload debug files. It cannot read issues or events. |
| `SENTRY_URL` | variable | the base URL of the Sentry instance |
| `SENTRY_ORG` | variable | the org slug |

The token reaches `sentry-cli` only as the `SENTRY_AUTH_TOKEN` environment variable of that step, never in argv or the log. The triage token the agents use (`event:read` and friends) has no release scope and is not used here.

**Fail-open.** The step has `continue-on-error: true` and always exits 0. A missing secret or variable, an unreachable Sentry, a missing project or a failed upload each log a `::warning` and the release still publishes its images. `sentry-cli` is a pinned GitHub release binary checked against its SHA-256 (`SENTRY_CLI_VERSION` / `SENTRY_CLI_SHA256` in the step). When you bump it, take the digest from the release asset (`gh api repos/getsentry/sentry-cli/releases/tags/<version>`, field `digest`).

**Checking a release.** The step log prints `<release>: <n> commits` per app. In Sentry, *Releases → `<app>@<version>`* shows the commit count. On a new event from that release, the Rust frames carry `filename` and `lineno`, and *Settings → Projects → `<app>` → Debug Files* lists the uploaded binary.

Sentry is telemetry: no audit event, no permission.

---

## Developer Guide / Observability - Prometheus + Grafana (Staging)

Source: https://docs.lumio.vision/developer-guide/observability-staging

# Observability - Prometheus + Grafana (Staging)

Single-node Prometheus + Grafana for the staging environment. Configuration is
versioned in the repo under `dev-stack/staging/observability/` and deployed with
Docker Compose - never hand-clicked on the host (ZAF-675).

**The rule behind the split:** operational/telemetry data → Prometheus; product
data → TimescaleDB. There is **no third time-series store** (no InfluxDB). The
full decision and sizing analysis live on ZAF-672 (`plan`, rev 2); the
instrumentation that exposes `/metrics` on each Rust service is ZAF-674
(`lo-metrics`).

**Tiering.** Like the message brokers (ZAF-655), staging runs a **single node**.
The multi-node / HA build is production on k3s (ZAF-61) and is tracked
separately - this stack is **not** k3s-gated.

## What ships

```
dev-stack/staging/
├── observability.docker-compose.yml        # Prometheus + Alertmanager + Grafana
├── .env.observability.example              # Grafana admin credentials template
└── observability/
    ├── prometheus/
    │   ├── prometheus.yml                   # scrape config (30 s interval) + alerting
    │   ├── rules/recording_rules.yml        # 5-min + 1-h rollups
    │   ├── rules/alerting_rules.yml          # alert rules (ZAF-687 + ZAF-676)
    │   └── targets/crawler-twitch.json      # file_sd for the crawler host
    ├── alertmanager/
    │   ├── alertmanager.yml                  # severity routing (page | ticket)
    │   └── secrets/                          # webhook URLs (git-ignored, host-provisioned)
    └── grafana/
        ├── provisioning/
        │   ├── datasources/datasource.yml   # Prometheus datasource
        │   └── dashboards/provider.yml      # dashboard provider ("Lumio" folder)
        └── dashboards/                       # versioned dashboard JSON
```

## Retention (why the numbers are acceptance criteria)

The founder's objection on ZAF-672 was **long-term** query performance.
Prometheus keeps only **15 days** by default; anything not retained in the first
months is gone forever. So the long window is present in the **first** config,
not a later phase:

- `--storage.tsdb.retention.time=400d` - ≥ 400 days.
- `--storage.tsdb.retention.size=90GB` - disk-safety guard below the ≥ 100 GB
  volume. With the sizing estimate below, **time** is the binding limit.
- The Prometheus data volume must be backed by **≥ 100 GB** of persistent disk.

**Sizing** (plan §4a): ~10 Rust services, ~15 000 active series, 30-s scrape,
~2 B/sample → ~86 MB/day ≈ **31 GB/year**; 13 months ≈ 35 GB. The 400-day window
fits comfortably inside 100 GB.

To pin the TSDB to a dedicated disk, back the `staging-prometheus-data` named
volume with a `driver_opts` bind (documented inline in the compose file) and
`chown 65534:65534` the target directory.

## Scrape config

- **Interval: 30 s** (not 15 s) - trend/alarm-adequate and half the long-term
  storage cost.
- Targets are each Rust service's internal `/metrics` (served by `lo-metrics` on
  the internal health server). Every series already carries the constant labels
  `service` and `env`, so the scrape does **not** re-label `service`; it adds
  only `job` (= service name) and `instance`.
- **Cardinality rule (hard):** the `/metrics` exposition never carries
  `account_id` / `channel_id` / `user_id` / `session_id` / raw URL paths.
  Per-channel stream history stays in `channel_history_stats`, never Prometheus.

Internal metrics ports - reconciled against the actual ZAF-674 wiring
(ZAF-679). The port comes from `config/default.toml` where a bot overrides its
`src/config.rs` struct default, so the two disagree; the **TOML value wins**.

| Service | Target | Source of port | Status in staging |
|---------|--------|----------------|-------------------|
| api | `staging-api:9100` | `apps/api/src/config.rs` `MetricsConfig` default `127.0.0.1:9100`; served by `lo_metrics::serve` | needs `LUMIO__METRICS__HOST=0.0.0.0` in `.env.api` (loopback is unreachable from the Prometheus container) |
| twitch-bot | `staging-twitch-bot:3001` | `apps/twitch-bot/config/default.toml` `[health] port` (overrides 9090) | up when the bot runs - `/metrics` on the health server (`src/health.rs`) |
| youtube-bot | `staging-youtube-bot:3002` | `config/default.toml` `[health] port` | " |
| kick-bot | `staging-kick-bot:3003` | `config/default.toml` `[health] port` | " |
| discord-bot | `staging-discord-bot:3005` | `config/default.toml` `[health] port` | " |
| redis | `staging-redis-exporter:9121` | `oliver006/redis_exporter` in `infra.docker-compose.yml` (Redis `INFO`, not `lo-metrics`) | up with the infra stack - see [Data layer (staging)](./data-layer-staging.md) |
| crawler-twitch | `file_sd` (empty) | health server `:8080` (ZAF-595 §7) | **operator-maintained, empty in staging** - see below |

The scrape set is **exactly** the seven jobs above (plus Prometheus itself) - the
services that actually run in staging. There are no static jobs for services
that staging does not deploy, so there are no dead `up == 0` targets by
construction.

**Instrumented but deliberately NOT scraped (ZAF-684).** Several Rust services
carry `lo-metrics` `/metrics` yet get **no** staging job on purpose. "Instrumented"
is not "deployed": a static job pointed at a container staging never starts would
be a permanent `up == 0` target - precisely the silent failure the acceptance
criterion forbids. Staging runs only `api` + `admin` + `id` + `web` + the five
bots + `infra` + `observability`; nothing else.

- **`bot-module-worker`, `automation-worker`** - no staging compose exists. Add a
  job only when one lands under `dev-stack/staging/`.
- **`innertube-proxy`** - runs deliberately **outside** the cluster on a
  trusted-IP host (`AGENTS.md`; `developer-guide/innertube-proxy.md`), so it is
  never on the `lumio-staging` network.
- When any of these later gets a staging compose, the scrape port is already
  fixed at **`:9100`** - its own internal metrics server, same layout as
  `apps/api` - assigned to the Rust backend in **ZAF-683** (which moves `/metrics`
  off the `3100`/`8090`/`8091` payload port). Nothing needs coordinating first.
- **crawler-twitch** ships through `release-images.yml` like every other Rust
  app, but has no staging compose: by design it runs on its own
  trusted-IP host (ZAF-595 §4), off the `lumio-staging` network. Its `file_sd`
  file (`targets/crawler-twitch.json`) is therefore **operator-maintained** and
  ships **empty** - an operator adds the real host:port out-of-band. An empty
  `file_sd` yields **no** target and **no** `up` series - a deliberate,
  documented absence, not a dead placeholder.

**Watch the `job:up:min` recording rule** (group `target_liveness`) or query
`min by (job) (up)` to see, at a glance, whether any job's target is down -
*before* anyone builds an alert on the metrics it should be producing (ZAF-676).

## Recording rules (5-min + 1-h rollups)

A 400-day query over raw 30-s samples is slow. The rules in
`recording_rules.yml` precompute the rates/quantiles the dashboards use so a
year-scale query runs over a handful of precomputed series:

- **`target_liveness`** - `job:up:min` = `min by (job) (up)`, one series per
  scrape job, so a dead target is visible before anyone alerts on it (ZAF-676).
- **`http_rollup_5m` / `http_rollup_1h`** - request rate, 5xx error ratio, and
  duration p50/p90/p99 per `(service, env)`, plus per-endpoint p99.
- **`crawler_rollup_5m` / `crawler_rollup_1h`** - reputation (429 /
  `LOGIN_REQUIRED` / ban), reconnects, writer throughput/errors, drop-policy
  activations.
- **`redis_client_rollup_5m`** - `service_operation:redis_command_duration_seconds:p99_5m`,
  the Redis client's p99 per command (`operation`), from the `lo-cache`
  histogram (ZAF-1532). Read it against the 2 000 ms client timeout.

**Raw samples are untouched** - rollups are *additional* series, not a
downsample-and-delete. Retention (400 d) applies to raw and rollup alike. The
1-h group evaluates hourly (not every 30 s), which is what makes the long-window
series cheap.

## Alerting (Prometheus rules + Alertmanager)

`rules/alerting_rules.yml` arms the ZAF-595 §7 alarms (ZAF-687) plus the
WebSocket / chat / bot degradation alarms (ZAF-676). Prometheus
evaluates them and pushes firing alerts to **Alertmanager**
(`staging-alertmanager:9093`), which groups, deduplicates and routes them by a
**`severity`** label:

| `severity` | Meaning | Route |
|-----------|---------|-------|
| `page` | Reputation-fatal or data-losing - the crawler is banned / login-gated / blind / not writing. Wakes a human. | `pager` receiver, re-notify hourly |
| `ticket` | Degraded-but-working - coverage / latency / throttle pressure. Looked at next business hours. | `ticket` receiver, re-notify 4-hourly |

Every alert also carries a `component` label (`crawler` | `http` | `target` |
`websocket` | `chat` | `bot` | `redis`). A `page` inhibits the lower-severity `ticket` for
the same incident.

**Rule groups** (35 alerts):

- **`target_liveness_alerts`** - `up == 0` per job (API + crawler paged, other
  services ticket) and `ServiceCrashLooping` (`changes(process_start_time_seconds)`).
  A dead target is the most expensive silent failure (ZAF-676).
- **`crawler_reputation_alerts`** (PAGED) - `CrawlerLoginRequired`,
  `CrawlerBanEvents`, `CrawlerHelix429Sustained`, `CrawlerHelixAuthFailures`.
  These are the §7 first-class reputation alarms.
- **`crawler_connection_alerts`** - no IRC connection, joined-but-silent (a
  wedged read path), reconnect storm, JOIN-throttle saturation, drop-policy
  activation.
- **`crawler_pipeline_alerts`** - writer errors (paged), write-batch latency,
  writer backlog.
- **`crawler_coverage_alerts`** - discovery staleness (paged), discovery errors,
  empty roster.
- **`http_alerts`** - API 5xx error ratio (paged) + p99 latency, and a
  ticket-level 5xx alarm for the other services. Reuses the recording rules so
  the alert and the dashboard read the same precomputed series.
- **`websocket_leak_alerts`** (ZAF-676 §3) - `WsSessionLeakSuspected` (live
  sessions accumulate without draining - the ZAF-396 wedged-session leak),
  `WsIdleReapStorm` (idle-reaper force-closing wedged sessions), `WsBroadcastLagging`
  (slow-consumer backpressure). Uses the `ws_*` series from ZAF-680.
- **`chat_buffer_alerts`** (ZAF-676 §4) - `ChatBufferBacklog` (persist buffer not
  draining), `ChatFlushSlow` (p99 flush latency), `ChatMessagesDropped` (paged -
  `dead_letter` / `lost` = chat data loss). Uses `chat_buffer_depth` /
  `chat_flush_duration_seconds` / `chat_messages_dropped_total` from ZAF-680.
- **`bot_reconnect_alerts`** (ZAF-676 §5) - per-`platform` `BotReconnectLoop`
  (outer connect-loop flapping), `BotSyncStale` (up but no successful channel-sync),
  `BotSyncFailing` (consecutive sync errors). Uses `bot_reconnects_total{platform}`
  and the `bot_sync_*{platform}` gauges from ZAF-680.
- **`redis_alerts`** (ZAF-2190) - `RedisMemoryNearMaxmemory` (used memory above
  80 % of `maxmemory`), `RedisRejectingWrites` (paged - Redis answers writes with
  `OOM`), `RedisMaxmemoryUnset` (the running Redis lost its `--maxmemory` flag).
  Redis runs with `noeviction`; see [Data layer (staging)](./data-layer-staging.md).

Each of the three ZAF-676 groups and `redis_alerts` carries an explicit `runbook` annotation (what
the alert means + the first handgriff, ZAF-676 §7); the older groups fold the
first action into `description`.

**Tuned quiet-under-normal-load** (the ZAF-635 go-live entry criterion): the
reputation counters sit at 0 when healthy, so a *sustained non-zero rate* (never
a single sample) is the signal, and `for:` windows outlast normal transients.

### What is needed before delivery is real

The metric surface these rules reference is now on `next`: ZAF-674 landed
`lo-metrics` + the `crawler_*` / `http_*` rework (the IRC `NOTICE` classifier
that increments `crawler_login_required_total` / `crawler_ban_events_total`), and
ZAF-680 added the `ws_*` / `chat_*` / `bot_*` domain series the ZAF-676 groups
alert on. So the alerts have a real signal once the services deploy to staging.

Two steps remain, both gated on the **staging-deploy** boundary (host access +
DevOps-Leader go/no-go - the ZAF-675 deploy gate):

1. **Deploy the stack + instrumented services to staging.** The rules go live
   when Prometheus scrapes services built from a `next` that includes ZAF-674 /
   ZAF-680.
2. **Provision the delivery secret (ZAF-676 §6).** The `pager` / `ticket`
   receivers read their webhook URL from a **file** (`url_file`), not an env var
   (Alertmanager does not expand env vars) and not a literal (no secret in git).
   Drop `pager_webhook_url` / `ticket_webhook_url` into
   `alertmanager/secrets/` on the host from the board-gated secret path, then
   `POST /-/reload` - a low-threshold Slack/Discord/Mattermost webhook is enough
   for staging. See `alertmanager/secrets/README.md`. Until the files exist the
   config still loads and alerts are visible in the UI (`127.0.0.1:9093`); they
   simply are not delivered off-box.

### Deliberately NOT alarmed yet (no emitting metric)

An alert on a series nothing emits is a permanently-silent lie, so these are
tracked here instead of armed:

- **Kafka consumer-lag** - the crawl-job / result bus is **in-memory single-node**
  today (`apps/crawler-twitch/src/bus.rs`); the Kafka/RabbitMQ impls are gated
  (ZAF-655 / ZAF-392). No consumer group, no lag series. Add the lag alarm when
  the Kafka bus lands.
- **Opt-out enforcer errors** (`crawler_optout_refresh_errors_total` /
  `_erasure_errors_total`) - the enforcer and those metrics are not on `next`
  yet (ZAF-635 / ZAF-686). Add the alarm in the PR that emits the counters.
- **Write-amplification ratio** (`rows_upserted` vs `rows_skipped_noop`) -
  `crawler_rows_skipped_noop_total` is registered at 0; its increment site ships
  with the writer's `DO UPDATE … WHERE` no-op guard, which is not wired yet.
  Until then write health is covered by `CrawlerWriterErrors` +
  `CrawlerWriteLatencyHigh`.

## Dashboards

Provisioned into the **Lumio** folder in Grafana:

- **Lumio - API** - request rate, error ratio, latency p50/p90/p99, per-endpoint
  p99, process memory/CPU, scrape-target health.
- **Lumio - Crawler reputation & pipeline** - 429/LOGIN_REQUIRED/ban rates,
  reconnects, roster size, discovery freshness, writer throughput/latency,
  pipeline backlog + drop policy.
- **Lumio - Realtime (WS / Chat / Bots)** - WS active sessions, chat buffer
  lag, bot reconnects. These panels expect series named `ws_active_sessions`,
  `chat_buffer_pending`, `chat_flush_lag_seconds`, and `bot_reconnects_total`
  (label `platform`) from ZAF-674; they show no data until each service emits
  them.

## Runbook

Both UIs bind to `127.0.0.1` only - reach them over an SSH tunnel; never expose
them publicly (metric names + route lists are recon material).

### Deploy

```bash
cd dev-stack/staging
cp .env.observability.example .env.observability   # set a real GF_SECURITY_ADMIN_PASSWORD

# The lumio-staging network is created by the infra stack:
docker compose -f infra.docker-compose.yml up -d   # if not already running

docker compose -f observability.docker-compose.yml up -d
```

Verify:

```bash
curl -s http://127.0.0.1:9090/-/healthy                 # Prometheus
curl -s http://127.0.0.1:9090/api/v1/rules | jq '.data.groups[].name'
curl -s http://127.0.0.1:9090/api/v1/alerts | jq '.data.alerts[] | {alertname:.labels.alertname, state}'
curl -s http://127.0.0.1:9090/api/v1/alertmanagers | jq '.data.activeAlertmanagers'
curl -s http://127.0.0.1:9090/api/v1/targets | jq '.data.activeTargets[] | {job:.labels.job, health}'
curl -s http://127.0.0.1:9093/-/healthy                 # Alertmanager
curl -s http://127.0.0.1:3009/api/health                # Grafana
```

Grafana UI: `http://127.0.0.1:3009` (via tunnel), login with the admin
credentials from `.env.observability`.

### Reload config / rules (no restart)

Prometheus runs with `--web.enable-lifecycle`:

```bash
docker compose -f observability.docker-compose.yml restart prometheus   # simplest
# or hot-reload:
curl -s -X POST http://127.0.0.1:9090/-/reload
```

Grafana re-reads provisioned datasources/dashboards on restart (dashboards also
poll every 30 s).

### Rollback

Config is versioned, so rollback is a `git revert` of the config change plus a
recreate:

```bash
git revert <commit>            # or check out the previous config
docker compose -f observability.docker-compose.yml up -d --force-recreate
```

The TSDB and Grafana state persist in named volumes, so a config rollback does
**not** lose collected metrics. To wipe everything (destructive - loses history):

```bash
docker compose -f observability.docker-compose.yml down -v
```

### Validate config before deploy

```bash
# Prometheus config + recording + alerting rules:
docker run --rm --entrypoint promtool \
  -v "$PWD/observability/prometheus:/etc/prometheus:ro" \
  prom/prometheus:v3.1.0 check config /etc/prometheus/prometheus.yml

# Alertmanager routing config:
docker run --rm --entrypoint amtool \
  -v "$PWD/observability/alertmanager:/etc/alertmanager:ro" \
  prom/alertmanager:v0.28.0 check-config /etc/alertmanager/alertmanager.yml
```

## Related: ingest diagnostics file

Prometheus holds metrics only; there is no log aggregation (no Loki). For ingest errors, `api`, `twitch-bot`, `kick-bot` and `youtube-bot` write every warning and error plus the ingest capture lines to `/app/data/diagnostics/<service>.<date>.jsonl` (ZAF-1720). Every staging compose file bind-mounts `${DIAGNOSTICS_DIR:-./data/diagnostics}` there.

The host directory must exist and be owned by uid 1001 before the first start:

```bash
sudo install -d -o 1001 -g 1001 data/diagnostics
```

If it is missing or not writable, the service logs one warning and runs on stdout only. Keys, selection and read-back: [Logging → Rust services: diagnostics file](logging.md#rust-services-diagnostics-file).

## Explicitly out of scope

- No InfluxDB / second time-series store. If series counts later explode, the
  path is a `remote_write` block to VictoriaMetrics - no code, no metric rename.
- No OpenTelemetry / tracing collector.
- No product/customer data in Prometheus (per-channel cardinality is forbidden).
- No delivery secret in the repo - the Alertmanager receivers reference a
  webhook URL by **file** (`url_file`); the actual Slack/Discord/PagerDuty URL is
  provisioned on the host via the board-gated secret path, never committed (see
  [Alerting → What is needed before delivery is real](#what-is-needed-before-delivery-is-real)).
- No production pager (persistent volume, on-call rotation, PagerDuty/Opsgenie) - that is stage 3, gated on ZAF-61 / k3s.

---

## Developer Guide / Access log for protected customer data

Source: https://docs.lumio.vision/developer-guide/protected-data-access-log

# Access log for protected customer data

Shopify order events carry protected customer data: the buyer label in
`raw.customer_display` (see [Shopify connection](../features/shopify.md)). The
data lives in the TimescaleDB table `platform_event_logs`, and on its way there
briefly in Redis (pub/sub and the dead-letter list). The main PostgreSQL holds the
order ids of Shopify customer data requests and redactions
(`shopify_compliance_requests.order_ids`), next to the personal data of Lumio's
own users. The extensions PostgreSQL holds the data extensions write. The [audit log](./audit-events.md)
records changes made through the app. It does not record a person who reads the
data directly on the host. This page describes the log that does, how long it is
kept and how it is reviewed. It covers Shopify's Level 2 requirement "keep an
access log to protected customer data".

The setup files are in `dev-stack/staging/access-log/`. The host runs its own
copies of the compose files (see [Data layer](./data-layer-staging.md)), so every
step below runs on each host that holds the data. Today that is staging. The
production databases do not exist yet; they get the same setup when they are
built, before the Shopify app goes live.

## What is logged

| Source | What it records | Where | Kept |
|--------|-----------------|-------|------|
| pgaudit on TimescaleDB | Every statement of every session except the app's (reads, writes, DDL, role changes), with role, source and client name | `/var/log/lumio-tsdb/postgresql-YYYY-MM-DD.log` in the container, `TSDB_LOG_DIR` on the host | 365 days |
| Statement log on the main and extensions PostgreSQL | The text of every statement of every session except the apps', with role, database, source and client name | `/var/log/lumio-pg/postgresql-YYYY-MM-DD.log` in each container, `PG_LOG_DIR` / `EXT_PG_LOG_DIR` on the host | 365 days |
| PostgreSQL connection log | Every login to all three databases, the apps' included: role, database, source address, client name | the same files | 365 days |
| systemd journal | SSH logins (accepted and failed), `sudo` and `su` | journald, persistent | 1 year |
| auditd | Every run of the docker CLI (`docker exec`, `docker cp`, `docker compose exec`) with the login user behind `sudo` and the full command line | `/var/log/audit/audit.log*` | 365 days |
| Review record | Who reviewed which month, when, the counts and the finding | `/var/log/lumio-access-review.log` | never deleted |

### Which database sessions are audited

A login trigger (`ops_audit_login`, from `tsdb-access-audit.sql`) switches on
`pgaudit.log = 'read, write, ddl, role'` for every session **except** the app
login (`TSDB_USER`, default `lumio`) over TCP. The app connects over TCP from its
containers, and its pooled sessions would make the log too large to review. Every
other way in is audited:

- `docker exec staging-tsdb psql …` uses the Unix socket, so it is audited with
  any role, the app role included.
- A personal role over an SSH tunnel is audited, because it is not the app login.
- The nightly backup (`docker exec … pg_dump`) is audited. Its reads show up as
  `tsdb_backup_reads` in the review.

The trigger compares the role baked into its function body, not a setting a
session could override at login. A non-superuser cannot switch the audit off: `SET
pgaudit.log` needs superuser rights. The trigger exists only in the `lumio_tsdb`
database, which is the only database that holds `platform_event_logs`.

`pgaudit.log_relation = on` logs each table a statement touches, so a read of a
single hypertable chunk (`_timescaledb_internal._hyper_…`) is logged under that
chunk's name. `pgaudit.log_parameter = off` and `pgaudit.log_catalog = off` keep
bind values and psql's catalog lookups out of the log. Statements typed by hand
are logged as written, so a value in a `WHERE` clause ends up in the log. That
is why the log files are mode `0640` and owned by the database user.

### Main and extensions PostgreSQL

Both run on `postgres:18-alpine`, which ships no pgaudit. Moving them to an image
with pgaudit would change the C library (musl to glibc) under an existing
`en_US.utf8` database, which changes text sort order and needs every text index
rebuilt. So the same kind of login trigger (`pg-access-audit.sql`) sets
`log_statement = 'all'` instead, for every session except the app logins over TCP:

| Database | App logins over TCP (not logged) | Trigger created by |
|----------|----------------------------------|--------------------|
| main (`lumio`) | `lumio` | `lumio` (bootstrap superuser) |
| extensions (`lumio_extensions`) | `lumio_ext`, `lumio_ext_api`, `lumio_ext_worker` | `postgres` (bootstrap superuser) |

The log holds the statement text as typed, not the tables a statement resolves
to. That is enough for the review: every direct access to
`shopify_compliance_requests` names the table. A non-superuser cannot switch it
off (`SET log_statement` needs superuser rights), and `postgres` on the
extensions database is logged even over TCP, because no app uses it. Slow app
queries keep appearing as `duration: … statement:` lines; the review counts only
`statement:` lines.

### What is not logged, and the limits

- **Redis contents.** Redis has no read log. Reaching it needs a shell on the
  host and `docker exec staging-redis redis-cli`, so the SSH log and the auditd
  docker record show who did it and when, with the full command line.
- **A superuser who switches the log off.** A superuser can connect with
  `options='-c event_triggers=off'` or change the server configuration. The
  connection itself is still logged (`connection authorized` with source and
  client), and a changed configuration file shows up in auditd. The log is
  tamper-evident, not tamper-proof. Database superuser access is limited to the
  founder.
- **`docker logs`** of the three databases shows only the start-up lines. Every
  later server log line, slow queries included, goes to the log files.

## Setting it up on a host

Run this on the host as root, once per host. The commands use the container
names of the reference compose file (`staging-tsdb`, `staging-postgres`,
`staging-extensions-postgres`); the staging host's own copy names them `tsdb`,
`postgres` and `extensions-postgres`, so replace the names there. Step 3 restarts
each database for a few seconds, so pick a quiet time. Chat messages wait in the Redis chat buffer
meanwhile (see [Data layer](./data-layer-staging.md)); back up first, as for any
TimescaleDB change.

1. **Check the image and the paths.** Each command prints a number or a path:

   ```bash
   docker exec staging-tsdb sh -c 'ls /usr/lib/postgresql/*/lib/pgaudit.so | wc -l'   # 1
   command -v docker                                                                  # /usr/bin/docker
   docker exec staging-tsdb psql -U lumio -d lumio_tsdb -Atc 'SHOW data_directory'
   cat /etc/os-release | grep -c -E 'ID=(debian|ubuntu)'                              # 1
   ```

2. **Create the log directories** next to the data directories and set them in
   the project `.env`. TimescaleDB runs as uid 1000, the alpine images as uid 70.
   On staging the data lives under `/root/data`:

   ```bash
   install -d -o 1000 -g 1000 -m 750 /root/data/tsdb-log
   install -d -o 70 -g 70 -m 750 /root/data/postgres-log /root/data/extensions-postgres-log
   printf '%s\n' TSDB_LOG_DIR=/root/data/tsdb-log PG_LOG_DIR=/root/data/postgres-log \
     EXT_PG_LOG_DIR=/root/data/extensions-postgres-log >> .env
   ```

3. **Update the host copy of `infra.docker-compose.yml`** with the three database
   services of the repo file: on `timescaledb` `pgaudit` in
   `shared_preload_libraries` and the `pgaudit.*` flags; on all three the
   `logging_collector` and `log_*` flags and the log mount. Then recreate the
   containers:

   ```bash
   docker compose -f infra.docker-compose.yml up -d timescaledb postgres extensions-postgres
   docker exec staging-tsdb psql -U lumio -d lumio_tsdb -Atc 'SHOW shared_preload_libraries'
   # timescaledb,pg_textsearch,pg_stat_statements,pgaudit
   docker exec staging-postgres psql -U lumio -d lumio -Atc 'SHOW logging_collector'                       # on
   docker exec staging-extensions-postgres psql -U postgres -d lumio_extensions -Atc 'SHOW logging_collector'  # on
   ```

4. **Install the login triggers.** The scripts are idempotent and print the
   trigger with `evtenabled = A`:

   ```bash
   docker exec -i staging-tsdb psql -v ON_ERROR_STOP=1 -v app_role=lumio \
     -U lumio -d lumio_tsdb < dev-stack/staging/access-log/tsdb-access-audit.sql
   docker exec -i staging-postgres psql -v ON_ERROR_STOP=1 -v app_roles=lumio \
     -U lumio -d lumio < dev-stack/staging/access-log/pg-access-audit.sql
   docker exec -i staging-extensions-postgres psql -v ON_ERROR_STOP=1 \
     -v app_roles=lumio_ext,lumio_ext_api,lumio_ext_worker \
     -U postgres -d lumio_extensions < dev-stack/staging/access-log/pg-access-audit.sql
   ```

5. **Keep the journal for a year** and install auditd with the docker rules:

   ```bash
   install -D -m 644 dev-stack/staging/access-log/journald-retention.conf \
     /etc/systemd/journald.conf.d/lumio-access-log.conf
   systemctl restart systemd-journald
   apt-get install -y auditd
   install -m 640 dev-stack/staging/access-log/lumio-access.rules /etc/audit/rules.d/
   sed -i 's/^max_log_file_action.*/max_log_file_action = keep_logs/' /etc/audit/auditd.conf
   augenrules --load
   auditctl -l | grep -c lumio-docker                                                 # 1
   ```

   `keep_logs` rotates `audit.log` without deleting old files; the prune timer
   deletes them after `RETENTION_DAYS`.

6. **Install the review script and the daily prune timer:**

   ```bash
   install -D -m 755 dev-stack/staging/access-log/access-log-review.sh /opt/lumio-access-log/access-log-review.sh
   install -m 600 dev-stack/staging/access-log/lumio-access-log.env.example /etc/default/lumio-access-log
   # edit the *_LOG_DIR paths and the app roles
   install -m 644 dev-stack/staging/access-log/lumio-access-log-prune.{service,timer} /etc/systemd/system/
   systemctl daemon-reload && systemctl enable --now lumio-access-log-prune.timer
   ```

7. **Check that it works.** Read one row as a person, then look at the report:

   ```bash
   docker exec staging-tsdb psql -U lumio -d lumio_tsdb -Atc 'SELECT count(*) FROM platform_event_logs'
   docker exec staging-postgres psql -U lumio -d lumio -Atc "SELECT to_regclass('public.shopify_compliance_requests')"
   docker exec staging-extensions-postgres psql -U postgres -d lumio_extensions -Atc 'SELECT 1'
   /opt/lumio-access-log/access-log-review.sh report "$(date +%Y-%m)" \
     | grep -E 'tsdb_protected_reads|pg_protected_statements|ext_person_statements|docker_exec_cp'
   ```

   All four are at least `1`. The main-database check uses `to_regclass`, so it
   also works before the Shopify migration has run; the statement names the
   table either way. Post the date and these numbers on the setup ticket.

## Monthly review

On the first working day of each month, the reviewer runs the report for the
previous month and records it:

```bash
/opt/lumio-access-log/access-log-review.sh record 2026-10 "Raphael" "none"
```

The report prints the counts (person sessions, protected reads, backup reads,
SSH logins and failures, `sudo`/`su`, docker runs) and lists every person's
protected read and every person's database session. For each line the reviewer
answers one question: was this access needed for a known task (an incident, a
support case, a data request)? An access without a reason is a finding. The
third argument records it (`"none"` when there is none), and a finding is
handled under the incident response policy.

`tsdb_backup_reads`, `pg_backup_statements` and `ext_backup_statements` are
expected: about one block per night from the backup job. A month with none means
the backup did not run.

`record` appends one line per review to `REVIEW_LOG`. That line is the record of
who reviewed which month and when.

## Rollback

```bash
docker exec staging-tsdb psql -U lumio -d lumio_tsdb \
  -c 'DROP EVENT TRIGGER IF EXISTS ops_audit_login' -c 'DROP SCHEMA IF EXISTS ops_audit CASCADE'
docker exec staging-postgres psql -U lumio -d lumio \
  -c 'DROP EVENT TRIGGER IF EXISTS ops_audit_login' -c 'DROP SCHEMA IF EXISTS ops_audit CASCADE'
docker exec staging-extensions-postgres psql -U postgres -d lumio_extensions \
  -c 'DROP EVENT TRIGGER IF EXISTS ops_audit_login' -c 'DROP SCHEMA IF EXISTS ops_audit CASCADE'
```

Then restore the previous host copy of `infra.docker-compose.yml` and run
`docker compose -f infra.docker-compose.yml up -d timescaledb postgres extensions-postgres`. The log files stay
on the host until the retention deletes them.

If a broken login trigger blocks every login, a superuser still gets in with the
trigger switched off for that one session (same for the other two databases):

```bash
docker exec -it staging-tsdb psql "dbname=lumio_tsdb user=lumio options='-c event_triggers=off'" \
  -c 'DROP EVENT TRIGGER ops_audit_login'
```

### TimescaleDB extension updates

`ALTER EXTENSION timescaledb UPDATE` must be the first statement of its session.
The login trigger runs before it and loads the old extension version, so the
update fails with `cannot be updated after the old version has already been
loaded`, even with `psql -X`. Run it with the trigger switched off for that one
session, in every database that has the extension:

```bash
docker exec -e PGOPTIONS='-c event_triggers=off' staging-tsdb \
  psql -X -U lumio -d lumio_tsdb -c 'ALTER EXTENSION timescaledb UPDATE'
```

pgaudit does not log that session. Its connection is still in the connection log
(see [What is not logged, and the limits](#what-is-not-logged-and-the-limits)).
The trigger stays enabled for every other session.

## Log volume

The audited sessions are rare, so the volume comes from the connection log. The
compose healthcheck (`pg_isready` every 10 s) logs two lines per check: about 3 MB
a day per database, or about 3.3 GB a year for the three databases on one host.
The nightly `pg_dump` adds one line per table and chunk on TimescaleDB and one
per statement on the other two.

---

## Developer Guide / Data layer - PostgreSQL, TimescaleDB, extensions PostgreSQL, Redis (Staging)

Source: https://docs.lumio.vision/developer-guide/data-layer-staging

# Data layer - PostgreSQL, TimescaleDB, extensions PostgreSQL, Redis (Staging)

The staging data layer is defined in `dev-stack/staging/infra.docker-compose.yml`.
That file is a **reference**: the staging host runs its own copy of it, so a
change here reaches staging only when the host copy is updated (see
[Applying a change on the staging host](#applying-a-change-on-the-staging-host)).
The local `dev-stack/db.docker-compose.yml` uses the same flags, with default
memory sizes and without the access log (local data is not
protected customer data).

## Memory sizing

PostgreSQL and TimescaleDB use about 25 % of the RAM they may use for
`shared_buffers` and about 70 % for `effective_cache_size`. Redis gets a container
limit and a `maxmemory` of about 70 % of that limit. The remaining 30 % covers the
fork for an AOF rewrite and allocator overhead.

The sizes are compose variables with defaults. Compose reads them from the shell
or the project `.env` file, not from `env_file: .env.infra`:

| Variable | Default | Setting |
|----------|---------|---------|
| `PG_SHARED_BUFFERS` | `1GB` | PostgreSQL `shared_buffers` |
| `PG_EFFECTIVE_CACHE_SIZE` | `3GB` | PostgreSQL `effective_cache_size` |
| `TSDB_SHARED_BUFFERS` | `1GB` | TimescaleDB `shared_buffers` |
| `TSDB_EFFECTIVE_CACHE_SIZE` | `3GB` | TimescaleDB `effective_cache_size` |
| `REDIS_MEM_LIMIT` | `2g` | Redis container `mem_limit` |
| `REDIS_MAXMEMORY` | `1400mb` | Redis `--maxmemory` |

The defaults assume each database may use about 4 GB of the host. On a larger
host, raise the values for both databases. Keep the ratios when you do.

### Redis `maxmemory`: one TimescaleDB outage hour

While TimescaleDB is down, the chat flush cannot drain the buffer, so every chat
message stays in Redis. Once Redis is full, the direct-insert fallback fails as
well, because it writes to the same TimescaleDB, and messages are lost. Size
`REDIS_MAXMEMORY` so that it holds the steady state **plus at least one outage
hour** of chat-buffer growth. Then set `REDIS_MEM_LIMIT` to about
`REDIS_MAXMEMORY / 0.7`.

The capacity model (ZAF-2180 §3.5) gives these values:

| Active channels | Steady state | Buffer growth per outage hour | Minimum `maxmemory` | `REDIS_MAXMEMORY` / `REDIS_MEM_LIMIT` |
|-----------------|--------------|-------------------------------|---------------------|---------------------------------------|
| 500 | ~0.15 GB (scaled linearly) | ~0.36 GB | ~0.5 GB | `1400mb` / `2g` (the defaults) |
| 5 000 | ~1.5 GB (profiles ~1.1 GB, chatter hashes ~0.3 GB) | ~3.6 GB | ~5.1 GB | `5600mb` / `8g` |

Dead letters stay for 72 h, so add their current size from `redis-cli --bigkeys`
on top. With these sizes, `RedisMemoryNearMaxmemory` (80 %) fires well before
Redis starts rejecting writes. At 5 000 channels it fires about 50 minutes into
an outage.

## Redis: `noeviction`

Redis runs with `--maxmemory-policy noeviction`. Some Redis data is durable and
has no other copy until it is flushed or expires:

- the chat buffer `lumio:chat:buffer:*` (messages waiting for the batch insert
  into TimescaleDB) and its dead letters (72 h),
- parked platform events `lumio:events:deadletter:*` (inserts that failed
  while TimescaleDB was unavailable, 72 h; see
  [Chat and event durability](./ingest-durability.md)),
- extension storage (some keys have no TTL),
- automation variables (30 days).

An `allkeys-*` policy would drop these keys without an error. With `noeviction`,
Redis answers every write with `OOM command not allowed when used memory >
'maxmemory'` when it is full. Reads and deletes still work, so the chat flush
(`LRANGE` + `DEL`) can still drain the buffer. What a full Redis does to each writer:

- **Chat ingest** - the buffer push fails and the message goes into TimescaleDB
  with a direct insert (`buffer_or_persist` in `crates/lo-chat/src/buffer.rs`).
  It is counted in `chat_buffer_push_failures_total{outcome="direct_insert"}`.
- **Platform events** - unaffected while TimescaleDB is healthy (Redis is only
  written when an insert fails). If both fail, the event is lost and counted in
  `events_persist_failures_total{outcome="lost"}`.
- **Extension storage, automation variables, caches** - the write fails, and the
  caller gets the error.

Do not switch to `volatile-lru` until the extension-storage keys without a TTL
are stored in PostgreSQL. With `volatile-lru`, Redis evicts only keys that have
a TTL. That still includes the chat and platform-event dead-letter lists.

### Alarms

`oliver006/redis_exporter` (container `staging-redis-exporter`) exports Redis
`INFO` to Prometheus as job `redis`. The `redis_alerts` group in
`observability/prometheus/rules/alerting_rules.yml` uses it:

| Alert | Fires when | Severity |
|-------|-----------|----------|
| `RedisMemoryNearMaxmemory` | `redis_memory_used_bytes / redis_memory_max_bytes > 0.8` for 10 min | `ticket` |
| `RedisRejectingWrites` | `rate(redis_errors_total{err="OOM"}[5m]) > 0` for 5 min | `page` |
| `RedisMaxmemoryUnset` | `redis_memory_max_bytes == 0` for 15 min (the running Redis has no `--maxmemory`) | `ticket` |

If the exporter is down, `ServiceTargetDown` fires for job `redis`.

To give Redis more memory, raise `REDIS_MEM_LIMIT` and `REDIS_MAXMEMORY` together
and recreate the container. Before that, run `redis-cli --bigkeys` to find what
grew. A stuck chat flush also shows up as `ChatBufferBacklog`.

### Command latency

The `lo-cache` client records `redis_command_duration_seconds{operation}`
(ZAF-1532) on the API's `/metrics`. The recording rule
`service_operation:redis_command_duration_seconds:p99_5m` holds the p99 per
command. The weekly read is the highest p99 per command over 7 days:

```promql
max_over_time(service_operation:redis_command_duration_seconds:p99_5m[7d])
```

The client times out after 2 000 ms (`command_timeout_ms` in
`crates/lo-config/src/common.rs`). Likely slow commands are `HGETALL` on chatter
hashes (up to 5 000 fields, about 1 MB), the chat flush worker's one
full-keyspace `SCAN` at startup, and any new unbounded `LRANGE 0 -1`. A p99 that stays near 2 s is an
infrastructure problem, not a timeout that is too tight.

## PostgreSQL and TimescaleDB settings

Both databases start with these `-c` flags:

| Setting | Value | Why |
|---------|-------|-----|
| `shared_buffers` | 25 % of the database's RAM | The 128 MB default is too small for the working set |
| `effective_cache_size` | 70 % of the database's RAM | Lets the planner choose index scans |
| `log_min_duration_statement` | `1000` | Logs every statement that takes 1 s or longer |
| `shared_preload_libraries` | `pg_stat_statements` (PostgreSQL); `timescaledb,pg_textsearch,pg_stat_statements,pgaudit` (TimescaleDB) | Needed for `pg_stat_statements`, and on TimescaleDB for the access log |

On TimescaleDB, `shared_preload_libraries` replaces the image's own list
(`timescaledb,pg_textsearch`). Both entries must stay in it.

All three databases also write their server log to daily files
(`logging_collector` and the connection log; on TimescaleDB also the `pgaudit.*`
flags) under `TSDB_LOG_DIR`, `PG_LOG_DIR` and `EXT_PG_LOG_DIR`, so `docker logs`
shows only the start-up lines. That log is the access log for protected customer
data: see
[Access log for protected customer data](./protected-data-access-log.md).

### TimescaleDB job workers

TimescaleDB also gets these flags:

| Setting | Value |
|---------|-------|
| `timescaledb.max_background_workers` | `16` |
| `max_parallel_workers` | `4` |
| `max_worker_processes` | `24` |

`tsdb_migrations` create 20 background jobs. TimescaleDB adds its own
housekeeping jobs.

| Kind | Count | Tables |
|------|-------|--------|
| Compression policy | 9 | `platform_event_logs`, `platform_chat_messages`, `audit_events`, `channel_history_stats`, `channel_history_stats_5m`, `channel_history_stats_1h`, `extension_errors`, `extension_install_logs`, `extension_events` |
| Retention policy | 5 | `extension_errors`, `extension_install_logs`, `extension_events`, `channel_history_stats`, `channel_history_stats_5m` |
| Continuous-aggregate refresh | 2 | `channel_history_stats_5m`, `channel_history_stats_1h` |
| Custom job (`add_job`) | 4 | `anonymise_old_audit_events`, `purge_old_audit_events`, `prune_old_csp_reports`, `recompress_stale_orderby_chunks` (deschedules itself once no chunk with an old compression order is left) |

Each running job takes one background worker, and each database with the
extension adds one scheduler. The default of 16 background workers is enough.
Background workers are taken from `max_worker_processes`. Parallel queries and
the launcher take from it too, and its default is 8. So the jobs had less than
8 slots, shared with parallel queries. 24 = 16 background workers + 4 parallel
workers + the launcher + headroom.

### `pg_stat_statements`

The library is preloaded, but the view exists only after you create the
extension. Run this once in each database as the database owner:

```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

Run it in `lumio` (PostgreSQL) and `lumio_tsdb` (TimescaleDB). The slowest
statements by total time:

```sql
SELECT calls, round(total_exec_time) AS total_ms, round(mean_exec_time, 1) AS mean_ms, query
FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 20;
```

Read-only access for anyone else (for example a `pg_read_all_stats` role) is a
separate decision. Enabling the extension does not grant it.

## Extensions PostgreSQL: connection budget

Extension data (`ext_{extension_id}` schemas) lives in a separate PostgreSQL,
`extensions-postgres` (`lumio_extensions`, host port `5434`). It runs
`postgres:18-alpine` with `max_connections` set explicitly to `100`
(`EXT_PG_MAX_CONNECTIONS`). PostgreSQL keeps 3 of them for superusers, so
clients can open 97.

Every client keeps its own pool:

| Client | Pool setting | Per replica |
|--------|--------------|-------------|
| API | `[extensions.database] max_connections` (`LUMIO__EXTENSIONS__DATABASE__MAX_CONNECTIONS`) | `10` on staging (`staging.toml`), `20` in production (`production.toml`) |
| bot-module-worker | its extensions-database pool (ZAF-2409) | `5` |
| API DDL pool (`lumio_ext`, ZAF-2513) | - | `2` |
| Headroom (`psql`, backups, migrations) | - | `5` |

All pools at their maximum must fit:

```text
P_api · N_api + 5 · M_worker + 2 + 5 ≤ 97
```

`N_api` and `M_worker` are the replica counts, `P_api` the API pool size.

- **Staging** with one API and one bot-module-worker replica:
  `10 + 5 + 2 + 5 = 22`.
- **Production** at `P_api = 20` fits at most 3 API replicas
  (`3 · 20 + 5 · 6 + 7 = 97` with up to 6 workers). With more than 3 API
  replicas, set `LUMIO__EXTENSIONS__DATABASE__MAX_CONNECTIONS=10`
  before you scale up.

When you add a replica or raise a pool, recompute the sum first. If the sum
exceeds 97, new connections fail with `too many clients already` and the
affected requests and handlers fail. Raise `max_connections` only together with
the memory each connection needs.

Current usage per client:

```bash
docker exec staging-extensions-postgres psql -U lumio_ext -d lumio_extensions -Atc \
  "SELECT application_name, client_addr, count(*) FROM pg_stat_activity GROUP BY 1, 2 ORDER BY 3 DESC"
```

## Extensions PostgreSQL: roles

Superusers and roles with `BYPASSRLS` ignore row-level security, `FORCE` included.
So no app connects to the extensions PostgreSQL as a superuser (ZAF-2509).

| Role | Attributes | Used by |
|------|------------|---------|
| `postgres` | bootstrap superuser (the image's `POSTGRES_USER`) | operators only, never in an app URL |
| `lumio_ext` | `LOGIN`, owner of `lumio_extensions` | the API's DDL pool (`LUMIO__EXTENSIONS__DATABASE__DDL_URL`): migrations, schema provisioning, purge paths |
| `lumio_ext_dml` | `NOLOGIN` group | target of every DML grant; the extensions migration fails if it is missing |
| `lumio_ext_api` | `LOGIN`, member of `lumio_ext_dml` | the API's server-function pool (`LUMIO__EXTENSIONS__DATABASE__URL`) |
| `lumio_ext_worker` | `LOGIN`, member of `lumio_ext_dml` | the bot-module-worker's extensions pool |

- None of them except `postgres` is `SUPERUSER`, `BYPASSRLS`, `CREATEROLE`,
  `CREATEDB` or `REPLICATION`, none is a member of another role that has one
  of these attributes, and none is a member of
  `pg_execute_server_program`, `pg_read_server_files` or
  `pg_write_server_files`. A migration cannot create roles, so the roles come
  from `dev-stack/initdb/extensions/10-roles.sh`, not from a migration.
- No login has a `role` setting (`ALTER ROLE … SET role`), and no app URL
  carries `options=-c role=…`. The startup check reads the session role, and
  `RESET ROLE` would return to a login it never read, so a session role that
  differs from the login stops the service.
- The DML logins are also not members of `pg_read_all_data` or
  `pg_write_all_data`, and not of `lumio_ext` or any other owner of the
  database, `public.schema_registry` or an `ext_*` schema.
- The DML logins have no `CREATE` and no `TEMPORARY` on the database and no
  `CREATE` on `public`. Their membership is `WITH INHERIT TRUE, SET FALSE`, so
  they use the group's grants but cannot `SET ROLE` to it.
- Each DML login has `statement_timeout = '2s'`. It is set on the login user,
  because settings of a `NOLOGIN` group are not inherited.
- `CONNECTION LIMIT` per login follows the budget above: `lumio_ext_api` =
  API pool × API replicas, `lumio_ext_worker` = 5 × worker replicas,
  `lumio_ext` = 2 × API replicas + 2 for `migrate` and `psql`. On staging that
  is `10`, `5` and `4` (`EXT_PG_*_CONN_LIMIT`).
- The script also creates the `pg_freespacemap` extension in `lumio_extensions`
  and grants `pg_stat_scan_tables` to `lumio_ext` and `lumio_ext_api`. The
  storage quota pass needs both to read the free space map. The extension is
  not trusted, so only a superuser can create it, and a migration cannot.
  `lumio_ext_worker` does not get the grant.

The script runs automatically on an empty data volume. It is idempotent: run it
again to change a password or a connection limit. It re-applies the attributes,
grants and settings each time:

```bash
docker exec -i -e EXT_DDL_PASSWORD -e EXT_API_PASSWORD -e EXT_WORKER_PASSWORD \
  -e EXT_DDL_CONN_LIMIT=4 -e EXT_API_CONN_LIMIT=10 -e EXT_WORKER_CONN_LIMIT=5 \
  staging-extensions-postgres bash -s < dev-stack/initdb/extensions/10-roles.sh
```

### Check the roles before a deploy

The API and the bot-module-worker check their roles at startup and refuse to
start when one breaks a rule above (ZAF-2509 A1). Memberships count even when
they are granted `WITH INHERIT FALSE, SET TRUE`, because `SET ROLE` restores
the rights. Run this check before you deploy a build with the check, and after
you change a role by hand:

```bash
docker exec staging-extensions-postgres psql -U postgres -d lumio_extensions -c "
SELECT r.rolname,
       r.rolsuper OR r.rolbypassrls OR r.rolcreaterole OR r.rolcreatedb
         OR r.rolreplication AS privileged_attribute,
       ARRAY(SELECT p.rolname FROM pg_roles p
             WHERE p.oid <> r.oid
               AND (p.rolsuper OR p.rolbypassrls OR p.rolcreaterole OR p.rolcreatedb
                    OR p.rolreplication)
               AND pg_has_role(r.oid, p.oid, 'MEMBER')) AS privileged_memberships,
       ARRAY(SELECT c FROM pg_db_role_setting s, unnest(s.setconfig) c
             WHERE s.setrole = r.oid
               AND s.setdatabase IN (0, (SELECT oid FROM pg_database
                                         WHERE datname = current_database()))
               AND c LIKE 'role=%') AS role_settings,
       ARRAY(SELECT s.rolname FROM pg_roles s
             WHERE s.rolname IN ('pg_execute_server_program', 'pg_read_server_files',
                                 'pg_write_server_files')
               AND pg_has_role(r.oid, s.oid, 'MEMBER')) AS server_roles,
       ARRAY(SELECT s.rolname FROM pg_roles s
             WHERE s.rolname IN ('pg_read_all_data', 'pg_write_all_data')
               AND pg_has_role(r.oid, s.oid, 'MEMBER')) AS all_data_roles,
       has_database_privilege(r.oid, current_database(), 'CREATE')
         OR has_database_privilege(r.oid, current_database(), 'TEMPORARY') AS db_create_temp,
       ARRAY(SELECT DISTINCT o::regrole::text FROM (
               SELECT datdba AS o FROM pg_database WHERE datname = current_database()
               UNION SELECT relowner FROM pg_class
                 WHERE oid = to_regclass('public.schema_registry')
               UNION SELECT nspowner FROM pg_namespace WHERE nspname LIKE 'ext\_%') x
             WHERE pg_has_role(r.oid, o, 'MEMBER')) AS owner_memberships
FROM pg_roles r
WHERE r.rolname IN ('lumio_ext', 'lumio_ext_api', 'lumio_ext_worker')
ORDER BY 1"
```

Expected:

| Role | `privileged_attribute` | `privileged_memberships` | `role_settings` | `server_roles` | `all_data_roles` | `db_create_temp` | `owner_memberships` |
|------|---|---|---|---|---|---|---|
| `lumio_ext` (DDL) | `f` | `{}` | `{}` | `{}` | not checked | not checked | not checked (it is the owner) |
| `lumio_ext_api`, `lumio_ext_worker` (DML) | `f` | `{}` | `{}` | `{}` | `{}` | `f` | `{}` |

Any other value stops that service at startup. The query cannot see an
`options=-c role=…` in an app URL: check `LUMIO__EXTENSIONS__DATABASE__URL`
and `LUMIO__EXTENSIONS__DATABASE__DDL_URL` for it by hand. A `t` in `privileged_attribute`
means the role could ignore row-level security or create roles and databases. A volume created before ZAF-2512 used `POSTGRES_USER=lumio_ext`, so
`lumio_ext` is its bootstrap superuser: switch it with one of the two paths
below.

### Switching an existing volume to the roles

Stop the API and the bot-module-worker first. A renamed role keeps its open
sessions, so the old superuser would stay connected until they restart.

Count what the volume holds:

```bash
docker exec staging-extensions-postgres psql -U lumio_ext -d lumio_extensions -Atc \
  "SELECT count(*) FROM pg_namespace WHERE nspname LIKE 'ext\_%'"
```

**A. The volume holds no `ext_*` schema: recreate it.** Back it up anyway
(see [Backups](#backups)). Stop the container, move its data directory aside,
set the `EXT_PG_*` passwords from `.env.infra.example` and run
`docker compose -f infra.docker-compose.yml up -d extensions-postgres`. The
script creates the roles on the empty volume.

**B. The volume holds data: switch in place.** The bootstrap superuser cannot
lose `SUPERUSER`, and `REASSIGN OWNED` refuses it. So it gets a new name, and a
new `lumio_ext` takes over its objects. Back up first.

```bash
# 1. A new bootstrap superuser, created by the old one.
docker exec staging-extensions-postgres psql -v ON_ERROR_STOP=1 -U lumio_ext -d postgres \
  -c "CREATE ROLE postgres SUPERUSER LOGIN PASSWORD '<EXT_PG_BOOTSTRAP_PASSWORD>'"
# 2. Rename the old bootstrap superuser and take its login away.
docker exec staging-extensions-postgres psql -v ON_ERROR_STOP=1 -U postgres -d postgres \
  -c "ALTER ROLE lumio_ext RENAME TO lumio_ext_legacy_bootstrap" \
  -c "ALTER ROLE lumio_ext_legacy_bootstrap NOLOGIN"
# 3. Create lumio_ext, the group and the DML logins, and hand every object in
#    lumio_extensions to lumio_ext.
docker exec -i -e POSTGRES_USER=postgres -e EXT_DDL_PASSWORD -e EXT_API_PASSWORD \
  -e EXT_WORKER_PASSWORD -e EXT_DDL_CONN_LIMIT=20 -e EXT_API_CONN_LIMIT=10 \
  -e EXT_WORKER_CONN_LIMIT=5 \
  staging-extensions-postgres bash -s < dev-stack/initdb/extensions/10-roles.sh
```

If `EXT_DDL_PASSWORD` is the password the API URL already carries, the API
starts again unchanged and now connects as the non-superuser owner. Until the
API's URL moves to `lumio_ext_api`, its whole pool connects as `lumio_ext`, so
`EXT_DDL_CONN_LIMIT` must be at least `LUMIO__EXTENSIONS__DATABASE__MAX_CONNECTIONS`
(`20` above). With the budget value `4`, the fifth pool connection fails with
`too many connections for role "lumio_ext"`. After the URL switch, lower it:
`ALTER ROLE lumio_ext CONNECTION LIMIT 4`, and keep the API pool at or below
`lumio_ext_api`'s limit. Then set
`POSTGRES_USER=postgres` and `POSTGRES_PASSWORD` in the host compose to match:
the image reads them only on an empty volume, but the healthcheck uses
`postgres`.

**Rollback for B:** as `postgres`, rename `lumio_ext` to
`lumio_ext_new`, rename `lumio_ext_legacy_bootstrap` back to `lumio_ext` and
give it `LOGIN` again. It still holds `SUPERUSER`, so it can still read every
object.

### Check the result

```bash
for u in lumio_ext_api lumio_ext_worker; do
  docker exec -e PGPASSWORD=<password of $u> staging-extensions-postgres \
    psql -h 127.0.0.1 -U "$u" -d lumio_extensions \
    -c "SELECT current_user, current_setting('statement_timeout')" \
    -c "CREATE SCHEMA ext_probe" -c "CREATE TEMP TABLE probe (x int)"
done
```

Expected per login: `2s`, then `permission denied for database
lumio_extensions` and `permission denied to create temporary tables`. Run the
role query from [Check the roles before a deploy](#check-the-roles-before-a-deploy):
`lumio_ext` must match the DDL row of its expected table.

### App URLs

The API needs both URLs, and they must differ (the API refuses to start
otherwise, ZAF-2513):

| Variable | Role |
|----------|------|
| `LUMIO__EXTENSIONS__DATABASE__URL` | `lumio_ext_api` |
| `LUMIO__EXTENSIONS__DATABASE__DDL_URL` | `lumio_ext` |
| bot-module-worker extensions URL (ZAF-2409) | `lumio_ext_worker` |

Point `LUMIO__EXTENSIONS__DATABASE__URL` at `lumio_ext_api` only with the API
release that reads `DDL_URL`. An older API provisions schemas through
`LUMIO__EXTENSIONS__DATABASE__URL`, which fails without `CREATE`. Until then it
stays on `lumio_ext`, which is no longer a superuser after the switch above.

## Extensions PostgreSQL: storage quota measurement

Every 15 minutes the API's data-deletion worker sizes each extension schema
for the 1 GiB storage quota. It writes the file size to
`schema_registry.size_bytes` and the space PostgreSQL can reuse to
`reclaimable_bytes`. Only `size_bytes - reclaimable_bytes` counts against the
quota. A blocked extension is unblocked once that drops to 90 % of the quota.

The reusable space comes from the free space map when the `pg_freespacemap`
extension is installed and the API's role may call `pg_freespace`. That reads
1 byte per table page. `pg_freespacemap` is not a trusted extension, so a
superuser creates it once. `10-roles.sh` (see the roles section above) does
this and grants `pg_stat_scan_tables` to `lumio_ext` and `lumio_ext_api`. By
hand, as the bootstrap superuser:

```bash
docker exec staging-extensions-postgres psql -U postgres -d lumio_extensions \
  -c "CREATE EXTENSION IF NOT EXISTS pg_freespacemap" \
  -c "GRANT pg_stat_scan_tables TO lumio_ext, lumio_ext_api"
```

The pass runs on the API's DDL pool (`LUMIO__EXTENSIONS__DATABASE__DDL_URL`,
role `lumio_ext`), which is why `lumio_ext` holds `pg_stat_scan_tables`.

Without the extension nothing counts as reusable and the file size alone
decides: deleted rows then unblock an extension only once the file shrinks.
`ext_*` tables force row-level security for their owner too, so no role can
scan every account's live rows as a fallback. A failed measurement also counts
nothing as reusable.

Check the state per extension:

```bash
docker exec staging-extensions-postgres psql -U lumio_ext -d lumio_extensions -Atc \
  "SELECT schema_name, size_bytes, reclaimable_bytes, writes_blocked, size_measured_at FROM schema_registry ORDER BY size_bytes DESC NULLS LAST LIMIT 20"
```

## Data directories

The two images keep their data in different places. A volume mounted at the
wrong path leaves the data in the container's writable layer. Docker then
deletes the data the next time it recreates the container, for example after
an image pull.

| Service | Image | `PGDATA` | Mount the volume at |
|---------|-------|----------|---------------------|
| PostgreSQL | `postgres:18-alpine` | `/var/lib/postgresql/18/docker` | `/var/lib/postgresql` |
| Extensions PostgreSQL | `postgres:18-alpine` | `/var/lib/postgresql/18/docker` | `/var/lib/postgresql` |
| TimescaleDB | `timescale/timescaledb-ha:pg18` | `/home/postgres/pgdata/data` | `/home/postgres/pgdata` |

- `postgres:18` does not start if a volume is mounted at
  `/var/lib/postgresql/data`. It reports that path as an "unused mount/volume".
- `timescaledb-ha` runs as uid 1000. A host directory mounted at
  `/home/postgres/pgdata` must be owned by `1000:1000`.

Check where a running database keeps its data:

```bash
docker exec staging-tsdb psql -U lumio -d lumio_tsdb -Atc 'SHOW data_directory'
docker inspect staging-tsdb --format '{{json .Mounts}}'
```

The `data_directory` must be inside one of the listed mounts.

## Backups

The daily encrypted off-host backup of all four stores, its retention, the
restore test and the restore log are described in [Backups](./backups.md). The
notes below explain what a TimescaleDB backup must contain and how a manual
restore works.

A TimescaleDB backup must contain the hypertable chunks (schema
`_timescaledb_internal`) and the continuous-aggregate materializations. Both are
ordinary tables in TimescaleDB's internal schemas, so `pg_dump` of the whole
database includes them. Never dump single hypertables.

`pg_dump` may warn about circular foreign keys in the TimescaleDB catalog. The
warning is expected. A restore needs the same TimescaleDB version as the dump,
and it must run between `timescaledb_pre_restore()` and
`timescaledb_post_restore()`:

```sql
CREATE DATABASE lumio_tsdb;
\c lumio_tsdb
CREATE EXTENSION IF NOT EXISTS timescaledb;
SELECT timescaledb_pre_restore();   -- stops the background jobs
-- shell: pg_restore -U lumio -d lumio_tsdb < lumio_tsdb.dump
SELECT timescaledb_post_restore();  -- starts them again
```

## Applying a change on the staging host

The host runs its own compose files, so these steps change staging.

1. **Find where the data is now.** Run the two commands under
   [Data directories](#data-directories). If `data_directory` is not inside a
   mount, the data exists only in the container. Back it up before anything
   else, because recreating the container deletes it.
2. **Check Redis memory.** Run
   `docker exec staging-redis redis-cli -a "$REDIS_PASSWORD" INFO memory`.
   `used_memory` must be well below the new `REDIS_MAXMEMORY`. Otherwise Redis
   rejects writes as soon as it starts.
3. **Back up** the data layer: `/opt/lumio-backup/lumio-backup.sh backup` (see
   [Backups](./backups.md)).
4. **Update the host copy** of `infra.docker-compose.yml` to match this file.
   Set the sizing variables in the project `.env`, and
   `chown -R 1000:1000` the TimescaleDB data directory.
5. **Recreate the containers:** `docker compose -f infra.docker-compose.yml up -d`.
6. **Check the result.** Run `SHOW shared_buffers;` and
   `SHOW shared_preload_libraries;` in both databases, and
   `redis-cli CONFIG GET maxmemory-policy` (expected: `noeviction`). Create
   `pg_stat_statements` in both databases. In Prometheus, `up{job="redis"}` must
   be `1`.

**Rollback:** restore the previous host copy of the compose file and run step 5
again. Moving the data directory cannot be undone by a rollback: do it only
after the backup in step 3 succeeded.

---

## Developer Guide / Backups (production and staging)

Source: https://docs.lumio.vision/developer-guide/backups

# Backups (production and staging)

Every Lumio host with customer data backs up its data layer once a day. The
backup is encrypted, stored off the host in the EU, and deleted after 14 days.
A backup counts only once a restore of it has been tested. The
[restore log](#restore-log) records each test with its date.

The scripts and systemd units are in `dev-stack/staging/backup/`. Like the
compose files next to them, they are **reference** files: the operator copies
them to the host (see [Setting up a host](#setting-up-a-host)). The folder's
`README.md` is the operator's quick reference on the host: commands for daily
operation, the configuration table and troubleshooting. Agents have no
access to the hosts. The operator applies every step and records the result.

## What is backed up

| Store | Content | Method |
|-------|---------|--------|
| PostgreSQL (`staging-postgres`) | main database `lumio` + roles | `pg_dump -Fc` + `pg_dumpall --globals-only` |
| TimescaleDB (`staging-tsdb`) | `lumio_tsdb` (hypertable chunks, compressed chunks, continuous-aggregate materializations) + roles | `pg_dump -Fc` + `pg_dumpall --globals-only` |
| Extensions PostgreSQL (`staging-extensions-postgres`) | `lumio_extensions` (`ext_*` schemas) + the roles from `initdb/extensions/10-roles.sh` | `pg_dump -Fc` + `pg_dumpall --globals-only` |
| Redis (`staging-redis`) | the `/data` directory: AOF (`appendonlydir/`) and `dump.rdb` | file copy outside an AOF rewrite |

Uploaded files are not on the host: the app stores them in its own R2 bucket
(`[storage]` in the API config). They are not part of this backup.

Redis holds data that has no other copy until it is flushed: the chat buffer,
parked events, extension storage and automation variables (see
[Data layer](./data-layer-staging.md#redis-noeviction)). The script copies `/data`
only while no AOF rewrite runs. If the AOF manifest changes during the copy, it
copies again.

Each dump is streamed straight into restic (`--stdin-from-command`), so no
unencrypted dump file is written to disk. If `pg_dump` fails, restic creates no
snapshot and the job fails.

## Tool, schedule and target

| Item | Value |
|------|-------|
| Tool | [restic](https://restic.readthedocs.io/) ≥ 0.19 (0.19.0 fixed a hang in `--stdin-from-command`; tested with 0.19.1), one repository per environment |
| Schedule | `lumio-backup.timer`: daily 03:15 UTC (`Persistent=true` catches up a missed run). `lumio-backup-check.timer`: Sundays 05:00 UTC, `restic check --read-data-subset=5%` |
| Target | Any S3-compatible object storage in the EU, one bucket per environment (`lumio-backup-prod`, `lumio-backup-staging`), each with its own access key and its own restic password. Staging uses **Cloudflare R2** with the EU jurisdiction today. See [Choosing or switching the S3 provider](#choosing-or-switching-the-s3-provider) |
| Monitoring | A failed run shows in `systemctl --failed` and `journalctl -u lumio-backup`. An optional dead-man's switch URL (`BACKUP_PING_URL`) gets a ping on success and `/fail` on failure |

## Encryption and key

restic encrypts all repository data with **AES-256 in counter mode**, authenticated
with **Poly1305-AES**. The repository key is derived from the password with
scrypt (restic design document, read 2026-10-27). The target only ever holds
ciphertext.

- The password is in `/etc/lumio-backup/restic.pass` (owner `root`, mode `0600`)
  on the database host. The host disk is fully encrypted.
- A second copy is in the operator's password manager. Without the password,
  no backup can be restored.
- The password is **never** stored at the backup target: not in the bucket and
  not in a file next to the repository.
- The S3 access key is in `/etc/lumio-backup/env` (owner `root`, mode `0600`).
  It can reach only that one backup bucket. So a compromised staging host can
  neither read nor delete the production backups, and neither host can touch
  the app's upload bucket.

## Retention: 14 days

`lumio-backup.sh` deletes every snapshot older than `BACKUP_RETENTION_DAYS`
(default 14) and prunes the repository data after each backup. Age is measured
against the clock, not against the newest snapshot. So if backups stop, old
snapshots are still deleted on time. With one backup a night, there are about
14 restore points, and the oldest one goes back 14 days. Damage that is noticed
later than that cannot be undone from a backup.

The value must stay below 30 days, because two deletion promises reach into
backups:

- `legal/privacy.mdx`: deleted YouTube revenue data disappears from backups at the
  latest 30 days after the deletion. The same holds for every other deletion (a
  deleted profile, an erased chatter, a Shopify `customers/redact`).
- Shopify API Terms §6.2.3: merchant data is deleted within 30 days.

Retention depends on the bucket as well. **Versioning** and **object lock** (R2:
bucket lock) must stay off, because they would keep deleted data beyond the 14
days or stop restic from deleting it. A **lifecycle rule** must not be added,
because it would delete restic's data files underneath the repository.

## Setting up a host

At the S3 provider, once per environment (details per provider in
[Choosing or switching the S3 provider](#choosing-or-switching-the-s3-provider)):

1. Create the private bucket `lumio-backup-<env>` (`prod` or `staging`) in an EU
   location, with versioning, object lock and lifecycle rules off.
2. Create an access key that can reach only this bucket. Note the access key ID
   and the secret access key; most providers show the secret only once.

As root on the database host (production or staging):

1. Install restic ≥ 0.19 and `jq`. Distribution packages are often older (Ubuntu
   24.04 ships 0.16.4, which lacks `--stdin-from-command`). In that case install
   the release binary from GitHub, compare its SHA-256 with the release's
   `SHA256SUMS`, put it in `/usr/local/bin`, and remove the distribution
   package. Check with `restic version`.
2. Copy the scripts and units:
   ```bash
   install -d -m 0700 /opt/lumio-backup /etc/lumio-backup
   install -m 0700 dev-stack/staging/backup/{lumio-backup.sh,lumio-backup-common.sh,restore-test.sh,restore.sh} /opt/lumio-backup/
   install -m 0644 dev-stack/staging/backup/README.md /opt/lumio-backup/
   install -m 0644 dev-stack/staging/backup/lumio-backup*.{service,timer} /etc/systemd/system/
   install -m 0600 dev-stack/staging/backup/lumio-backup.env.example /etc/lumio-backup/env
   ```
3. Fill in `/etc/lumio-backup/env`: the repository and region of the provider block you chose, the access key, `LUMIO_ENV`, the container
   names, `REDIS_DATA_DIR` and `REDIS_PASSWORD`.
4. Create the password and the repository:
   ```bash
   (umask 077; openssl rand -base64 32 > /etc/lumio-backup/restic.pass)
   set -a; . /etc/lumio-backup/env; set +a
   restic init
   ```
   Store the password in the password manager now.
5. Run a first backup by hand, then enable the timers:
   ```bash
   /opt/lumio-backup/lumio-backup.sh backup
   systemctl daemon-reload
   systemctl enable --now lumio-backup.timer lumio-backup-check.timer
   ```
6. Run the [restore test](#restore-test) and add the result to the
   [restore log](#restore-log).

## Choosing or switching the S3 provider

restic's S3 backend works with any S3-compatible object storage, and the scripts
only pass `RESTIC_REPOSITORY`, `AWS_DEFAULT_REGION` and the access key through.
The provider is therefore chosen in `/etc/lumio-backup/env` alone.
`lumio-backup.env.example` has a ready block for each of these (provider docs
read 2026-10-27):

| Provider | `RESTIC_REPOSITORY` | `AWS_DEFAULT_REGION` | EU location | Key limited to one bucket |
|----------|---------------------|----------------------|-------------|---------------------------|
| Cloudflare R2 | `s3:https://<ACCOUNT_ID>.eu.r2.cloudflarestorage.com/<bucket>` | `auto` | bucket created with jurisdiction **European Union** (cannot be changed later) | API token with *Object Read & Write* on this bucket |
| Hetzner Object Storage | `s3:https://fsn1.your-objectstorage.com/<bucket>` | `fsn1` (or `nbg1`, `hel1`) | all locations are in the EU | a Hetzner key opens **every** bucket of its project, so use one project per environment |
| DigitalOcean Spaces | `s3:https://fra1.digitaloceanspaces.com/<bucket>` | `us-east-1` (signing only; the endpoint decides the location) | `fra1` or `ams3` | Spaces key with *Limited access* to this bucket |
| AWS S3 | `s3:https://s3.eu-central-1.amazonaws.com/<bucket>` | `eu-central-1` (or another EU region) | EU regions | IAM user whose policy allows only this bucket |
| Self-hosted MinIO | `s3:https://<minio-host>:9000/<bucket>` | `us-east-1` (MinIO's default) | a server in the EU that is **not** the database host | MinIO user whose policy allows only this bucket |

For every provider: private bucket, versioning, object lock and lifecycle rules
off. Prod and staging never share a bucket or a key.

A self-hosted MinIO only counts as off-host if it runs on a different machine
than the databases (ideally at another provider or data centre), with an
encrypted disk, reached over HTTPS. If its certificate comes from its own
certificate authority, put the CA file into `RESTIC_CACERT`. The scripts load
every variable of the env file into restic's environment. Tested against MinIO
with a self-signed certificate (2026-10-27): backup, `restore-test.sh` (PASS)
and `restore.sh --dry-run`. Without `RESTIC_CACERT` restic refuses the
connection (`x509: certificate signed by unknown authority`).

**Switching provider** (for example from R2 to Hetzner):

1. Create the bucket and key at the new provider.
2. Keep the old configuration and its password: copy `/etc/lumio-backup/env` to
   `env.<old-provider>`, rename `restic.pass` to `restic.pass.<old-provider>`,
   and point `RESTIC_PASSWORD_FILE` in `env.<old-provider>` at the renamed file.
   Without that, the new password would overwrite the old one and the old
   backups could no longer be read.
3. Put the new provider's values into `/etc/lumio-backup/env` (`RESTIC_REPOSITORY`,
   `AWS_DEFAULT_REGION`, the key). Create a new `restic.pass`, store it in the
   password manager, and run `restic init`. The commands are in the folder's
   `README.md`.
4. Run `lumio-backup.sh backup` and `restore-test.sh`. The timers back up to the
   new provider from now on.
5. The old backups stay restorable for the transition:
   `LUMIO_BACKUP_ENV=/etc/lumio-backup/env.<old-provider> /opt/lumio-backup/restore.sh --dry-run`.
   Nothing prunes them any more, so **delete the old bucket 14 days after the
   switch** at the latest. That keeps the 30-day deletion promise, and by then
   the new provider holds a full set of restore points.

Copying the old snapshots over is not worth it: with 14 days of retention, the
new provider holds a full set of restore points two weeks after the switch.

**Several targets at once.** With `BACKUP_TARGETS="r2 hetzner"` in the main env
file and one file per target in `/etc/lumio-backup/targets/<name>.env` (its own
bucket, key and restic password), every backup goes to all targets one after
the other. A target that does not answer within `BACKUP_TARGET_TIMEOUT` seconds
(default 120) or fails is reported, and the others still run; the run then ends
with exit code 1 (`backup failed for: <names>`). Each target keeps its own 14 days.
`--target <name>` limits `lumio-backup.sh`, `restore-test.sh` and `restore.sh` to
one target; the restore scripts default to the first one. Run the restore test
for every target. Setup steps are in the folder's `README.md`.

## Restore test

Run it after setting up a host, after every change to the backup setup, and at
least once a quarter:

```bash
/opt/lumio-backup/lumio-backup.sh backup
/opt/lumio-backup/restore-test.sh
```

`restore-test.sh` takes the newest snapshot of each store and restores it into
throwaway containers. These containers run the same image as the live
containers and have no network (`--network none`). TimescaleDB is restored
between `timescaledb_pre_restore()` and `timescaledb_post_restore()`, into a
database created from `template0` with the **same extension version as the
dump**. The installed extension can be older than the image's default (the
`-ha` image ships older versions too), and a dump restores only into its own
version. The backup records that version as the tag `timescaledb-<version>` on
the TimescaleDB snapshot. Redis
loads the restored AOF. The script then counts rows **created before the
snapshot time** in the live and the restored databases:

- `platform_event_logs` and `platform_chat_messages` (TimescaleDB),
- `users` and `accounts` (PostgreSQL),
- the number of `ext_*` schemas (extensions PostgreSQL),
- the Redis key count after the AOF is loaded.

It prints a result block for the restore log. Afterwards it deletes the scratch
containers and files, because they hold production data. The scratch directory is
`/var/tmp` on the encrypted disk. Never copy a restored database or a dump to
another machine.

| Result | Meaning |
|--------|---------|
| `PASS` | all counts match, `pg_restore` reported no errors, Redis loaded its keys |
| `CHECK` | the restore worked, but a count differs or `pg_restore` reported errors. A smaller live count is expected when retention or a deletion removed rows after the snapshot. A smaller restored count, or any `pg_restore` error, is a failed test |
| `FAIL` | Redis did not load, or a count query failed on one side (`ERR` in the table, for example a missing table). Exit code 1 |

## Restoring production

`restore.sh` brings the live data layer back to a snapshot. It **overwrites** the
live databases and the Redis data, so it differs from `restore-test.sh`, which
only ever restores into throwaway containers. A restore brings the data back to
the snapshot time, which is at most about 24 hours old. Everything after that
point is lost, including deletions.

1. Stop the API, the bots and the workers.
2. Look at the plan first. It lists the snapshot of each store and its time, and
   changes nothing:
   ```bash
   /opt/lumio-backup/restore.sh --dry-run
   ```
   `--before 2026-10-27T03:00:00Z` picks the newest snapshots older than that
   time. `--only tsdb,redis` restores only some stores (`postgres`, `tsdb`,
   `extensions`, `redis`).
3. Restore. The script asks for the host tag (`lumio-<env>`) before it changes
   anything:
   ```bash
   /opt/lumio-backup/restore.sh
   ```
   What it does:
   - It refuses to run while other sessions are connected to a target database.
     `--terminate` ends them instead.
   - It takes a safety backup of the current state first, without pruning, so a
     wrong restore can itself be undone. If a database is already gone, skip it
     with `--no-safety-backup`.
   - For each database: it creates only the **missing** roles (existing roles keep
     their current passwords), recreates the database from `template0` with its
     previous owner, and runs `pg_restore`. TimescaleDB gets the extension version
     from the snapshot's `timescaledb-…` tag and is restored between
     `timescaledb_pre_restore()` and `timescaledb_post_restore()`. Every session
     runs with `event_triggers=off`, so the
     [access-log login trigger](./protected-data-access-log.md) does not interfere.
   - Redis: it stops the container, moves the current data directory aside
     (`<dir>.before-restore-<time>`, never deleted), puts the restored one in
     place, starts the container and waits until the AOF is loaded.
   - At the end it prints the snapshot IDs, the `pg_restore` errors (exit code 1
     if there are any) and the row counts of the stores it restored.
4. Repeat the deletions made after the snapshot time. The audit log in the
   restored TimescaleDB does not contain them. Use what still exists outside
   the database: support requests, the Shopify Partner Dashboard webhook log
   (`customers/redact`, `shop/redact`) and Google revocations, which the daily
   check picks up again on its own.
5. Start the services. The TimescaleDB retention policies and the daily
   compliance and retention jobs run again on their normal schedule. Once
   everything works, delete the Redis directory that was moved aside.

## Restore log

| Date (UTC) | Host | Snapshots | Result | Tested by |
|------------|------|-----------|--------|-----------|
| — | production | — | pending: the production host is not set up yet | — |
| 2026-10-27 22:59 | staging | postgres `7d409dd8`, tsdb `e1b2f479` (TimescaleDB 2.31.0), extensions `621e9cff`, redis `8b0670a6` | **PASS**: users 18 = 18, accounts 11 = 11, `platform_event_logs` 16 031 = 16 031, `platform_chat_messages` 127 857 = 127 857, `ext_*` schemas 0 = 0; Redis 292 keys; 0 `pg_restore` errors | operator (founder) |

---

## Developer Guide / Cookies Consent Library

Source: https://docs.lumio.vision/developer-guide/cookies-consent

# Cookies Consent Library

The `@lumio/cookies-consent` shared package provides a GDPR-compliant cookie-consent UX for Lumio's external frontend apps (`apps/web`, `apps/id` and `apps/stats`).

It wraps a provider, banner, preferences modal, floating settings button, and detection hooks, with one additive feature (`exemptPathPrefixes`) to silence the banner on OBS overlay routes where a consent dialog would be inappropriate.

## When to use

- Wrap your app's root layout with `<ConsentProvider>`.
- Render `<ConsentPrePaintScript />` inside that layout's `<head>`, with the same `exemptPathPrefixes` (see [First paint](#first-paint-pre-paint-script)).
- The provider renders `<ConsentBanner />` and `<CookieSettingsButton />` automatically (controlled by `showFloatingButton` - default `true`).
- Use `useConsent()` from any client component to gate loading of non-essential scripts / cookies.

## Consumer apps must mount `<TooltipProvider />`

The `CookieSettingsButton` floating tooltip uses Lumio's shared `<TooltipProvider />` (from `@lumio/ui`) which reads `data-tooltip` / `data-tooltip-pos` attributes. Mount the provider once at your app's root layout.

`data-tooltip-pos` (`top` \| `bottom` \| `left` \| `right`, default `top`) is a *preference*, not a hard constraint: if the tooltip would clip past the viewport on the requested side it flips to the opposite side, and its cross-axis position is clamped to the viewport edge instead of being cut off. This keeps tooltips readable when the anchor sits in the top row of a popout or hard against a viewport edge.

## Public API

| Symbol | Kind | Purpose |
|---|---|---|
| `ConsentProvider` | Component | Wraps the app, loads/persists state, renders banner + floating button. |
| `useConsent()` | Hook | Returns `hasConsented`, `isAllowed(category)`, `consent`, `openPreferences`, `isExempt`. (`openPreferences` is the context's `openBanner`.) |
| `useConsentContext()` | Hook | The full context value, including `acceptAll` / `acceptEssentialOnly` / `closeBanner`. `useConsent()` is the narrowed, preferred surface. |
| `useCookiePreferences`, `useCookieStatus` | Hook | Preferences-modal state and per-category status. |
| `useCookieDetector`, `useStorageDetector`, `useBrowserDataDetector` | Hook | Reactive wrappers over the detection utils below. |
| `ConsentPrePaintScript` | Component (server) | Inline `<head>` script that decides before the first paint whether the banner shows. |
| `buildConsentPrePaintScript(exemptPathPrefixes)` | Util | The script source `ConsentPrePaintScript` renders, for a custom `<head>`. |
| `ConsentBanner`, `CookieSettingsButton`, `CookieStatusIndicator` | Component | Standalone UI pieces if you need them outside the provider's auto-render. |
| `ConditionalScript`, `ConditionalContent`, `EssentialScript` | Component | Only mount `<script>`-like content when a category is allowed. |
| `GoogleAnalytics`, `FacebookPixel`, `Hotjar`, `Matomo`, `Plausible` | Component | Pre-wired analytics integrations that respect consent. |
| `defaultTranslations` | Data | `{ en, de }` default copy. |
| `getStoredConsent`, `setStoredConsent`, `clearStoredConsent` | Util | Low-level localStorage access. |
| `getDetectedCookies`, `getCookiesByCategory`, `getCookiesByService`, `hasServiceCookies`, `getCookieSummary` | Util | Runtime cookie detection (drives the preferences modal). |
| `getDetectedStorage`, `getDetectedLocalStorage`, `getDetectedSessionStorage`, `getStorageByCategory`, `getStorageByType`, `getStorageByService`, `hasServiceStorage`, `getStorageSummary` | Util | Same for localStorage / sessionStorage. |

## Integration status

The library is mounted in three consumer apps:

| App | Mounted in | `appName` | `exemptPathPrefixes` | Policy URL |
|---|---|---|---|---|
| `apps/web` | `src/app/(main)/layout.tsx` | `"Web"` | `["/overlay", "/popout", "/api", "/dashboard", "/account", "/hub"]` | `/legal/cookies` (relative) |
| `apps/web` (public share page) | `src/app/(public)/layout.tsx` | `"Web"` | none | `/legal/cookies` (relative) |
| `apps/id` | `src/app/layout.tsx` | `"ID"` | none | `${WEB_URL}/legal/cookies` |
| `apps/stats` | `src/app/layout.tsx` | `"Stats"` | none | `https://lumio.vision/legal/cookies` |

Each of these layouts also renders `<ConsentPrePaintScript />` in its `<head>`. `apps/web` keeps its exempt list in one `CONSENT_EXEMPT_PATHS` constant and passes it to both the script and the provider. Each app's `globals.css` lists `shared/cookies-consent/src` as a Tailwind `@source`, otherwise the banner's utility classes are not generated.

Each app mounts `<TooltipProvider />` next to `<ConsentProvider>` inside `NextIntlClientProvider`. The provider renders the banner and floating settings button internally - consumers do NOT pass them as children. `apps/web` (`(main)` layout) and `apps/id` additionally nest `<SentryConsentSync />` inside the provider so Sentry's capture follows the consent state ([Error tracking](./error-tracking.md)).

**Third-party images on public pages.** Public trees of `apps/web` (share page, marketing, legal) wrap their content in `<PublicMediaPolicy>` (`apps/web/src/components/third-party-media-gate.tsx`); Lumio Stats mounts `ProxiedImagePolicy` once in its root layout. Avatars, emotes, badges and Bits graphics then load through the same-origin [image proxy](./image-proxy.md) and need no consent. Only GIPHY GIFs still wait for Functional consent (`useGifsAllowed()` in web, `useConsent()` in Stats `top-gifs.tsx`). See [Third-party images on public pages](#third-party-images-on-public-pages).

The webapp exempts the whole authenticated surface (`/dashboard`, `/account`, `/hub`) in addition to the embed routes, so the banner only appears on the public marketing and legal pages.

`apps/admin` does NOT integrate the consent library. Admin is an internal, auth-gated tool for the zaflun team - no external end-users reach it, so no GDPR consent prompt is required.

Bot apps and `apps/docs` do not integrate the library either (server-only / Docusaurus).

## Third-party images on public pages

Platform avatars (Twitch, Google, Discord, Kick), chat emotes, badges, GIPHY GIFs and Bits graphics live on the provider's CDN. Loading one straight from there sends the visitor's IP address and user agent to that provider. Signed-in dashboard and popout pages load them directly, because they are contract-based. Pages reachable without login do not:

- **Avatars, emotes, badges, panel artwork, Bits / KICKs graphics** load through the same-origin [image proxy](./image-proxy.md) (`/img/<provider>/…`). No third party receives a request from the visitor, so there is no consent gate for them.
- **GIPHY GIFs** are not proxied and load only after **Functional** consent. Before that, the page mounts no `<img>` pointing at GIPHY. Hiding a mounted image would still send the request.

How the apps wire it:

- `apps/web` wraps every public tree in `PublicMediaPolicy` (`src/components/third-party-media-gate.tsx`): `src/app/(public)/layout.tsx` (share pages), `src/app/(main)/(marketing)/layout.tsx` (ideas board, invite pages and the other marketing pages) and `src/components/legal/legal-shell.tsx`. It must sit below a `ConsentProvider`.
- The policy sets `AvatarImagePolicy` from `@lumio/ui` with `resolveSrc={proxiedImageUrl}`. Every `AvatarImage` and `ChannelAvatar` below it loads the proxied URL, or shows its initials when the proxy does not cover the URL. Avatars need no per-call code.
- Other image leaves call `useImageSrc()` / `useImageSrcSet()` (emotes, badges, Bits, the hover card) and `useGifsAllowed()` (GIFs). Outside a policy `useImageSrc()` returns the URL unchanged and GIFs are allowed. A `null` from `useImageSrc()` means "render the placeholder", never the raw URL.
- `apps/stats` mounts `ProxiedImagePolicy` once in `src/app/layout.tsx` and rewrites emotes (`EmoteImage`) and panel artwork (`proxiedSlides` in `channel-panels.tsx`) on the server, so the HTML carries no CDN URL. `top-gifs.tsx` keeps its `useConsent()` gate.
- A new public page that renders these components must sit below the policy.

## `exemptPathPrefixes`

Pass this prop to the provider to suppress the consent UI on specific pathname prefixes (e.g. OBS browser-source routes at `/overlay/*` where a banner would break the embed).

On matching paths:

- `<ConsentBanner />` and `<CookieSettingsButton />` do not render - not even in the server HTML, because `usePathname()` also resolves during server rendering.
- The pre-paint script sets nothing, provided it got the same list.
- `useConsent().isExempt === true`.
- `isAllowed("essential")` returns `true`; all other categories return `false`.
- `acceptAll / acceptEssentialOnly / openPreferences / openBanner / closeBanner` are no-ops.

```tsx
<ConsentProvider
  translations={defaultTranslations[locale]}
  policyUrl="/legal/cookies"
  appName="Web"
  exemptPathPrefixes={["/overlay", "/api"]}
  footerLinks={{ privacyUrl: "/legal/privacy", imprintUrl: "/legal/imprint" }}
>
  {children}
</ConsentProvider>
```

## First paint (pre-paint script)

The visitor's choice lives in `localStorage`, which the server cannot read. So the banner is decided in the browser, before the first paint, without waiting for the app to hydrate:

1. On every non-exempt page the provider renders the banner into the server HTML inside `<div class="lumio-consent-root" data-prepaint>`. CSS (`ConsentBanner.css`) hides it.
2. `<ConsentPrePaintScript />` runs inline in `<head>`. When no valid choice is stored and the path is not exempt, it sets `data-consent="needed"` on `<html>`. Only then does the CSS show the banner (and lock page scrolling).
3. Until the app hydrates, the script also handles **Accept all** and **Essential only**: a tap on a `[data-consent-action]` button stores the choice in the same format as `setStoredConsent()` and sets `data-consent="given"`, which hides the banner. The tap is not passed on to React, so it is not replayed after hydration. **Customize** needs React; until then it shows a pending state.
4. On hydration `ConsentProvider` reads the stored choice, removes the `data-consent` attribute and drops `data-prepaint`. From then on React alone decides whether the banner is open.

Result: a visitor without a choice sees the banner in the first paint; a visitor with a choice never sees it, not even for a frame. If the script does not run, the provider still opens the banner after hydration.

The **Customize** view (cookie and storage detection, the per-category tables) is code-split with `React.lazy` and loads when opened, behind a layout-matched skeleton.

Below the `md` breakpoint the backdrop is a plain dark dim. The backdrop blur is used from `md` up only, because a full-screen blur cost about 16 % of the frame rate on a throttled phone (Moto G Power emulation, 4× CPU: ~16.8 vs ~20.0 fps with animated content underneath).

The script is an inline script without a nonce, like the `next-themes` script. `apps/web`'s app-level CSP is Report-Only with `'unsafe-inline'` in `script-src`. A future enforcing CSP has to allow it by nonce or hash, together with the other inline scripts.

## Adding a cookie

Edit `shared/cookies-consent/src/utils/cookieDetector.ts`. Append to the `cookiePatterns` array:

```ts
{ pattern: /^your_cookie_name$/, category: "functional", service: "Your Service" }
```

An optional `devOnly: true` marks a cookie that only appears in local development. A name matching no pattern falls through to `category: "unknown"`.

Also add a matching entry to `shared/cookies-consent/src/i18n/en.json` (and `de.json`) under the appropriate category's `cookies` array so the preferences modal shows the human-friendly name + purpose + duration.

## Storage key

Persistent state is stored under `localStorage["lumio_cookie_consent"]` as `{ version, ... }`. `getStoredConsent()` returns `ConsentState | null` and **clears** the entry when the stored `version` does not match the library's current `STORAGE_VERSION`, or when the record is incomplete (`hasConsented` is not `true`, or `categories` is missing). A version bump therefore re-prompts every user. The pre-paint script applies the same rule (`shared/cookies-consent/src/utils/prepaint.ts`), so both always agree on whether the banner shows.

## Categories

`essential`, `functional`, `statistics`, `marketing` (`CookieCategory` in `shared/cookies-consent/src/types/consent.ts`) - semantics match the spec at `docs/superpowers/specs/2026-04-16-cookies-consent-library-design.md`, with the app integration described in `2026-04-17-cookies-consent-integration-design.md`.

---

## Developer Guide / Image Proxy

Source: https://docs.lumio.vision/developer-guide/image-proxy

# Image Proxy

Lumio's public pages show images that live on third-party CDNs: Twitch, 7TV, BetterTTV and FrankerFaceZ emotes, platform avatars, Twitch panel artwork and Bits graphics. If the visitor's browser loaded them from those CDNs, each request would send the visitor's IP address and user agent to the provider. The image proxy avoids that. The browser loads `/img/<provider>/<path>` from the Lumio host it is already on, and the Lumio server fetches the upstream image without any visitor data.

The proxy is a route handler in each public app, built from the shared package `@lumio/image-proxy` (`shared/image-proxy`):

| App | Route | Covered pages |
|-----|-------|---------------|
| `apps/stats` | `src/app/img/[...path]/route.ts` | every Stats page |
| `apps/web` | `src/app/img/[...path]/route.ts` | the share report `/share/history/[token]`, the ideas board `/ideas` and `/ideas/[id]`, the invite pages `/invite/*`, and the other marketing and legal pages |

The signed-in dashboard, Multichat, popouts and overlays do **not** use it. They load images directly from the CDNs, because their users are contract parties. GIPHY GIFs are not proxied anywhere; on public pages they still wait for Functional consent ([Cookies Consent Library](./cookies-consent.md#third-party-images-on-public-pages)).

## Providers

A proxy URL names a provider key, never a host or a full URL, so the proxy can reach only these hosts, and on each host only these first path segments:

| Key | Upstream host | Allowed first segment | Query |
|-----|---------------|-----------------------|-------|
| `ttv` | `static-cdn.jtvnw.net` | `emoticons`, `jtv_user_pictures`, `badges` | none |
| `ttvpanel` | `panels.twitch.tv` | exactly one segment `panel-<channel id>-image-<uuid>` (Twitch panel artwork) | none |
| `7tv` | `cdn.7tv.app` | `emote` | none |
| `bttv` | `cdn.betterttv.net` | `emote` | none |
| `ffz` | `cdn.frankerfacez.com` | `emote` | none |
| `yt` | `yt3.ggpht.com` | one opaque segment, or `ytc/<one segment>` | none |
| `discord` | `cdn.discordapp.com` | `avatars`, `icons` (never `attachments`) | `size` ∈ 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 |
| `kick` | `files.kick.com` | `images`, `emotes`, `kicks`, `channel_subscriber_badges` | none |
| `kickext` | `ext.cdn.kick.com` | `chat` | none |
| `bits` | `d3aqoihi2n8ty8.cloudfront.net` | `actions` | none |

The table lives in `shared/image-proxy/src/providers.ts`. Adding a provider or a segment widens what the proxy fetches, so it needs an AppSec review.

## Rewriting URLs

`proxiedImageUrl(src)` from `@lumio/image-proxy` turns `https://static-cdn.jtvnw.net/emoticons/v2/25/default/dark/1.0` into `/img/ttv/emoticons/v2/25/default/dark/1.0`. It returns `null` for anything the proxy would refuse. The caller then renders its fallback (initials, the emote code, a placeholder) and **never** the raw URL.

`proxiedImageUrl` and the handler share one validator (`shared/image-proxy/src/path.ts`). A URL is accepted only in its canonical form, so every image has exactly one proxy URL and one cache key:

- `https:` only, no userinfo, no port (`:443` included), no fragment, nothing the URL parser would normalise (dot segments, upper-case host).
- Path segments match `[A-Za-z0-9._~=-]+`: no `%` (nothing encoded), no `\`, no empty segment (`//`, a trailing `/`), no `.` or `..`. The upstream path is at most 512 bytes.
- A query string only where the provider allows one. Each parameter appears at most once, is never empty, takes a value from the fixed set, and keys are in sorted order.

`proxiedSrcSet(srcSet)` does the same for every candidate of a `srcset` and returns `null` if any candidate cannot be proxied.

Where the components get the rewrite:

- **Stats**: `ProxiedImagePolicy` in the root layout sets `AvatarImagePolicy resolveSrc={proxiedImageUrl}` from `@lumio/ui`, so every `AvatarImage` and `ChannelAvatar` loads the proxied URL. `EmoteImage` and the panel artwork (`proxiedSlides` in `channel-panels.tsx`) rewrite on the server, so the HTML carries no CDN URL.
- **Web**: `PublicMediaPolicy` (`src/components/third-party-media-gate.tsx`) sets the same `AvatarImagePolicy`. Other leaves call `useImageSrc()` / `useImageSrcSet()`: `ChatEmoteImage`, `BitsToken`, the report's emote, chatter, AutoMod and event avatars, and the emote hover card. Outside a policy (dashboard) these hooks return the URL unchanged.

## Request handling

| Step | Rule |
|------|------|
| Path | Canonical form as above. A syntax error is `400`; an unknown provider or first segment is `404`. Nothing is fetched. |
| Outbound headers | Built fresh. **No incoming header is copied**: no `X-Forwarded-For`, `Forwarded`, `CF-Connecting-IP`, `X-Real-IP`, `Cookie`, `Referer`, `User-Agent` or `Accept-Language`. The proxy sends `User-Agent: LumioImageProxy/1 (+https://lumio.vision)` and `Accept: image/avif,image/webp,image/png,image/gif,image/jpeg`, with `credentials: "omit"` and `referrerPolicy: "no-referrer"`. |
| Data Cache | `cache: "no-store"` on the fetch and `dynamic = "force-dynamic"` on the route, so Next keeps no copy. |
| Redirects | `redirect: "manual"`. At most 2 redirects, each only to a URL `proxiedImageUrl` would also accept. Anything else is `502`. |
| Timeout | 5 s, and the fetch is also aborted when the visitor's request goes away (`request.signal`). |
| Status | Only an upstream `200` passes. An upstream `404` is `404`; every other status is `502`. |
| Type | `image/png`, `image/jpeg`, `image/gif`, `image/webp` or `image/avif` from the upstream `Content-Type`. No SVG. The bytes are not inspected, with one exception: `files.kick.com` serves emotes as `binary/octet-stream`, so for the `kick` provider only an octet-stream body is typed by its file signature. It passes only if the signature names one of the five raster types. |
| Size | At most 2 MiB. `Content-Length` is checked first, and the body is counted while it is read. |

Logs carry the provider key and the status class only, never the path, because avatar paths contain platform user ids.

## Response

Every response gets fresh headers. Only the validated `Content-Type` comes from upstream; upstream `Set-Cookie`, `Cache-Control` and other headers are dropped.

| Header | `200` | Errors (`400`, `404`, `502`) |
|--------|-------|------------------------------|
| `Cache-Control` | `public, max-age=86400, s-maxage=86400` | `public, max-age=60` |
| `Content-Type` | the validated image type | none (empty body) |
| `X-Content-Type-Options` | `nosniff` | `nosniff` |
| `Content-Security-Policy` | `default-src 'none'; sandbox` | same |
| `Cross-Origin-Resource-Policy` | `same-origin` | same |

## Caching and retention

There is no server-side store: no Redis key, no object storage, no disk, no Next Data Cache. The only copies of an image are HTTP caches, the Cloudflare edge and the visitor's browser, and `max-age=86400` bounds both to **24 hours** whatever the upstream sends. Invalidation is expiry only.

The 24 hours bound the image bytes. The avatar URL itself is kept by the read model for as long as the stream report exists, until erasure; the proxy adds no retention of its own. After an erasure the page stops referencing the image, and remaining cached copies expire within 24 hours.

Cloudflare settings matter here: a zone *Browser Cache TTL* above 24 hours, or an *Edge Cache TTL* cache rule that ignores the origin header, would keep copies longer. Both must respect the origin `Cache-Control` for `/img/*`.

## Request interception

`/img/` bypasses request interception. The `apps/web` `proxy.ts` matcher excludes `img/`, so the route gets no login redirect, no locale cookie and no CSP nonce, and a publicly cached image never carries a `Set-Cookie`. `apps/stats/src/proxy.ts` still runs on `/img/` (it sets `X-Robots-Tag` per deployment), but it never sets the `?lang=` locale cookie there, the same rule as for `/og/`. `robots.txt` does not disallow `/img/`, so search engines can fetch images on indexed pages.

Next itself normalises a request path before the handler runs. Dot segments (`/../`, `/%2e%2e/`) are resolved first, so they can only reach a path that passes the allow-list. A doubled or trailing `/` gets a `308` to the canonical path.

## Tests

`shared/image-proxy/__tests__/` (vitest project `image-proxy`) covers the rewrite for every provider, the rewrite and handler refusing every non-canonical or disallowed input, a test that the mocked upstream fetch receives none of the visitor's headers, the redirect, type, size, status and timeout limits, and the `Cache-Control` values. `apps/web/__tests__/third-party-media-gate.test.tsx` checks that a public tree renders only `/img/` URLs, and `apps/web/__tests__/proxy-img-matcher.test.ts` checks the matcher exclusion.

---

## Developer Guide / MDX Content Pipeline

Source: https://docs.lumio.vision/developer-guide/mdx-content

# MDX Content Pipeline

`apps/web` uses [`@next/mdx`](https://nextjs.org/docs/app/building-your-application/configuring/mdx) to render long-form content (currently: legal pages) from MDX files in `apps/web/content/`.

## Pipeline

`next.config.ts` wraps the Next config with `createMDX({ extension: /\.mdx?$/, options: {...} })` and pipes:

- `remark-gfm` - GitHub-flavoured markdown (tables, strikethrough, task lists).
- `rehype-slug` - derives `id` attributes from heading text.
- `rehype-autolink-headings` - appends an anchor link (`className: ["heading-anchor"]`) to each heading.

Plugins are configured as **string names** (or `[name, options]` tuples), not imported function references: Next.js 16 / Turbopack requires the plugin spec to be serializable.

`apps/web/mdx-components.tsx` maps every MDX element (`h2`, `p`, `table`, `blockquote`, …) to Tailwind-styled React components using Lumio design tokens. No per-page overrides are needed - all legal pages inherit this mapping.

## Current surface

The MDX pipeline currently powers the six legal pages under `/legal`:

- `imprint`
- `privacy`
- `terms`
- `cookies`
- `security`
- `faq`

## Adding a legal page

1. Add the slug to `LEGAL_PAGES` in `apps/web/src/components/legal/legal-pages.ts` with an icon from `lucide-react`. That file carries **only** `slug` + `icon` - the `lastUpdated` date is not there.
2. Add MDX files at `apps/web/content/en/legal/<slug>.mdx` and `apps/web/content/de/legal/<slug>.mdx`, each exporting its own date: `export const meta = { lastUpdated: "YYYY-MM-DD" };`.
3. Add translation keys under `legal.pages.<slug>` in `messages/en.json` and `messages/de.json` (`title`, `description`, `navLabel`).
4. Register the EN + DE loader entries in `apps/web/src/lib/mdx-import.ts` so the dynamic `import()` specifiers stay string literals (required for Next.js to statically bundle them).

The route `/legal/<slug>` is produced automatically by the dynamic `legal/[slug]/page.tsx` handler.

## Fallback behaviour

If `/content/<locale>/legal/<slug>.mdx` doesn't exist, `importLegalMdx` falls back to the English file. If the English file is also missing, the page calls `notFound()`.

## TOC generation

`rehype-slug` sets heading IDs at build time. The `LegalToc` component (client) reads the rendered DOM and drives the "On this page" sidebar using an IntersectionObserver. No manual TOC authoring is needed.

## Adding bigger styling changes

All MDX typography lives in `apps/web/mdx-components.tsx`. Don't add Tailwind classes inside MDX body text - they'd apply to plain markdown as well and leak inconsistent styling.

---

## Developer Guide / SEO Foundation

Source: https://docs.lumio.vision/developer-guide/seo-foundation

# SEO Foundation

## Overview

The public web pages get titles, descriptions, canonical URLs, language alternates and share images from `apps/web/src/lib/seo.ts`. The ID app uses its own metadata helper in `apps/id/src/lib/seo.ts` for browser tabs and link previews; its pages are excluded from search indexing. All page copy comes from the English and German message catalogs.

## Page metadata and language URLs

Each public web page calls `buildPageMetadata(ns, { path, ...options })` in `generateMetadata`. The helper reads `<ns>.meta.title` and `<ns>.meta.description` from `apps/web/messages/en.json` and `apps/web/messages/de.json`. The `(main)` layout supplies the `%s - Lumio` title template and default description. The home page uses `absoluteTitle: true`; detail pages can pass `titleValues`, a fallback title and a data-backed description.

The web helper accepts `indexing: "index" | "noindex-follow" | "noindex-nofollow"` and `hreflang: false` where a page should not advertise language alternates. Public song and playlist detail pages use the indexable default; invite links use `noindex-nofollow`. The legal contact page uses `hreflang: true` by default, while `/withdraw` and `/cancel` disable it. Pages with either `noindex` setting do not emit alternates.

An explicit valid `?lang=de` selects German for one request. `?lang=en` selects English. The web and ID proxies validate the parameter, then resolve the language in this order: URL parameter, valid `locale` cookie, English default. The URL does not redirect. A valid parameter sets the `locale` cookie only if no cookie exists; it never overwrites an existing preference. Share-image requests ignore `?lang=`. See [Preferences](/user-guide/preferences#language) for the visitor-facing behavior.

For indexed web pages, the canonical URL uses the route path and the **explicit** language parameter, not the cookie. German is `https://lumio.vision/features?lang=de`; English and a URL without a valid parameter use `https://lumio.vision/features`. Other query parameters are omitted. The `hreflang` links are absolute: `en` points to the plain URL, `de` to `?lang=de`, and `x-default` to the plain URL. No canonical or alternates are emitted when the public origin is unknown. ID pages emit neither canonical nor `hreflang` links.

The ID helper reads `<ns>.meta.title` and optional `<ns>.meta.description` from `apps/id/messages/{en,de}.json`. Its root layout uses `common.meta.*` for the title template, description and share image.

## Crawler rules and sitemap

`LUMIO_APP_URL` is read at request time by `apps/web/src/lib/seo-env.ts`. Only the exact origin `https://lumio.vision` is indexable. Staging, local, unset and invalid values cause the web proxy to send `X-Robots-Tag: noindex, nofollow` on responses; page metadata also emits `noindex, nofollow`. `apps/web/src/app/robots.ts` allows crawling on production except `/invite/`, `/share/` and `/api/`, and advertises `/sitemap.xml`. The share images under `/og` stay crawlable, because link-preview crawlers such as Twitterbot obey `robots.txt` for the card image as well; on production the proxy keeps them out of search results with `X-Robots-Tag: noindex` on every `/og` and `/og/…` response, and sends no `X-Robots-Tag` on page routes. The proxy is the only place that sets the header, so no response carries two. In every other environment, `/robots.txt` disallows `/` and names no sitemap.

`apps/web/src/app/sitemap.ts` generates `/sitemap.xml` at request time. Its curated routes include the home, features, pricing, public music listings and legal pages; legal document slugs come from `LEGAL_SLUGS`. It also lists `/music/songs/{id}` for global safe and blocked songs and `/music/playlists/{id}` for system playlists with tracks. Song IDs come from keyset-paged `publicSongSitemap` reads (up to 5,000 per page, at most 45,000 song URLs in the sitemap); playlist IDs come from `publicSystemPlaylists`. The music enumeration is cached for one hour. If it fails or the music feature is off, the sitemap still serves the curated routes. Each entry uses the plain English/default URL and includes `en`, `de` and `x-default` alternates; there is no separate German entry. Detail entries use the song's `created_at` or playlist's `updated_at` as `lastModified` when present. An unknown `LUMIO_APP_URL` produces an empty sitemap. The route does not invent dates, priorities or change frequencies.

The ID app always emits `noindex, nofollow` in both metadata and `X-Robots-Tag`. Its `/robots.txt` disallows `/`; it has no sitemap. The web proxy publicly serves only the exact crawler paths `/robots.txt` and `/sitemap.xml`; ID publicly serves only `/robots.txt`. Both apps also serve `/og` paths without a login session. These exemptions do not open similarly named paths such as `/robots.txt/x` or `/og-x`.

### Stats indexing

`apps/stats/src/lib/seo-env.ts` reads `LUMIO_STATS_URL` at request time. Only
`https://stats.lumio.vision` permits indexing. Staging, production preview,
localhost, and an unset or invalid origin send `noindex, nofollow` in metadata
and `X-Robots-Tag`; dynamic `robots.txt` disallows `/`, and sitemap routes
return 404. Production `robots.txt` advertises `/sitemap.xml` and disallows
`/api/`. It does not disallow `noindex` pages or `/og/`, so crawlers and link
unfurlers can fetch those resources and see their directives.

The Stats home, ranking, games, emotes and partners pages are indexable.
Twitch and Kick channel pages are indexable; YouTube channel pages are
`noindex, follow`. Stream pages and the channel `/{channel}/history` route are
`noindex, follow`, search results are `noindex, follow`, and the personal
watchlist is `noindex, nofollow`. The channel page contains current profile
and active-panel content only. Its canonical uses the current login returned
by `publicChannelCard.channelLogin`, resolved from the stable channel ID.

`/sitemap.xml` is an index of `/sitemaps/static.xml` and zero-based
`/sitemaps/channels/{page}.xml` files. The static file contains the home,
five ranking metrics, games, emotes and partners. Each channel file holds at
most 45,000 URLs from the API's `public_stats.sitemap_platforms` allowlist
(default Twitch and Kick), with a login and stream start in the last 12 months, after
opt-outs are excluded. It never lists stream or history URLs. Its `lastmod` is
the latest stream-start date, and the file count is read at request time.

## Structured data

The home page emits `Organization` and `WebSite` JSON-LD through `buildHomeJsonLd()`. `/features` emits `SoftwareApplication` JSON-LD with `featureList` taken from the cards actually rendered on that page. Its `offers` come from the same public `plans` read as `/pricing`, cached for five minutes: one `Offer` per plan and billing interval, with the stored decimal price, row currency, `P1M` or `P1Y` billing duration and a `/pricing` URL. A zero-priced yearly offer is omitted. If the plan read fails, the list is empty or any price or currency is invalid, the entire `offers` property is omitted. The data has no `valueAddedTaxIncluded`, ratings, reviews or logo URL. `apps/web/src/components/seo/json-ld.tsx` escapes `<` before embedding the JSON in a script element. These blocks need a known public origin.

## Share images

The web route `apps/web/src/app/og/[locale]/[[...page]]/route.tsx` serves 1200 × 630 PNGs at `/og/en`, `/og/de` and the `/features`, `/pricing` and `/music` variants. Other web pages use the home banner. The ID route serves one banner per language at `/og/en` or `/og/de`. An unknown locale falls back to English; an unknown web page falls back to home. `buildPageMetadata` puts the active language's image into Open Graph and Twitter metadata when the public origin is known. ID's root layout does the same using `AUTH_URL` as its public origin.

Both apps render the shared `@lumio/ui/og-banner` template using their own localized text, 640 × 552 PNG window captures and static Roboto WOFF files. The web text is under `marketing.og.*`; ID text is under `common.meta.og.*`. The image URLs carry `?v=<product version>` and responses use `Cache-Control: public, max-age=31536000, immutable`. The proxy does not set a language cookie on `/og` responses, so a shared cache cannot replay one visitor's cookie to others. The source files and capture instructions live in each app's `src/app/og/_banner/shots/README.md` and `manifest.json`.

### Lumio Stats share images

Lumio Stats (`apps/stats`) has two image routes. `/og/[locale]/[[...page]]` serves a banner for `/`, `rankings`, `games`, `emotes` and `partners`, plus a `generic` banner without a window. These URLs carry `?v=<stats version>` and are cached as immutable. `/og/channel/[platform]/[platformChannelId]/[locale]` serves a channel card that is drawn from the public card read (`GET /v1/public-stats/channels/{platform}/{platform_channel_id}/card`). The card is keyed by the stable platform id, never by the handle in the page URL. The id must match `^[A-Za-z0-9_-]{1,64}$` in the OG route and in the API: on GraphQL `publicChannelCard` and on the REST card read, any other id gets the same `Invalid platform channel id` validation error (REST 400) before the database is read. One cached read serves both languages, and the response carries `Cache-Control: public, max-age=600, s-maxage=900, stale-while-revalidate=300`.

The channel image contains only the current display name, handle and aggregate
figures. It excludes chatter names, bio, links, team and change history. An
unknown or opted-out channel, a disabled public Stats surface or a card-fetch
error receives the same generic image. Stats share images carry
`X-Robots-Tag: noindex` on the production host; the footer carries the
independent-service platform disclaimer in English and German.

An unknown, opted-out or switched-off channel gets the generic banner, status 200 and `Cache-Control: public, max-age=300, s-maxage=300`. So do an API error, a timeout and a failed render. The bytes are identical in every one of these cases, so the image does not reveal an opt-out. A failed page banner also answers the generic banner with these headers. If even the generic banner cannot be rendered, both routes answer a plain 1200 × 630 PNG with the same status and headers, so neither route ever answers 5xx.

Rendering a PNG takes about 120 ms of server work, so both routes keep rendered images in memory. A page banner is rendered once per language and page; an unknown language, page or query string resolves to one of these. A channel card is kept for 300 seconds per platform, channel id and resolved language, at most 500 cards. The route still reads the card each time from the 300-second data cache, and changed card data, including an opt-out, replaces the kept image at once. A missing figure renders as "—", never as 0. Channel names and categories use only characters that the bundled Roboto subsets (Latin, Latin Extended, Cyrillic, Greek, Vietnamese) can draw. A name with other characters falls back to the login, and in a category those characters are dropped. This way the renderer never fetches fonts at request time.

Every page passes `share` to `buildPageMetadata` in `apps/stats/src/lib/seo.ts`: index pages pass their banner, and the channel, history and stream pages pass the channel card. `/search`, `/watchlist` and the 404 page get the generic banner. On `https://stats.lumio.vision`, `/og/*` responses carry `X-Robots-Tag: noindex`. On every other host they carry the proxy's `noindex, nofollow`, like every other response. `robots.txt` never disallows `/og/`, because X does not show a preview when the image URL is disallowed. Text comes from `og.*` in `apps/stats/messages/{en,de}.json`. The windows, the fonts and the capture instructions are in `apps/stats/src/app/og/_og/`.

## Adding a public page or banner

1. Add the page's `meta.title` and `meta.description` keys in **both** web message catalogs. Use the namespace in its `generateMetadata()` call to `buildPageMetadata`, with the final route path and the appropriate indexing setting. Check the page's canonical and `hreflang` behavior in both languages.
2. For a curated route, add its path to `SITEMAP_ROUTES` in `apps/web/src/app/sitemap.ts`. Legal document routes follow `LEGAL_SLUGS`; music detail routes come from the public song and playlist reads. Keep private and tokenized pages out of the list.
3. For structured data, use `JsonLd` with properties supported by the rendered page and current product facts. Keep the JSON-LD copy in both message catalogs.
4. If the page needs its own banner, add its name to `OG_PAGES` in `apps/web/src/lib/og.ts`, pass `share` to `buildPageMetadata`, add `marketing.og.<page>.title` and `.claim` in both languages, and register each localized PNG in `apps/web/src/app/og/_banner/assets.ts`. Follow `shots/README.md` to refresh the captures and their manifest. The ID app keeps its own single banner and message keys.

Marketing copy for this surface is kept within `marketing.*` (including `marketing.og.*` and `marketing.demos.*`) and `*.meta.*` keys in the web message catalogs, and `*.meta.*` keys in the ID catalogs. The sitemap route array is the curated URL list; changes to marketing copy should not alter unrelated messages or page logic. Review claims against the behavior they describe, especially legal claims about music, plan availability and platform coverage.

`LUMIO_APP_URL` and `AUTH_URL` are listed in [Installation](/getting-started/installation#environment-configuration).

---

## Developer Guide / GraphQL Schema ↔ Proxy Drift Check

Source: https://docs.lumio.vision/developer-guide/graphql-proxy-drift-check

# GraphQL Schema ↔ Proxy Drift Check

A fail-closed CI gate that catches a specific, otherwise-invisible bug class: a
frontend proxy query names a GraphQL **field** the schema does not define
(usually because the schema renamed it). The GraphQL call then fails validation
at runtime, and a `catch → empty state` handler masks the failure as "no data" —
the page renders silently empty, and code review never sees it. This is the class
behind ZAF-724 and ZAF-924.

The check lives in `scripts/check-graphql-proxy-drift.mjs` (pure Node, no
dependencies) and runs as the **GraphQL Proxy Drift** job in
`.github/workflows/ci.yml` on every PR.

## The invariant

> Every GraphQL field referenced in a `query` / `mutation` template literal under
> `apps/{web,admin,id,stats}/src` or `shared/` must exist on the type it is
> selected from in `apps/api/schema.graphql` - at **every depth of the selection
> set**, not just the operation root.

The scan covers proxy route handlers, server-side loaders such as
`apps/web/src/lib/settings/loaders/*` (`serverGqlSSR()` callers), and the shared
API client in `shared/api`. Unit tests are skipped: `__tests__/` directories and
`*.test.ts(x)` / `*.spec.ts(x)` files send deliberately fake operations to mocked
clients. `node_modules/`, `.next/` and `dist/` are skipped too.

The checker resolves the selection tree against the schema: it starts at
`type Query` / `type Mutation`, and for every field that has a sub-selection it
resolves that field's **return type** and checks the nested fields against it,
recursively.

> **Extended in ZAF-1013 (nested fields):**
> The original gate (ZAF-926) only compared **root** field names. That left it
> blind to the far more common drift one selection deeper - e.g. selecting
> `duplicateWidgetInstance { id name }` when `CreateWidgetResult` exposes
> `widget / accessToken / obsUrl`. Every field-level drift catalogued in the
> ZAF-1005 baseline sweep sat below the root and slipped past the root-only check.
> ZAF-1013 walks the full selection tree so the whole class is covered.

## Run it locally

```sh
just graphql-proxy-drift
# or directly:
node scripts/check-graphql-proxy-drift.mjs            # the real check
node scripts/check-graphql-proxy-drift.mjs --self-test # extractor unit tests
```

Exit `0` = clean, `1` = drift detected, `2` = internal/format error.

## Deliberately conservative (false-positives ≈ 0)

The check is scoped narrowly so it never blocks a PR on a query it cannot
statically understand. **A field is flagged only when its parent type is a
`type` we parsed from the schema _and_ the field is absent from it** - anything
unresolvable is skipped, never guessed at:

- **Unresolvable parent ⇒ skipped.** If a field's return type is a scalar, enum,
  input, union base, or a type the parser did not capture, its sub-selection is
  skipped rather than flagged. False-positives stay ≈ 0.
- **Aliases are resolved.** `first: myField` is checked as `myField`, not `first`,
  at the root and at every nested level.
- **Arguments are ignored.** `field(input: { a: 1 })` - including object-valued
  arguments with their own braces - do not disturb the selection walk.
- **Inline fragments switch context.** Fields under `... on Type { … }` are
  checked against `Type`. Plain **fragment spreads** (`...Name`) resolve to a
  definition the static extractor does not follow, so they are skipped.
- **Dynamic queries are skipped.** An operation whose body contains a `${…}`
  template interpolation cannot be statically resolved, so it is skipped whole.
- **Built-in meta fields** (`__typename`, `__schema`, `__type`) are always valid.

## Allowlist escape hatch

`scripts/graphql-proxy-drift-allowlist.json` is the documented escape hatch. Add a
field name here (matched by bare field name, at any depth) **only** when it is a
known, tracked exception the static extractor cannot resolve. Every entry needs a
`reason`.

```json
{
  "allow": [
    { "field": "someComputedAliasField", "kind": "query", "reason": "built via a computed alias the extractor can't see", "trackedBy": "ZAF-1234" }
  ]
}
```

Prefer **fixing the query** (rename it to the canonical schema field) or **fixing
the extractor** over allowlisting. New drift must be fixed, not allowlisted - the
allowlist is for pre-existing/tracked exceptions only.

> **Baseline retired (ZAF-926 → ZAF-942 → ZAF-943):**
> The root-field check shipped with a 14-entry baseline of pre-existing drifts.
> ZAF-942 burned down 12 (7 renamed to the canonical schema field, 4 removed as dead
> consumer-less proxy routes, 1 re-derived), and ZAF-943 cleared the final 2 by
> landing the developer-facing verification resolvers. **The allowlist is now empty
> (`"allow": []`).** New drift must be fixed, not allowlisted. The ZAF-1013
> nested-field extension started from a clean root-field baseline; the field-level
> drifts it surfaces are fixed in the frontend, never allowlisted.

## When you touch a GraphQL query or a resolver name

- Renaming **any** field (root or nested) in the API? Update every frontend proxy
  query that references it - the check will fail the PR otherwise, at whatever
  depth the field is selected.
- Adding a new proxy query? Make sure every field it selects exists on its parent
  type in `apps/api/schema.graphql` (regenerate with `just schemas` after backend
  changes).

## Extending the check

The extractor is intentionally simple. If a real query pattern trips it (a genuine
false positive), the right fix is usually to teach the extractor about that pattern
rather than to allowlist - allowlisting hides real drift on the same field name.
The `--self-test` mode builds a synthetic schema and synthetic drift source
in-memory and asserts the extractor flags an invented field; extend those cases
when you change the extractor.

---

## Developer Guide / Platform Name Drift Check

Source: https://docs.lumio.vision/developer-guide/platform-name-drift-check

# Platform Name Drift Check

A fail-closed CI gate that keeps platform-name rendering on one shared helper. On
a platform with **localized display names** (Twitch's CJK feature) a chatter can
carry a display name like `こさむん` while their login stays the ASCII handle
`kosamun`. The right behaviour — render `こさむん (kosamun)` only when the name
"really looks like that", **and only on a platform where the display name is a
freely-editable field over an immutable login (Twitch today)**, and never on a
normal `Cruex` / `cruex` chatter — lives in one place: `@lumio/ui`'s
`formatPlatformName` / `isLocalizedPlatformName` (ZAF-1452). A hand-rolled
`displayName ?? login` fallback re-introduces the bug this helper fixes: it either
shows the login on every chatter (noise), drops it entirely (loses the handle a
moderator needs), or renders `こさむん (こさむん)` on Kick/YouTube.

The check lives in `scripts/check-platform-name-drift.mjs` (pure Node, no
dependencies) and runs as the **Platform Name Drift** job in
`.github/workflows/ci.yml` on every PR.

## The invariant

> No source file under `apps/{web,admin,stats}/src` may collapse a platform
> display name and its login with a raw `??` / `||` expression
> (`displayName ?? login`, `display_name || username`, and the mirror order).
> Use `@lumio/ui`'s `formatPlatformName({ displayName, login, platform }, t)` for
> the composed string, or `isLocalizedPlatformName(displayName, login, platform)`
> when you only need the decision.

Comparisons (`!==`, `===`), ternaries and helper calls are never flagged — only a
raw `??` / `||` collapse between a display-name token and a login token, in either
order. A member-access prefix on the right operand (`?? user.login`) is tolerated.

**Always pass the source `platform`.** The bracket is gated on a third ANDed
condition (founder ruling ZAF-1452, 2026-09-27): the trigger fires only when
`platform` is on the helper's `LOCALIZED_DISPLAY_NAME_PLATFORMS` allowlist —
**`["twitch"]`** today. An unknown or absent platform is **fail-closed** (no
bracket). This is why the platform must be threaded through: a localized display
name only exists where the platform lets a user edit it independently of the login
(Twitch). On YouTube "channel title ≠ handle" is the *normal* case (ZAF-1478), so
bracketing there would fire on every non-Latin-titled channel — the exact "nicht
bei jedem chatter" the founder rejected. Kick writes one value into both name
fields and is a permanent no-op.

The `decorateLoginForPlatform` `@` prefix (`こさむん (@kosamun)`) is retained in
the helper but currently unreachable: while the allowlist is Twitch-only the
YouTube bracket never triggers. Adding `"youtube"` to the allowlist would restore
it with no other change — the `@` lives **only** in the helper, never in the
stored login (ZAF-1478).

## Why a guard and not just a sweep

Migrating N call sites by hand and hoping the (N+1)-th uses the helper is a
snapshot, not a state. The guard makes "app-wide" a **state**: a new collapse
fails the PR.

## The ratchet allowlist

The pre-existing collapse sites are baselined in
`scripts/platform-name-drift-allowlist.json`, keyed by `{ file, expr }` (the
matched text with internal whitespace collapsed). The guard fails **only** on a
new `{ file, expr }` pair that is not on the baseline; the baseline may only
**shrink**.

- **Migrating a site** (ZAF-1452 sweep tasks): replace the collapse with the
  helper and delete its allowlist entry in the same change.
- **A genuinely out-of-scope site** — machine-consumed login (filter matching,
  `@`-mention insertion, dedupe keys) or a Lumio-account identity that has no
  platform login (ZAF-1452 §D4/§D6) — stays listed with a corrected `reason`.
- **Never** add a new entry to unblock new code. Use the helper.

## Running it locally

```sh
node scripts/check-platform-name-drift.mjs --self-test   # exercise the detector
node scripts/check-platform-name-drift.mjs               # check the tree
```

Exit codes: `0` clean, `1` a new collapse was found, `2` internal/format error.

---

## Developer Guide / Reporting an Issue

Source: https://docs.lumio.vision/developer-guide/reporting-an-issue

# Reporting an Issue

This page describes where each kind of report goes and how a fix travels from
report to production. Use it whenever you find a bug, want to request a feature,
have an idea to discuss, or need to disclose a security vulnerability.

## Overview

Lumio uses a small number of dedicated surfaces so every report lands in exactly
one place and can be tracked to resolution:

- **GitHub Issues** - code-level bug reports and concrete feature requests that
  benefit from sitting next to the code and pull requests.
- **GitHub Discussions** - open-ended ideas, questions, and RFC-style proposals
  that are not yet actionable work.
- **GitHub Security Advisories** - the only correct channel for security
  vulnerabilities. A vulnerability is **never** filed as a regular issue.

Accepted reports are triaged, labelled, and tracked internally through to a fix.

## Where to report

Pick the surface that matches what you found:

| What you have | Where it goes | Notes |
|---|---|---|
| Bug or error | GitHub Issue - **bug report** template | Include steps to reproduce, expected vs. actual behaviour, and the affected app. |
| Concrete feature request | GitHub Issue - **feature request** template | For a well-scoped, buildable change. |
| Open-ended idea, question, or design proposal | GitHub Discussions | Promising ideas are promoted to tracked work. |
| Security vulnerability | **Private** GitHub Security Advisory | See [Security vulnerabilities](#security-vulnerabilities) below - never a public issue. |

The two templates (`.github/ISSUE_TEMPLATE/bug_report.yml` and `feature_request.yml`) prompt for the details maintainers need. Blank issues are **disabled** - every report goes through one of the two templates or through Discussions. Labels (type, priority, status, scope; defined in `.github/labels.yml`) are applied during triage so you can follow progress on the report.

## Security vulnerabilities

> **Warning:**
> Do not report a security vulnerability as a public issue or discussion.

Report vulnerabilities privately through a GitHub Security Advisory, following
the repository's security policy (`SECURITY.md`). Private advisories keep the
details restricted while a fix is prepared and let maintainers coordinate a
release before any disclosure. If you cannot use GitHub Security Advisories,
email **security@lumio.vision** and an advisory is opened on your behalf.

`SECURITY.md` also carries the response targets - acknowledgement within 2
business days, triage within 5, a remediation plan or status update within 10 -
plus the in-scope surface list (every production domain, and the non-production
`lumio.*.staging.zaflun.dev` environments) and what is out of scope (physical
access, social engineering, DoS, unqualified scanner output). Reporters are
credited in the published advisory unless they ask to stay anonymous.

Do **not** include secrets, credentials, or other users' personal data in a
report - describe an exposed credential rather than pasting it.

## How a fix reaches production

Fixes and features move through branches and a versioned release tag. The
environment each stage maps to matches the [Deployment](./deployment.md) and
[Installation](../getting-started/installation.md) guides:

| Stage | Branch / tag | Environment |
|---|---|---|
| Development & integration | `next` | Staging |
| Release preview | `main` | Production preview |
| Release | version tag, e.g. `api@2026.5.3` | Production |

The flow, end to end:

1. **Branch and open a pull request into `next`.** `next` is the
   staging integration branch and the default target for normal fixes and
   features. CI must be green and the change reviewed before it merges.
2. **Promote to `main`.** Once validated on staging, `next` is merged into
   `main`, the production-preview branch.
3. **Cut a release.** Publishing a GitHub **Release** on a tag in the
   `{app}@{version}` format (for example `api@2026.5.3`) triggers
   `release-images.yml`, which builds and pushes the container image. A
   pre-release publishes the `beta` channel tag; a full release publishes
   `latest`. The workflow can also be started manually via `workflow_dispatch`
   with an app selection. See [Deployment](./deployment.md) for the full tag
   reference.

Promotion from `next` to `main` is a maintainer decision, not something a
contributor's pull request does - open every pull request against `next`. An
urgent security fix is the one case where a maintainer may land a change on
`main` ahead of the normal `next` cycle.

## Following updates

Track progress from the surface where you reported:

- **Issues and Discussions** - the thread's labels reflect its status, and
  GitHub notifications alert you to comments and status changes when you
  participate in or watch the thread.
- **Security advisories** - updates are shared privately with the reporter until
  a coordinated release.

See [Contributing](./contributing.md) for local setup and pull-request
conventions.

---

## Developer Guide / Contributing

Source: https://docs.lumio.vision/developer-guide/contributing

# Contributing

Guidelines for contributing to Lumio.

## Getting Started

1. Clone the repository (access required - Lumio is a closed-source project)
2. Set up the dev stack: `just stack-up`
3. Run the API: `just dev-api`
4. Run the web app: `just dev-web`

## Code Style

- **Rust** - Follow `rustfmt.toml` conventions (`just fmt`), pass `clippy` with `-D warnings`
- **TypeScript** - ESLint + double quotes
- **Commits** - Conventional commits format

## Before you push

| Command | What it covers |
|---------|----------------|
| `just verify-all` | `verify-rust` + `lint-ts` + `typecheck-ts` - the fast inner loop |
| `just lint-all` | clippy (`-D warnings`) + ESLint |
| `just test-all` | `test-rust` + `test-v8` + `test-ts` |
| `just verify-release` | `verify-all` **plus** OpenAPI / GraphQL schema and Bazel vendor drift - run before a version-bump or crate-update change |
| `just bazel-build` / `just bazel-test` | the Bazel gates CI runs for Rust - required for any Rust change |
| `pnpm --filter @lumio/<app> build` | the production `next build` CI runs for `web`, `admin`, `id`, `stats` and `shopify` - required for any change under `apps/{web,admin,id,stats,shopify}`; a change under `shared/`, `packages/protocol` or to `pnpm-lock.yaml` builds all five (build `@zaflun/lumio-protocol` first for `web`) |
| `pnpm -r --filter "./packages/**" build` | the `tsup` build CI runs for the public `@zaflun/*` packages under `packages/` - required for any change under `packages/` |

`just verify-all` does not detect schema or vendor drift; only `just verify-release` does.

**Run these one at a time.** Each recipe already uses every core it is given, so a build, a test run, a clippy pass and a format check started in parallel do not finish sooner - they contend for the same CPU and slow each other down (badly so on a shared machine). Run the checks in sequence, cheapest first - `fmt-check`, then lint, then `check` / `typecheck`, then tests, then the Bazel gates - and let each finish before starting the next. Do not background one or start a second alongside it, and leave the job counts the recipes set (`test-rust` pins `CARGO_BUILD_JOBS=2`) alone.

A recipe is sequential in its *dependencies*, but not necessarily in what it spawns: `lint-ts` and `typecheck-ts` expand to `pnpm -r lint` / `pnpm -r typecheck`, and `pnpm -r` runs package scripts about four at a time. On a machine you share, pass `--workspace-concurrency=1` or scope the run with `--filter` to the packages you touched.

**AI coding agents do not use `just` at all.** The recipes are a human convenience layer; an agent runs the underlying command for each step so the steps stay individually visible, reportable and sequential. The recipe-to-command mapping and the reasoning live in `AGENTS.md`, section *Verification - Agents run the tools directly*.

**Cargo green is not Bazel green.** CI builds and tests the Rust workspace with Bazel, which fails on things Cargo never sees - a dependency missing from a hand-written `BUILD.bazel`, a test that reads a fixture off the filesystem instead of embedding it, or `vendor/` drift after a lock change. For any change touching Rust, run `just bazel-build` and `just bazel-test` before you push.

**Typecheck green is not `next build` green.** `tsc` never resolves Next.js file conventions, route manifests, server/client boundaries, the React Compiler or prerendering. The `Next Build` job runs the real production build per affected app - the same build the release image performs - so run `pnpm --filter @lumio/<app> build` locally for any frontend change. It is path-filtered: an app builds when its own directory changed, and a change under `shared/`, `packages/protocol/`, the root manifests or `ci.yml` builds all four.

**Always-dynamic route groups declare themselves.** `serverGqlSSR()` reads the auth cookie, so during the production build's static-generation pass Next throws a `DynamicServerError` (digest `DYNAMIC_SERVER_USAGE`) purely as a signal to bail the route out of prerendering. Our SSR pages wrap their data loads in `try`/`catch` so a failed query renders a visible error instead of an empty success state - and that `catch` swallows the bail-out signal, turning it into a build-time `Failed to load ...: Error: Dynamic server usage` or, silently, into a `notFound()` / `redirect()` fired at build time. The fix lives at the segment root rather than in every `catch`: the always-dynamic route groups in `apps/web` and `apps/admin` export `const dynamic = "force-dynamic"` from their `layout.tsx`, which Next inherits down to every page in the group. It changes no output - those routes were already server-rendered on demand - it only skips a prerender attempt that could never succeed. Add the same line when you introduce a route group whose layout or pages call `serverGqlSSR()`; if a segment genuinely must stay prerenderable, start its `catch` blocks with `unstable_rethrow(err)` from `next/navigation` so Next's own errors pass through.

**Typecheck green is not `tsup` build green either.** The public `@zaflun/*` packages under `packages/` are bundled by `tsup` (entry resolution, export map, `.d.ts` rollup) - none of which `tsc --noEmit` or ESLint exercise, so a broken entry or export only surfaced at `npm publish` time. The `Packages Build` job runs `pnpm -r --filter "./packages/**" build` in dependency order (so `cli` and `sdk` get their built dependencies first); run it locally for any change under `packages/`. It is path-filtered: any `packages/` file, a root manifest, or `ci.yml` arms it.

## Pull Requests

- Create a feature branch off `next` and open the pull request into `next`, the staging integration branch
- **Open every pull request as a draft** (`gh pr create --draft`) and mark it ready for review (`gh pr ready`) only once the work is finished
- Include tests for new functionality
- Update `apps/docs/` in the same change - a code change without matching doc updates is incomplete
- Ensure CI passes and the change is reviewed before it merges

### Why draft first

CI is draft-gated: every job in `.github/workflows/ci.yml` is skipped while a pull request is a draft, so iterating on a draft costs no GitHub Actions minutes. The full pipeline runs when the pull request is marked ready for review, and on every push after that.

Two consequences worth knowing:

- **Verify locally while drafted** - `just verify-all` and `just test-all`, plus `just bazel-build` / `just bazel-test` for a Rust change and `just verify-release` for a version bump or crate update. That is what replaces the per-push CI run, so run all of it before marking the pull request ready, and say in the pull request which checks you ran.
- **A draft's green checks are not evidence.** The `CI Done` aggregate treats skipped jobs as passing, so a draft shows green with nothing run. Only a run triggered by marking the pull request ready - or by a push while it is not a draft - proves anything.

See [Reporting an Issue](./reporting-an-issue.md) for where each kind of report goes and how a fix travels from `next` to production.

## Architecture

See the [Developer Guide](/developer-guide/bot-modules) section for detailed system design documentation.

---

## Features / Chat

Source: https://docs.lumio.vision/features/chat

# Chat

## Overview

The Chat module provides a unified, multi-platform chat system that aggregates messages from Twitch, YouTube, and Kick into a single real-time stream. It supports message history with pagination, moderation actions (bans, timeouts, message deletion), user profiles with enrichment data from a `ProfileService`, moderator notes, emote rendering (Twitch, Kick, 7TV, BTTV, FFZ), polls, predictions, and raid management. Messages are buffered in Redis, flushed to TimescaleDB in batches, and broadcast to all connected WebSocket clients in real time.

## Twitch AutoMod held-message queue

Twitch EventSub `automod.message.hold` and `automod.message.update` supply held messages and outcomes; Helix performs allow and deny with the acting moderator's Twitch login. The channel connection needs `moderator:manage:automod`, so older grants need a reconnect. The live queue is separate from ordinary chat: a held message is published only to `automod:{account_id}` (permission `chat:automod-read`, feature `feature:multichat`) and never enters the chat-message pipeline, overlays or widgets. Allow publishes a separate chat message with a new ID. The queue is available in the dashboard and authorized chat popouts; allow and deny require `chat:automod-allow` and `chat:automod-deny` respectively. The action is written to the chat moderation log; no separate audit event is emitted. When the acting user's stored Twitch login scopes are known and lack `moderator:manage:automod`, allow and deny fail with `error_code: login_scope_missing` before any Helix call; an empty stored scope set counts as unknown and Helix decides, and a Helix 401 maps to the same code. `ConnectionStatus.loginMissingScopes` / `login_missing_scopes` lists the login scopes the acting user's grant lacks, so the UI can ask for a new Twitch login before a click fails.

Each held message carries `emotes` (Twitch emotes and cheermotes, the same shape as a chat message's `emotes`, derived from the EventSub fragments when the message leaves the server and never stored in Redis; absent or `null` when there are none or the fragments were dropped for size) and the sender's `avatar_url`, `color` and `badges`. The look is a snapshot of `platform_users` at hold time, read with a 250 ms timeout, fail-open and never through Helix; it is absent for a chatter Lumio has not seen. Above the 4 KiB Redis entry cap, Lumio drops `fragments` first, then `badges`, then `avatar_url`; `color` and the text stay. 7TV, BTTV and FFZ emotes are matched by word from the channel emote map in the client.

The reason distinguishes `automod`, `blocked_term` and `blocked_link`. Marked offsets are Unicode code-point positions with an inclusive end. The held row renders Twitch emotes and Cheers with their amount, and 7TV/BTTV/FFZ from the channel's emote map. It shows the sender's snapshot avatar, color and badges before the name, respecting the chat's avatar, badge and density settings; if no snapshot exists it uses the sender's latest feed row, then the ordinary no-avatar placeholder without badges. The name opens the regular user card with `chat:userinfo` and stays plain text without it, including after a decision or conflict. The UI renders held links as plain text and shows waiting time when Twitch provides no expiry deadline. In the dashboard, a known missing `moderator:manage:automod` scope on the acting user's login replaces Allow/Deny with **Sign in with Twitch again**; popouts retain the decision buttons and show the error toast after a refused click. Kick has no held-message queue: its AutoMod deletes immediately, and Lumio labels those deletions **Kick AutoMod**. Twitch IRC and the retired PubSub path do not carry this queue. The private [Stream History log](./stream-history.md#automod-log) retains held-message details separately from the live queue. The same log is the third source of the [server-merged history read](#server-merged-history-read-mergedchathistory), so held messages, including resolved ones with their outcome, survive a reload and appear when scrolling back at their original time.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/chat.rs`) -- Queries for chat history, message count, user profiles, emotes, moderation log, and moderator notes. Mutations for sending messages, moderation actions, and CRUD on user notes.
- **Crate** (`crates/lo-chat/src/`) -- Core chat logic including `ChatBuffer` (Redis-backed message buffering), `ChatFilter`/`ChatMessageInput` types, `ProfileService` (caching + circuit breaking for platform API enrichment), emote set types, moderation log, and platform user management.
- **Database** -- Chat messages are stored in TimescaleDB (`platform_chat_messages` hypertable). Platform users are tracked in PostgreSQL (`platform_users`). Moderator notes in `platform_user_notes`. Moderation log entries in `moderation_log`.
- **YouTube Member Badges** -- Custom-tier-badge image URLs are sourced from YouTube's internal InnerTube endpoint (the public Data API does not expose them) and cached in Redis. Inline-enriched into `platform_chat_messages.badges` at INSERT time so chat history scrollback renders correctly. See [Member Badges](./memberships.md) for the full architecture, configuration, and GDPR considerations.
- **Real-time** -- Messages are broadcast via Redis pub/sub to all WebSocket subscribers for the account. The `PendingChatAccounts` state tracks which accounts have buffered messages needing flush.

### Frontend

- Next.js API proxy routes call GraphQL internally; browser hooks use the `/api/chat/*` proxy and keep popout-token support on every fetch.
- Emotes and badges in Multichat, event rows and user-card chat rows open a larger [media card](./emotes.md#chat-emote-and-badge-cards) after desktop hover or a tap on touch devices. A phone uses a bottom sheet. The card resolves cross-channel origin and Kick/YouTube animation through the popout-capable `emoteInfo` proxy; unknown animation shows no chip. Emotes can copy their paste text and ID, while badge cards have no copy controls. The same card works in chat popouts, including OBS; OBS browser sources offer **Copy link** beside external links because they can block popups.
- The Multichat UI renders messages with emotes, badges, colors, reply threading, platform/broadcast filters, keyword tabs, rule colors, per-user highlight colors (each highlighted user carries its own colour - the shared highlight token by default, a custom colour, or switched off to park the entry - edited in a colour dialog opened from the chip's colour button, with a live preview and an explicit Apply/Cancel), notification sounds (per keyword rule, plus one fixed sound for the whole highlighted-user list - a keyword rule's sound wins when a message matches both), and hidden/deleted-message display controls.
- **Localized chatter names surface the login (Twitch).** A chat row, the reply-preview header, and the moderation-confirm dialogs render a chatter's display name on its own. On **Twitch** a viewer can set a display name in a non-Latin script (`こさむん`) that is unrelated to their immutable login (`kosamun`); when that happens the surface renders both as **`こさむん (kosamun)`**, so a moderator still sees the handle to act or search on. An ordinary name is never bracketed: a display name that is only a case-variant of the login (`Cruex` / `cruex`) or an accented Latin name (`Ömer`) renders alone, so the bracket is not noise on every chatter. The trigger is three conditions ANDed - the display name differs from the login case-insensitively, it carries at least one letter outside `Script=Latin`, **and** the platform is Twitch - so Kick/YouTube (where the display name is not an independently editable field) never bracket. The decision is made **at render time** from the `username` + `display_name` columns every message already stores, so it also applies to older history rows after deploy; the composed string is display-only and never persisted. The `@`-mention completion lists and the composed reply body always key on the **raw login**, never the bracketed string. The [User Info Card](../user-guide/chat.md#user-info-card) keeps Twitch's own two-line layout (the localized name as the title, `@login` beneath it) rather than the inline bracket.
- **First-time chatter card (Twitch).** When a viewer sends their first-ever message in a connected Twitch channel, the row renders as the first-time-chatter **spotlight card** (see [Spotlight cards](#spotlight-cards)). It is driven by the `twitch:first_message` event (from the [IRC-tags listener](./connections.md#twitch-irc-tags-listener-connected-channels-only)) correlated to the chat row by message id, so the card appears even when the event arrives just after the message. It shows in the dashboard chat and in a **logged-in** chat pop-out/overlay. A **delegated/shared** chat pop-out (a popout session opened from a shared `lm_pop_*` link) shows it **only when its token was granted `events:read`** - the card rides the `events:{account_id}` stream, which a shared popout subscribes to only under that condition; see [Inline stream events](#inline-stream-events).
- The tab bar (platform + keyword tabs) is a single horizontally-scrolling row: it never wraps to a second line, so a crowded bar or a narrow pop-out costs no chat height. Desktop shows edge arrows and fades only while the row overflows; touch swipes instead. The **+** (new rule) and gear (settings) are anchored outside the scroll area. The active tab scrolls into view on selection and on reload-restore. Keyword tabs are drag-sortable on a mouse (`@dnd-kit`, 5px activation so a click still selects); touch keeps the Filters-list up/down arrows - both persist into the same `keywordTabs` order.
- **User info card** (`apps/web/src/components/info-user-modal.tsx`, sub-components in `apps/web/src/components/user-card/`) is a full-page view on the shared `@lumio/ui` `FullscreenPanel` (platform accent line, platform gradient, `backdrop="blur"`): header with avatar/name/badges/`@username`/ID, then two columns at `lg` and up (a sticky "who" column with profile facts, treatment status and actions; a full-height "what" column with the Messages · Mod notes · Moderation history · Events tabs) and a single column below `lg` and in popout mode. Its moderation confirmation and external-link warning are passed through the panel's `layers` slot so they render inside the panel's portal and stack above it (see [Frontend Overlays](../developer-guide/frontend-overlays.md)); gating is unchanged - the `permissions` prop, `platformSupportsModeration`, the `getChatPermissions` actor-target matrix via `ownBadges`, and the popout session permission subset. The card fetches a unified profile combining DB data with live platform API enrichment. Its message history still shows rows that the feed hides as deleted, so moderators keep audit context. From the chat (not the event feed), it also carries one-click **Highlight** / **Hide** buttons that write the same name-based, cross-platform rule as the Filters tab via the shared `@lumio/chat-filters` toggle helpers (`toggleHighlightUser` is three-valued - add / switch a parked entry back on / remove - so a second click never stacks a duplicate); the buttons are prop-gated on a filters setter, so the event-feed variant of the card never offers a folgenlos toggle.
- Chat filters and keyword tabs live in `localStorage` with an account-scoped key plus an unscoped mirror for token popouts; the shared `@lumio/chat-filters` matcher keeps dashboard and popout behavior identical. A `storage`-event listener re-reads the filter/tab keys when another document writes them, so a Highlight/Hide toggle made in the OBS popout reaches the dashboard tab (and vice-versa) without a reload.
- **Reconnect notices before a send fails.** When a grant the Multichat send path depends on can no longer be refreshed - the `reconnect_required` state the dashboard shows as **Neuverbindung erforderlich** - the Multichat shows it in its [connection notices](./connections.md#connection-notices) under the topbar before a send fails at the provider. **Two sources, two entries:** the platform's **channel** connection (`connectionStatuses.reconnectRequired`) and the acting user's **personal login grant** (`connectionStatuses.loginReconnectRequired`, ZAF-1045) - the send actually uses the login grant (the founder's `aead::Error` case). Both appear as separate entries because they are repaired in different places: the **login** entry routes to [Account → Profile](../user-guide/connections.md), the **channel** entry starts the OAuth flow in place for viewers holding `connections:create`, and for everyone else links to the [connections page](../user-guide/connections.md). Login entries appear only for platforms the user can actually send on (the active account has the platform's channel connection **and** a login of the user for it is assigned to the account, the rule that decides which send toggles are shown) and only with `chat:write`; a viewer without `connections:create` (a Moderator) keeps the channel entry exactly for those sendable platforms. The affected platform's send toggle is disabled (with a reconnect tooltip) and dropped from the active send set, so no message is dispatched to a grant that would 401. A delegated pop-out guest (token session, not a first-party user) sees the entries without a button, and never the login-assignment notice. With the pop-out header hidden but the input visible, only these send-relevant entries appear, compactly, above the input; header and input both hidden ⇒ none. The notices sit in the normal layout flow, and the feed keeps a bottom-stuck reader at the newest message (and a scrolled-up reader on their line) while they change height.
- **Failed-send messages are translated, never raw.** A rejected send now carries a machine-readable `errorCode` (`login_reconnect_required` \| `internal_error` \| `send_failed`) on both `sendChatToPlatform` (GraphQL) and `POST /v1/chat/send` (REST). The failed-send banner renders a **translated** line off that code - the `login_reconnect_required` code is always a dead personal **login** grant, so it shows the login-specific reconnect line and a **Jetzt neu verbinden** button that opens **Account → Profile**; `send_failed` (the platform refused the message) shows "{platform} rejected the message."; `internal_error` shows "Lumio could not send the message - please try again." Both arrive as HTTP 200 with `sent: false`, so they carry no status suffix. An unrecognised or absent code shows only "Send failed (status)". The raw backend error chain (crypto/DB internals such as `aead::Error`) is never rendered in the UI (ZAF-1047, ZAF-1048, ZAF-1627).
- The alert box (hype train, ad break, poll, prediction, outgoing raid) is event-sourced through one pure reducer (`applyAlertEvent`) and persisted across refreshes by two layers. **Layer A** writes the five card slots plus a `dismissed` registry to `localStorage` (`lumio:chat-alerts`, same account-scoped-key + unscoped-mirror Pattern-B storage as the filters). On mount it reconciles every slot against the wall clock - countdowns are absolute epoch-ms deadlines, so an ad break/raid resumes with the correct remaining time, an alert whose end already passed returns **ended** (with its wind-down window) or is dropped, and anything past its age limit (prediction locked 30 min; hype train / YouTube poll 15 min) is discarded, never shown as running. **Layer B** is a server replay of the last 30 minutes of Twitch event history via `GET /api/events`, gated client-side on `events:read` (so a token dock without that scope never fires the request) and fail-soft (a `502`/empty result is additive-only and can never blank Layer A). One merge reconciles both sources: Layer A is the source of truth for live values, Layer B for existence and end - so an alert whose *end* the browser missed is restored **ended** with the last live numbers. A dismissed card is filtered out of both sources and the dismiss propagates cross-tab through the same `storage` listener as the filters. A restored card renders identically to a live one - the alert box carries no restored/stale badge.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `chatHistory(filter: ChatFilterInput)` | `chat:read` | Paginated chat message history with filters for platform, user, date range, keyword `search`, and YouTube `liveChatId` (broadcast-level). Without `from` it reads the 30 days before `to` (or now); `total` is capped at 10 000 (`totalCapped: true` = more match) — see [Bounded list reads](#bounded-list-reads) |
| `mergedChatHistory(filter: MergedChatHistoryFilterInput): ChatHistoryPage!` | `chat:read` and/or `events:read`, plus `chat:automod-read` for AutoMod rows (per-source, see below) | **Server-merged messages + events + AutoMod holds** timeline: one `created_at`-ordered, keyset-paged page for the multichat history view (see [Inline stream events](#inline-stream-events)) |
| `platformUserProfile(platform, platformUserId)` | `chat:userinfo` | Unified user profile with platform API enrichment via `ProfileService` |
| `searchPlatformUsers(query, platforms, limit)` | `chat:userinfo` | Prefix-search the account's known chatters by username/display name for the filter name-completion (min 2 chars, else empty; capped at 25) |
| `emotes(platform, channelId)` | `chat:read` | Emote sets for a platform/channel (7TV, BTTV, FFZ, YouTube native, Kick native) |
| `userEmotes` | `chat:read` | Twitch emotes available to the authenticated user (subs, globals, follower) |
| `emoteInfo(platform, items)` | Authenticated (sessions, API/service/developer keys, popout tokens, System keys; overlay/widget/extension tokens refused); no RBAC permission | Owner details and Kick/YouTube animation for up to 50 emotes (see [GraphQL reference](../api-reference/graphql.md#emoteinfo)) |
| `platformUserNotes(platform, platformUserId)` | `chat:notes` | List moderator notes for a platform user |
| `moderationLog(platform, platformUserId, page, limit)` | `chat:userinfo` | Moderation action history for a user |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `sendChatMessage(input: ChatMessageInputGql!)` | System key with `bots:internal` + `feature:multichat` for `input.accountId` | Bot-fleet ingest: buffer a chat message in Redis and broadcast via pub/sub. `accountId` is required (`account_id is required`); tenant credentials cannot call it (ZAF-1922) |
| `sendChatToPlatform(input: SendToPlatformInput!)` | `chat:write` | Send a chat message to a platform (twitch, youtube, kick). The message is authored by the **logged-in user's** platform identity (their Twitch/Google login), so they need a login connection for the target provider. The target chat is the **broadcaster's** stream - for YouTube the active `liveChatId` is read from the polling worker's Redis cache (same source as `youtubeActiveStreams`), so invited members can post even though they themselves have no active stream. Resolution prefers a currently-`live` broadcast; when nothing is live yet it falls back to the open **waiting-room chat** of a scheduled (`upcoming`) broadcast, so bots and commands can respond in the pre-stream chat that the worker already reads. With multiple concurrent broadcasts (of the same status) the caller must pass `liveChatId` to choose which one to post to. |
| `createPlatformUserNote(platform, platformUserId, note)` | `chat:notes` | Create a moderator note on a user |
| `updatePlatformUserNote(noteId, note)` | `chat:notes` | Update an existing moderator note |
| `deletePlatformUserNote(noteId)` | `chat:notes` | Delete a moderator note |
| `updateUserTreatment(platform, platformUserId, treatment)` | `chat:ban` | Update chat user treatment (`none`, `active_monitoring`, `restricted`); Twitch syncs to Helix best-effort |
| `moderateChat(input: ModerationInput!)` | `chat:ban` / `chat:timeout` / `chat:delete` | Perform a moderation action (ban, timeout, delete) on Twitch, YouTube, or Kick. Permission checked per action type. YouTube auto-resolves the active `liveChatId` from the polling worker's Redis cache when not supplied. After a successful ban/timeout the server soft-deletes the affected user's messages of the last 24 hours (see [Ban / Timeout Sweep](#ban--timeout-sweep-chatclear_user)) and broadcasts a `chat:clear_user` WebSocket event so all connected clients grey those messages out - same UX as the platform's native chat. All three platforms support delete + timeout + ban; Kick goes through its official public API. The action runs on the moderator's **login** token, which is refreshed on demand. When an action is refused the mutation returns `success: false` with a human-readable `details` reason and a stable `errorCode` (`login_scope_missing`, `login_reconnect_required`, `moderation_forbidden`, `moderation_failed`, `internal_error`) as HTTP 200, not an error. The client surfaces the translated reason and leaves the user's messages untouched. See [GraphQL → moderateChat](../api-reference/graphql.md#moderatechatinput-moderationinput-gqlmoderationresult). |
| `cancelRaid` | `chat:raid` | Cancel a pending Twitch raid |
| `endPoll(pollId, status?)` | `chat:poll` | End an active Twitch poll (`status` defaults to `TERMINATED`). Acts as the **channel**: it uses the broadcaster token of the account's Twitch channel connection (refreshed on demand), never the caller's login, so moderators and service keys can end polls. Shares one implementation with `DELETE /v1/chat/poll` (`services::twitch_channel_actions`) - same guard, same errors |
| `endPrediction(predictionId, status, winningOutcomeId?)` | `chat:prediction` | End/cancel a Twitch prediction (`RESOLVED` requires `winningOutcomeId`). Acts as the **channel** like `endPoll`, sharing one implementation with `DELETE /v1/chat/prediction` |
| `refreshPlatformUserProfile(platform: String!, platformUserId: String!)` | `chat:refresh_user` | Force a `ProfileService` re-enrichment for one platform user, bypassing the Redis cache. Rate-limited to once per 10 minutes per user via a Redis `SETNX`. |

Every chat query and mutation additionally requires the `feature:multichat`
feature flag; the GraphQL guards combine `FeatureGuard("feature:multichat")`
with the permission above, and the REST handlers call the same
`require_feature`. `moderateChat` is the one exception to the guard shape: its
declared guard is `AuthGuard + FeatureGuard`, because the required permission
(`chat:ban` / `chat:timeout` / `chat:delete`) depends on the action in the
input and is therefore resolved inside the resolver.

### Sending: result shape and reconnect signalling

`sendChatToPlatform` and `POST /v1/chat/send` author the message with the
**logged-in user's personal login grant** for the platform (twitch→twitch,
youtube→google, kick→kick) - *not* the account's channel
connection. That grant is acquired through the central refresh chokepoint, so an
expired-but-refreshable token is refreshed transparently before sending; a grant
that can no longer be used is flagged `reconnect_required` and reported as a
typed signal.

Both protocols call one service, `services::chat_send::send_to_platform`
(`apps/api/src/services/chat_send.rs`): it checks the channel connection,
acquires the login grant, dispatches to the platform and returns either a hard
refusal (no channel connection, unsupported platform, no login connection,
missing Twitch client id, database error - each protocol keeps its own error
text) or a send outcome with the `errorCode` below.

The send result carries a machine-readable `errorCode` (`error_code` on REST) so
the client renders a **translated** message instead of parsing backend strings.
Both protocols return the identical shape, codes and `platform`, as HTTP 200 in
every case below (only a hard validation error - unsupported platform, no channel
connection - is a protocol error):

| `errorCode` | Meaning |
|-------------|---------|
| _absent_ (`sent: true`) | Sent; `messageId` is set when the platform returns one. |
| `login_reconnect_required` | The user's personal login grant is dead - undecryptable ciphertext, already flagged, or expired with no refresh token. The connection is flagged `reconnect_required` and the user must reconnect that login. **No** crypto/DB internals are ever returned in `error`. |
| `internal_error` | An internal failure reading the credential; the human-readable `error` is scrubbed and the cause is logged, never shipped. |
| `send_failed` | The platform rejected the send (slow-mode, ban, invalid content, …); `error` carries the platform's message. |

A dead login grant also surfaces on the connection-status read model as
`loginReconnectRequired` (see [Connections](./connections.md#login-grant-health)),
so the Multichat can warn **before** the first send attempt.

### REST Endpoints

All paths live under `/v1`. Bodies are snake_case and mirror the GraphQL inputs.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/chat/history` | `chat:read` | Paginated chat history (filter by platform, user, date, keyword `search`, YouTube `live_chat_id`) |
| `GET` | `/v1/chat/history/merged` | `chat:read` and/or `events:read`, plus `chat:automod-read` for AutoMod rows (per-source) | Server-merged messages + events + AutoMod holds, one keyset-paged timeline page (see [Inline stream events](#inline-stream-events)) |
| `POST` | `/v1/chat/message` | System key with `bots:internal` + `feature:multichat` for body `account_id` | Bot-fleet ingest/buffer of a message; `account_id` required (ZAF-1922) |
| `POST` | `/v1/chat/send` | `chat:write` | Send a chat message to a connected platform |
| `POST` | `/v1/chat/moderate` | `chat:ban` / `chat:timeout` / `chat:delete` | Ban, timeout, or delete on twitch / youtube / kick (permission resolved per action). Mirrors the GraphQL `moderateChat` mutation 1:1 - same fields, same auto-resolve of `live_chat_id` for YouTube, same `chat:clear_user` broadcast on ban/timeout, same `error_code`. Both twins call one shared implementation (`services::chat_moderation::moderate`). |
| `DELETE` | `/v1/chat/raid` | `chat:raid` | Cancel the current Twitch raid |
| `DELETE` | `/v1/chat/poll` | `chat:poll` | End the current Twitch poll. Runs on the channel's broadcaster token; mirrors GraphQL `endPoll` 1:1 |
| `DELETE` | `/v1/chat/prediction` | `chat:prediction` | Lock/resolve the current Twitch prediction. Runs on the channel's broadcaster token; mirrors GraphQL `endPrediction` 1:1 |
| `GET` | `/v1/chat/users/search` | `chat:userinfo` | Prefix-search known chatters by username/display name for the filter name-completion. `?q=` (min 2 chars, else empty), optional `?platform=` (comma-separated), `?limit=` (capped at 25). Mirrors GraphQL `searchPlatformUsers` 1:1. |
| `GET` | `/v1/chat/users/{platform}/{platform_user_id}` | `chat:userinfo` | Unified user profile (DB + enrichment) |
| `GET` | `/v1/chat/users/{platform}/{platform_user_id}/moderation-log` | `chat:userinfo` | Moderation action history |
| `GET` | `/v1/chat/users/{platform}/{platform_user_id}/notes` | `chat:notes` | List moderator notes |
| `POST` | `/v1/chat/users/{platform}/{platform_user_id}/notes` | `chat:notes` | Create a moderator note |
| `PATCH` | `/v1/chat/users/{platform}/{platform_user_id}/notes/{note_id}` | `chat:notes` | Update a moderator note |
| `DELETE` | `/v1/chat/users/{platform}/{platform_user_id}/notes/{note_id}` | `chat:notes` | Delete a moderator note |
| `PUT` | `/v1/chat/users/{platform}/{platform_user_id}/treatment` | `chat:ban` | Set user treatment (`none`, `active_monitoring`, `restricted`) |
| `POST` | `/v1/chat/users/{platform}/{platform_user_id}/refresh` | `chat:refresh_user` | Force-refresh the enriched profile, bypassing the cache. Mirrors GraphQL `refreshPlatformUserProfile` 1:1, including the 10-minute per-user rate limit. |

### WebSocket

| Channel | Gate | Feature flag |
|---------|------|--------------|
| `chat:{account_id}` | `chat:read` on the account in the channel key | `feature:multichat` |

The channel carries the live message stream plus the moderation side-events:
`chat:message`, `chat:delete`, `chat:clear_user`, `chat:moderation_log`, and
`chat:user_treatment_update`. The feature flag is enforced at subscribe time —
without `feature:multichat` a crafted `chat:{account_id}` subscription is
rejected, matching the REST/GraphQL gate.

### Bounded list reads

`chatHistory` and `GET /v1/chat/history` always read a bounded time range: the supplied `from`, else 12 hours for a keyword `search`, else the 30 days before `to` (or now). Chat is kept for up to 1 095 days, and an unbounded read would scan the account's whole history on every page. Pass an explicit `from` to page further back. `mergedChatHistory` keeps its own keyset walk window.

`total` is a count capped at 10 000. When more messages match, `total` is `10000` and `totalCapped` (REST: `_meta.total_capped`) is `true`, shown as "10 000+". `pages` covers the capped total, and a page past it is empty. GraphQL counts only when `total`, `totalCapped` or `pages` is selected. The same rules apply to `events` / `GET /v1/events` ([Events](./events.md)). There is no whole-account message-count endpoint.

### Keyword search

`chatHistory` accepts a keyword `search` filter so a keyword tab can pull older matches from TimescaleDB instead of only what is left in the in-browser buffer. It is exposed as `ChatFilterInput.search` (GraphQL, `[String!]`) and as the comma-separated `search` query parameter on `GET /v1/chat/history` (REST, e.g. `?search=hello,world`). A message is a **candidate** when its body contains any of the keywords (case-insensitive substring). The server predicate is a coarse `message ILIKE`-any-keyword - a deliberate superset of the shared `@lumio/chat-filters` matcher, which the client re-checks so live and back-loaded messages judge identically.

- **Always time-bounded.** A keyword search never scans the whole hypertable: it always carries a lower time bound - the caller's `from` when supplied, otherwise the last 12 hours. Plain (non-search) history queries default to the 30 days before `to` (or now) instead ([Bounded list reads](#bounded-list-reads)). Because a keyword search is capped to a window and the daily retention sweep bounds the data, "no older matches in the window" is an expected, ordinary end state.
- **Bounded input.** At most 20 keywords, each at most 100 characters (after trimming and dropping blanks). A violation returns `400 BAD_REQUEST` with the **identical** message on GraphQL and REST - the shared `lo_chat::validate_search_terms` backs both. Wildcard metacharacters (`%`, `_`) inside a keyword match literally. REST splits the single `search` query parameter on commas, so a keyword that itself contains a comma cannot be expressed through REST; use GraphQL `ChatFilterInput.search: [String!]` for comma-containing keywords.
- **No new permission or flag.** `search` only narrows the existing history surface, which is already gated on `chat:read` + `feature:multichat`.

The client side (`useMultichat` / `Multichat`) drives this window:

- **Per-tab paging.** `loadMore` runs in two modes: for a keyword tab it pages the keyword `search` window (`from` seeded once at 12 h on first open); otherwise it pages the general history. Paging state (`page` / `hasMore`) is kept per view so one tab never inherits another's exhausted end.
- **Capped follow-on.** A candidate page can yield zero *visible* rows (the server pre-filter is a superset of the matcher). The infinite-scroll keeps loading - hard-capped at 5 pages per trigger - until a row matches or the window is exhausted, so a keyword with no recent hits never loops. Back-loaded rows are tagged `__source: "history"` (client-only) and merged by `created_at` with dedupe on `platform_message_id ?? id`, keeping the list chronological and duplicate-free. Both merge modes trim **only from the oldest end** — never the newest (see below).
- **A scroll-up never deletes the newest rows; rendering is scroll-independent (ZAF-1529 / ZAF-1530 / ZAF-1533).** Founder invariant: *"Neuste nachrichten sollten nie gelöscht werden."* Paging older history grows the buffer to keep **both** ends. `mergeOlderMessages` trims **only from the oldest end**, keeping the newest `MAX_HISTORY_MESSAGES = 5000` — an order of magnitude above the `MAX_MESSAGES = 500` live-tail cap — so a normal scroll-up simply grows the buffer and the trim bites only at that documented memory ceiling (~50 scroll-up pages), never mid-scrollback. The earlier `slice(0, max)` did the opposite (kept the oldest, dropped the newest overflow); from the 5th scroll-up page on it deleted exactly the history the reader had just scrolled past, which also shrank `scrollHeight` and grew the scrollbar thumb — the ZAF-248 (`04abe689`, 2026-08-04) regression this reverses. What renders is a pure function of the loaded data, never of the scroll position: scrolling can neither add nor remove a line. The live-append path (`addMessage`, via `trimLiveTail`) trims the oldest back only once the reader is at the live end — to `MAX_MESSAGES` for a **fresh** buffer, but to `MAX_HISTORY_MESSAGES` once a scroll-up has grown it (`bufferGrownRef`), so returning to the present and then receiving a live message never snaps the paged history back out (ZAF-1538). **Jump-to-bottom does not reload the window**: the buffer already holds the live tail *and* the older history the reader paged in, so re-loading a 500-row window there would only discard that history (the founder's ZAF-1538 report). It instead calls `fillGap` (throttled, deduped, never discards a row — see [Gap-fill](#gap-fill-closing-the-span-between-history-and-the-live-tail)) to pull any message caught in the ~5 s write-buffer flush lag without dropping anything. Only mount and a server-side filter change reload the newest window (`loadLatestWindow` → `mergeLatestWindow`, which keeps any live message that landed during the fetch and resets the buffer to the 500-row window), because there discarding the previous view's rows is correct.
- **Following the live end is tied to reader intent, not to a pixel zone (ZAF-1408 / ZAF-1647).** Multichat keeps the feed glued to the newest line through a *bottom-stick* window: armed by every deliberate end-landing (mount, filter or tab switch to the end, the jump-to-bottom button, *Page Down*) and by the reader scrolling **down** until they reach the **true end** (`AT_END_PX = 2` px, `interpretReaderScroll` in `lib/chat-display.ts`). While armed, content growth (live tail, event back-fill, late avatars/embeds via a `ResizeObserver`) re-pins to the bottom. Any reader gesture away from the end (`wheel`, `touchmove`, *Arrow Up* / *Page Up* / *Home*) disarms it, and any **upward** movement - however small - marks the reader as scrolled up, so the 100-px near-bottom zone (`NEAR_BOTTOM_PX`) no longer re-pins on live growth (`shouldStickToBottom`). That zone drives only the UI: the jump bar, live-end buffer trimming and the load-older gate. A single wheel notch up (~100 px in Chromium, ~3 lines in Firefox) therefore stays put; scrolling back down to the end glues again without a `loadMore`.
- **The inline event ring falls under the same invariant.** `mergeEventBatch` (`use-chat-events.ts`) never evacuates the newest events: it keeps every **reachable** event (`created_at >= floorAt`, the oldest buffered message — the interleaved + live-tail region) up to `MAX_HISTORY_EVENTS = 5000`, and drops **below-floor** events (older than the oldest loaded message) unconditionally once over the cap — the server-merged cursor re-fetches them together with their messages when the reader pages that window in (ZAF-1535). Dropping them, rather than the old "keep the freshest below-floor to fill headroom", is what couples the ring to the message span: a live-tail trim that raises `floorAt` sheds the now-orphaned event lines instead of the ring hoarding thousands of them (the 500-message-vs-5000-event divergence). The window is a pure function of the loaded data, never of scroll position. **At the start of history the floor lifts** (ZAF-2329): once the view has no older page left (`hasMore === false`) and the buffer still holds its oldest message, the events before the first message are the real start of the chat, so the ring keeps them as reachable instead of dropping them.
- **Reliable end state.** The BFF (`/api/chat/history`) passes the GraphQL `total` / `page` / `pages` through, so `hasMore` is read from `page < pages` rather than guessed from the page length; a failed first fetch leaves paging retryable instead of permanently off.

### Name completion (`searchPlatformUsers`)

The *Hidden users* and *Highlighted users* filter lists offer an `@`-completion bound to the account's real chatter base - the `platform_users` table, which the chat flush updates for every sender (see [Chatter tally](#chatter-tally-platform_users-write-cadence)). `searchPlatformUsers` (GraphQL) and `GET /v1/chat/users/search` (REST) back it, returning the slim `{ platform, platformUserId, username, displayName, avatarUrl, lastSeenAt, messageCount }` shape.

- **Prefix match, both name columns.** Case-insensitive prefix (`prefix%`) on **`username`** and **`display_name`**. `%`, `_`, and `\` in the query match literally (the same escaping as member search). Ordered `last_seen_at DESC, message_count DESC` - whoever wrote most recently ranks first.
- **Minimum two characters.** A query shorter than 2 characters (after trimming) returns an **empty list, not an error** - the UI queries on every keystroke. `platforms` (GraphQL `[String!]`, REST comma-separated `?platform=`) restricts the platforms; omit for all. `limit` is hard-capped at **25** regardless of the requested value.
- **Same guard as the profile query.** `feature:multichat` + `chat:userinfo`, identical to `platformUserProfile`, so the completion never surfaces a user the caller could not already inspect - and without `chat:userinfo` the search returns nothing (no data leak). The account is always derived server-side from the (cookie or popout) token, never from a client parameter, so a popout with `?token=lm_pop_*` gets results without sending an account id.
- **Indexed prefix.** Backed by `(account_id, lower(username) text_pattern_ops)` and the matching `display_name` index (`20260805000001_platform_users_search_prefix_index`) so a per-keystroke prefix lookup range-scans instead of full-scanning the monotonically growing, never-pruned table. The predicate uses `lower(col) LIKE …` (not `ILIKE`) to match the index expressions exactly.
- **All chat platforms populate it.** Twitch, YouTube, and Kick all record their senders in the chatter tally, so a chatter on any platform appears in the completion within one flush tick (≈ 5 s) of their first message.

## Chat badges — where they come from

Every chat message and every chatter in the user card carries a `badges` array in one shared shape, whatever the platform:

```json
[{ "set_id": "moderator", "id": "1", "image_url": null, "info": "Moderator" }]
```

`set_id` names the badge (`broadcaster`, `moderator`, `subscriber`, `vip`, …), `id` is its version or tier, `image_url` is the platform's artwork when it is known, and `info` is free text (Twitch sub months, Kick badge label). Twitch badges add `title`, Twitch's readable English name for the badge version (`Gold Pixel Heart`, `25 Gift Subs`). Kick badges add `count` (subscription months, gifted subs). YouTube member badges add `tier_name`, `duration_value` and `duration_unit`. Next to the array, each message and user carries the role flags `is_mod`, `is_sub` and `is_vip`, derived from the same badges.

### Twitch

| Step | Current behaviour |
|------|-------------------|
| Source | EventSub `channel.chat.message` `badges[]` (`set_id`, `id`, `info`). |
| Image URLs and titles | Resolved from the worker's badge cache (global and channel badges, loaded from Helix when the worker starts; a channel badge wins over a global one with the same `set_id` and `id`). The cache holds each version's image and its Helix `title`. |
| Normalisation | Passed through unchanged plus `image_url` and `title`. `title` is stored with the message as it was at that moment and is left out when Twitch sends none; messages stored before titles were recorded have no `title`. The `twitch:watch_streak` event's `badges` use the same cache and shape. `is_mod` = `moderator`, `lead_moderator` or `broadcaster`; `is_sub` = `subscriber`; `is_vip` = `vip`. |

### YouTube

| Step | Current behaviour |
|------|-------------------|
| Source | InnerTube author flags (owner, moderator, member) and author badges. |
| Image URLs | Only for the member badge: its artwork and tier come from the InnerTube badge or the membership badge cache (see [Channel Memberships](./memberships.md)). Broadcaster and moderator have no image URL. |
| Normalisation | One entry per flag: `broadcaster`, `moderator`, and `subscriber` (members, enriched with `image_url`, `tier_name`, duration and `info` = months when the cache knows the tier). |

### Kick

| Step | Current behaviour |
|------|-------------------|
| Source | `chat.message.sent` webhook, `sender.identity.badges[]` (`type`, `text`, `count`) and `sender.is_verified`. |
| Image URLs | Kick sends no badge artwork. Two caches fill it in, both from **undocumented** kick.com endpoints (see below): the channel's **sub-badge** images and the chatter's selected **global** badges (level, founder …). Role badges (broadcaster, moderator, VIP, OG, verified, sub gifter …) have no image anywhere and render from built-in icons. |
| Normalisation | Each badge becomes `{set_id, id, info, count?, image_url?}`: `set_id` = Kick `type`, `info` = Kick `text`, `count` = Kick's number (subscription months, gifted subs), `id` = the tier (below). `sender.is_verified` adds a `verified` badge. |

| Kick `type` | `set_id` | `id` | Flag |
|-------------|----------|------|------|
| `broadcaster` | `broadcaster` | `"1"` | `is_mod` |
| `moderator` | `moderator` | `"1"` | `is_mod` |
| `subscriber` | `subscriber` | the chosen sub-badge tier's months (without a tier cache: `count`) | `is_sub` |
| `sub_gifter` | `sub_gifter` | `count` (gifted subs) | — (gifting is not subscribing) |
| `vip` | `vip` | `"1"` | `is_vip` |
| global badge (selected by the user) | `level`, or the badge name (e.g. `kick_founder22`) | the level (`level` only), else `"1"` | — |
| anything else (e.g. `og`, `verified`, `staff`) | passed through unchanged | `count` or `"1"` | — |

**Sub-badge images, per channel.** `https://kick.com/api/v2/channels/{slug}` →
`subscriber_badges[{months, badge_image.src}]`, cached in Redis for 6 h. For a
subscriber with `count` months the highest tier with `months ≤ count` is chosen:
its months become `id` and its image is frozen into `image_url` on the stored
message.

**Global badges, per user.** `https://kick.com/api/v2/channels/{channel_slug}/users/{user_slug}`
(`user_slug` = the webhook's `sender.channel_slug`) → `badges_v2`, keeping only
the entries the user chose to show (`selected: true`): name, `image_url` on
`ext.cdn.kick.com` and `metadata.level`. The level is Kick's global watch time,
so the cache is keyed by user and kept 4 h. A level badge adds
`{set_id: "level", id: "<level>", info: "Level <level>", image_url}`; if Kick
itself sent a badge of the same type, that badge only gains the image.

**Ingest never waits for either cache.** It only reads Redis. On a miss it
schedules a background fetch and the message goes out without the image or the
global badge, so a chatter's first message in a cache period can lack their
level badge. Fetches are de-duplicated across API replicas with a Redis lock
(which also spaces out retries after a failure), limited to 4 in flight per
process (a burst beyond that is skipped, not queued), and stopped for 5 minutes
by a circuit breaker after 5 failures in a minute. Both endpoints have no
contract and sit behind Cloudflare: when they fail or change shape, only the
images and global badges disappear — chat, role badges and history are
unaffected. Metrics: `chat_sub_badge_fetch_total`, `chat_identity_badge_fetch_total`
and `chat_identity_badge_cache_total`, labelled only by `platform` and `outcome`.

**Kick message text, replies and decode failures.** Kick emotes arrive as
`[emote:ID:NAME]` markers inside `content`; the stored message is plain text
plus one `emotes` entry per occurrence (see [Emotes → Kick chat emotes](./emotes.md#kick-chat-emotes)).
A reply stores the parent's id in `reply_parent_msg_id` when it is a UUID — Kick's
Chat API types message ids as `format: uuid` — and leaves it `NULL` otherwise; the
parent's text in `reply_parent_message` is plain text too. A
`chat.message.sent` payload that does not decode is still answered with `200`
(Kick disables a subscription only for an app that stops answering), but it is
logged at `warn` and counted in `chat_ingest_failures_total{platform="kick",
outcome="decode_error"}` instead of disappearing silently.

### Storage

| Where | Database | Holds | Read by |
|-------|----------|-------|---------|
| `platform_chat_messages.badges` | TimescaleDB | The badges as they were on that message. | Live chat (WebSocket `chat:message`), chat history. |
| `platform_users.badges` | PostgreSQL | The latest known badges of the chatter, overwritten by every chat message. | User card: GraphQL `platformUserProfile` and REST `GET /v1/chat/users/{platform}/{platform_user_id}`. |

`platform_users.badges` is merged with `COALESCE`, so a write without badge data keeps the stored value. Moderation events (bans, timeouts) carry no badge data and never touch it. A chat message whose sender has no badges writes `[]`, so a demoted moderator loses the badge on their next message. On Kick, only a webhook without any `identity` counts as "no badge data". A message row stores `null` instead of `[]` when there are no badges, which renders the same. The user card goes through `ProfileService`, which caches an enriched profile for up to 4 hours, so a badge change can take that long to show there.

### Rendering

`apps/web/src/components/chat-badges.tsx` renders the array in chat rows and the user card:

1. `image_url` wins (Twitch badges, YouTube member badges, Kick sub badges and Kick global badges such as the level badge).
2. A `level` badge without an image renders a green plaque showing the level number.
3. Otherwise a per-platform built-in icon, if one exists for that `set_id`. Kick has one for every role badge: `broadcaster`, `moderator`, `subscriber` (used when the channel's sub-badge image is unknown), `sub_gifter`, `vip`, `og`, `verified`, `staff`, `sidekick` and `bot`. The broadcaster, moderator and VIP icons are Kick's own `HostBadge`, `ModeratorBadge` and `VIPBadge` artwork, rendered verbatim at the same size as every other badge. The others are Lumio's own artwork, drawn as a coloured plaque with one glyph.
4. Otherwise the generic built-in SVG for the `set_id` (`broadcaster`, `moderator`, `lead_moderator`, `subscriber`, `vip`).
5. Otherwise a `•` placeholder.

**Tooltip and accessible name.** Every badge carries a tooltip, which is also its `alt` text or `aria-label`. It never shows a raw badge ID; the first rule that applies wins:

1. **Standard badge** — a translated label from `chat.badge.*` (`en`/`de`). Twitch and Kick spell some IDs differently; both map to the same label:

   | Label (en / de) | Twitch `set_id` | Kick `set_id` |
   |-----------------|-----------------|---------------|
   | Broadcaster / Streamer | `broadcaster` | `broadcaster` |
   | Moderator / Moderator | `moderator` | `moderator` |
   | Lead Moderator / Lead-Moderator | `lead_moderator` | – |
   | VIP / VIP | `vip` | `vip` |
   | Subscriber / Abonnent | `subscriber` | `subscriber` |
   | Founder / Gründer | `founder` | `founder` |
   | Sub Gifter / Sub-Gifter | `sub-gifter` | `sub_gifter` |
   | Top Sub Gifter / Top-Sub-Gifter | `sub-gift-leader` | – |
   | Bits / Bits | `bits` | – |
   | Top Cheerer / Top-Cheerer | `bits-leader` | – |
   | Verified / Verifiziert | `partner` | `verified` |
   | Prime Gaming / Prime Gaming | `premium` | – |
   | Turbo / Turbo | `turbo` | – |
   | Staff / Staff | `staff` | `staff` |
   | Admin / Admin | `admin` | – |
   | Global Moderator / Globaler Moderator | `global_mod` | – |
   | Artist / Künstler | `artist-badge` | – |
   | Bot / Bot | `bot-badge` | `bot` |
   | Watching without audio / Ohne Ton | `no_audio` | – |
   | Listening only / Ohne Video | `no_video` | – |
   | OG / OG | – | `og` |
   | Sidekick / Sidekick | – | `sidekick` |

   YouTube role badges use the same labels. Standard badges add their tier: Twitch `subscriber` shows the months from `info` and Kick `subscriber` the months from `count` ("Subscriber · 12 months" / "Abonnent · 12 Monate"); Twitch `sub-gifter` and `bits` show the version `id` and Kick `sub_gifter` its `count` ("Sub Gifter · 50"). Kick `level` shows "Level 7"; YouTube member badges keep their parsed tier and duration.
2. **Twitch `title`** — every other Twitch badge (event, channel and campaign badges) shows Twitch's English name, untranslated ("Gold Pixel Heart").
3. **`info`** — the platform's own text, for example Kick's "Kick Founder".
4. **Readable ID** — otherwise the `set_id` with `-`/`_` turned into spaces and each word capitalised (`gold-pixel-heart` → "Gold Pixel Heart"); this covers Twitch messages stored before `title` was recorded.

When a role flag is set but the array has no matching badge (for example `is_mod` without a `moderator` or `broadcaster` entry), `ChatBadges` synthesises the badge from the flag. A synthesised badge has no `count`, so its tooltip carries no tier. Badges sort as broadcaster, lead moderator, moderator, VIP, OG, subscriber, sub gifter, then the rest in their original order.

## Twitch Shared Chat

[Twitch Shared Chat](https://help.twitch.tv/s/article/shared-chat) lets several channels share one chat session - a message sent in channel B also appears in channel A's chat. Lumio recognises these cross-channel messages and attributes each to its **origin channel** so the dashboard/overlay can show which channel a message actually came from.

- **Source fields.** On the Twitch EventSub `channel.chat.message` path (`crates/lo-twitch-api` `ChatMessageEvent`), Lumio captures `source_broadcaster_user_id/login/name`, `source_message_id`, `is_source_only`, and `source_badges`. When the source broadcaster differs from the host broadcaster, ingest (`process_chat_message`) resolves the source channel's avatar through `ProfileService::get_profile` (a channel *is* a user on Twitch, keyed by `platform_user_id`) and populates two fields on the chat message.
- **Contract fields (identical on all three protocols).**
  - `is_shared_chat` (`isSharedChat` in GraphQL) - `true` when the message originated in a different channel's room during a shared-chat session.
  - `source_channel` (`sourceChannel` in GraphQL) - `{ platform_channel_id, login, display_name, avatar_url }` for the origin channel; `null`/absent for normal messages and for host-origin messages in a shared session.

  These ship on the `chat:message` WebSocket payload, the GraphQL `chatHistory` `ChatMessage` type, and the REST `GET /v1/chat/history` response. Non-shared messages are byte-for-byte unchanged (fields absent/`null`).
- **Persistence.** The `platform_chat_messages` hypertable stores `source_channel_id`, `source_channel_login`, `source_channel_display_name`, and `source_channel_avatar_url` (nullable) via the buffer→flush path, so chat-history scrollback keeps the origin-channel attribution.
- **Dashboard and popout display.** A Twitch Shared Chat message places its square, rounded-corner **origin-channel avatar after the platform icon and before the badges**. Its ring uses a stable channel colour shared with history charts; it falls back to an initial when no image is available. Kick and YouTube rows have no origin marker. The 40 px session bar below the tabs shows the Twitch icon, host-first avatar stack (at most four, then `+N`), title, live state and **Summe aller Kanäle**. It appears only with the header visible and the **All** or **Twitch** tab selected. YouTube, Kick and keyword tabs have no bar or session event lines, and tab buttons have no channel avatars. An OBS popout with **Show Header** off retains origin markers and event lines without the bar. There is no separate Shared Chat bar setting.
- **Session participants (backend).** Twitch `channel.shared_chat.begin`, `.update` and `.end` drive a server-owned session state, independently of whether a partner has written a message. GraphQL `sharedChatSession`, REST `GET /v1/chat/shared-chat` and `shared_chat_session` frames on the existing chat WebSocket channel expose the same state. The read returns `session`, `none` or `unknown`; on `unknown` the client keeps its last known session. Revisions prevent a slow read from undoing a newer push. A previously unseen partner message can show a provisional participant and trigger a debounced Helix reconciliation, but the message buffer never removes participants. Reloads, reconnects and tab switches show the current state without an entrance animation.
- **Session bar controls.** The bar opens one popover with a scrollable channel list and an in-place channel card. The list shows channel, host/own-channel markers, category, viewers, **Only this channel** and a Twitch link; its footer gives the sum and start time. Selecting a channel opens its card with banner, follower count when available, category, viewers and messages observed in this browser since session start. Escape returns to the list before closing it. Hovering an avatar with a mouse or activating it opens the same card directly; narrow popouts keep it inside the chat window. Session views use round avatars, while message and event rows use square avatars. The host has a crown; joining/leaving channels keep their origin avatar on older rows.
- **Motion.** Only a fresh WebSocket transition animates. Full motion moves the bar and avatars, briefly highlights a join, fades a departure, and pulses the live dot. Reduced motion uses opacity only; Off switches immediately. The Chat/Events/Music motion override can further reduce the global preference. End state shows the duration and every partner seen in the session, then the bar closes after eight seconds.
- **Partner-channel events.** Subs, resubs, gifts, upgrades, pay-it-forward, raids into the partner and Bits that happen in a partner channel of the session are stored as the own event types, marked `raw.is_shared_chat: true` with the same `raw.source_channel` shape. They show in the events feed and as inline chat event lines with the channel-coloured origin avatar, but never count toward own-channel stream history or fire automations. The multichat alert box ignores them (`applyAlertEvent` skips `raw.is_shared_chat`, including persisted-alert replay). See [Events → Twitch Shared Chat partner events](./events.md#twitch-shared-chat-partner-events).
- **Session transition events.** Lumio keeps the own channel's Shared Chat session state and stores each change as an event: `twitch:shared_chat_begin`, `twitch:shared_chat_join`, `twitch:shared_chat_leave` and `twitch:shared_chat_end`. Every payload carries `session_id`, `host_broadcaster_id`, the subject channel (`broadcaster_id`, `login`, `display_name`, `avatar_url`), `inferred` and `rev`. `begin` adds `participants` and `total_viewers`. `join` adds the channel's `viewer_count`, `category_id`, `category`, `title` and `followers` when known. `leave` adds `duration_secs`, `message_count` and `last_viewer_count`. `end` adds `duration_secs`, `partner_count`, `peak_total_viewers`, `partner_messages`, `end_reason` and `participants`. A `participants` entry has `broadcaster_id`, `login`, `display_name`, `avatar_url` and, when known, `viewer_count`, `category` and `title`. On `begin` it lists the channels in the session at that moment. On `end` it lists every channel that was in the session, with its last known values: the channels still in it at the end in join order, then the partners that left earlier, in the order they left.
- **No new gate.** Shared-chat display is intrinsic to Twitch chat - it adds **no** RBAC permission, feature flag, or `plan_features` row and emits **no** audit event (chat is high-volume telemetry). Attribution is by **channel** (public broadcaster identity), never by viewer.

### Channel-points messages

A Twitch chat message sent through a channel-points reward with text input carries
only the reward's id (`channel_points_custom_reward_id`) - its Twitch
`message_type` stays `text`. Lumio stores and delivers such a message with
`message_type: "channel_points_custom_reward"` on all three protocols (the
`chat:message` WebSocket payload, GraphQL `ChatMessage.messageType`, REST
`GET /v1/chat/history`). Twitch's own `channel_points_highlighted`
("Highlight my message") passes through unchanged. Twitch sends no reward name or
cost on the message, so none is shown. This applies to own and Shared Chat
partner messages alike; a partner message also carries `source_channel`. Rewards
without text input in a partner channel are invisible to Lumio, because Twitch
delivers the redemption event (`twitch:reward`) only for the own channel.

In Multichat such a message carries a **"Redeemed with channel points"** chip
(`chat.redeemedWithChannelPoints`, tinted with the `twitch:reward` accent) after the
badges - live and in loaded history, since the history proxy requests `messageType`.

## Permissions

| Permission | Description |
|-----------|-------------|
| `chat:read` | Read chat messages, view emotes |
| `chat:write` | Send/ingest chat messages |
| `chat:userinfo` | View user profiles, follow status, moderation log |
| `chat:delete` | Delete chat messages |
| `chat:ban` | Ban/unban chat users |
| `chat:timeout` | Timeout chat users |
| `chat:notes` | Manage moderator notes on platform users |
| `chat:raid` | Cancel raids |
| `chat:poll` | End polls |
| `chat:prediction` | End predictions |
| `chat:refresh_user` | Force a cache-bypassing profile re-enrichment |

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `platform_chat_messages` | TimescaleDB | Chat messages hypertable with compression. Fields: id, account_id, platform, channel_name, announcement_color, user_id, username, display_name, message, emotes (JSONB), gifs (JSONB), badges (JSONB), color, is_mod, is_sub, is_vip, sub_tier, platform_message_id, reply fields (`reply_parent_msg_id`, `reply_parent_username` — the parent author's **display name**, which is also what is stripped as `@{name}` from the echoed reply body; `reply_parent_login` — the parent author's **login/handle** twin, ZAF-1452 F1, `NULL` for platforms without a distinct login and for pre-existing rows; `reply_parent_message`), deleted_at, deleted_by, action, action_duration_secs. `created_at` is populated from the platform timestamp (YouTube `publishedAt`, Twitch `metadata.message_timestamp`, Kick webhook `created_at`) so re-ingested backlog stays chronologically aligned across platforms. A partial UNIQUE index on `(account_id, platform, platform_message_id, created_at)` makes ingestion idempotent - workers re-fetching the live-chat backlog after a restart no longer create duplicates. The `action` column records *why* a row was hidden (`"ban"`, `"timeout"`, `"delete"`); `action_duration_secs` carries the timeout length. Both survive a page refresh so the UI keeps rendering "Hidden by X" / "Blocked 5min by X" instead of the generic "Deleted by X". The `live_chat_id` column stores the YouTube live chat ID for broadcast-level filtering, enabling the Multichat to show messages from a specific broadcast when multiple YouTube streams are active simultaneously. The `gifs` column stores the per-message Twitch GIF-keyboard fragments (an ordered JSONB array of `{id, url, provider, alt}`) in its own field - never folded into `emotes`, whose per-emote counts feed already-frozen stream-history reports. Twitch cheermotes do live in `emotes` as `kind: "cheermote"` entries ([Emotes → Twitch cheermotes](./emotes.md#twitch-cheermotes)); the report counts skip them. |
| `platform_users` | PostgreSQL | Platform user profiles with ban status, treatment, follower info, enrichment timestamps, and the latest known `badges` (see [Chat badges](#chat-badges--where-they-come-from)) |
| `platform_user_notes` | PostgreSQL | Moderator notes on platform users (created_by, created_by_name) |
| `moderation_log` | PostgreSQL | Log of moderation actions (ban, timeout, delete) with target user/message, moderator, reason, duration. Both the target and the moderator carry a login/display-name pair (`target_username`/`target_display_name`, `moderator_name`/`moderator_login`) so a localized name renders as `display (login)`; a half is `null` when the platform exposes only one name or a system placeholder acted (ZAF-1452 F7). |

## Data Flow

1. Platform adapter (Twitch IRC, YouTube live chat, etc.) receives a message.
2. Message is sent to the API via the `sendChatMessage` GraphQL mutation (bot-fleet System key with `bots:internal`, explicit `accountId`).
3. Message is buffered in Redis via `lo_chat::buffer_or_persist()` (see [Buffer-push failures](#buffer-push-failures)).
4. Message is broadcast via Redis pub/sub to all connected WebSocket clients.
5. `PendingChatAccounts` tracks the account for the background flush worker.
6. Flush worker periodically (every 5s) writes buffered messages from Redis to TimescaleDB, splitting each account's batch into bind-parameter-safe chunks (see [Flush durability](#flush-durability)).
7. Frontend receives the message via WebSocket and renders it with emotes, GIFs, and badges.

### Flush durability

`ChatBuffer::flush()` reads and deletes an account's Redis buffer atomically - `LRANGE` + `DEL` run inside one `MULTI`/`EXEC` transaction (`RedisClient::pipeline_lrange_del`), so a message pushed concurrently lands either in this batch or in the next one, never between the read and the delete. The drained batch is then briefly the only surviving copy. Several safeguards keep that copy from being lost and keep a bad batch from wedging the account:

- **Chunked INSERT.** `insert_messages_batch` splits the batch into fixed-size chunks (1000 rows) before writing. Each chat row binds 28 parameters and Postgres caps a single statement at 65535 bind parameters, so an un-chunked flush of ≥ 2341 messages - trivially reached by a raid or emote wave in one 5s window - would fail as a protocol error (the batch then re-queued forever). Chunking keeps every statement well under the ceiling regardless of batch size.
- **Re-queue on failed INSERT.** If a chunk INSERT fails, the flush worker re-queues the drained messages onto the Redis buffer (`ChatBuffer::requeue`) and re-arms the account so the next tick retries, instead of dropping them. Because ingestion is idempotent (the partial UNIQUE index → `ON CONFLICT DO NOTHING`), a retry after a partial insert never duplicates rows - including across chunk boundaries. Only if Redis is *also* unreachable are the messages genuinely lost, and that path logs loudly.
- **Dead-letter on repeated failure.** A batch that keeps failing to persist must not re-queue onto the *live* buffer forever - that "poison pill" would silently stop the account's chat from ever being stored. After `CHAT_FLUSH_MAX_RETRIES` (5) consecutive failed flush cycles for an account, the worker parks the batch in a dead-letter list (`lumio:chat:deadletter:{account_id}`) instead of re-queuing it, resets the failure counter, and logs at `error`. No data is lost - the batch is preserved - and live chat keeps buffering normally. The dead-letter list is deliberately *not* matched by the live-buffer recovery scan, so a genuinely un-insertable batch can never re-wedge the live buffer.
- **Dead-letter drain / replay (ZAF-1565).** Parking is not a dead end. A **leader-gated drain pass** runs on a slower cadence (~60s) - `ChatBuffer::dead_letter_account_ids` scans `lumio:chat:deadletter:*`, and for each account `ChatBuffer::drain_dead_letter` read-and-deletes the parked batch and replays it into TimescaleDB (idempotent, so a partial prior insert never duplicates). If the insert still fails the batch is **re-parked** - which re-sets its TTL - so it is retried next cycle rather than dropped. This is what makes a parked chat window become visible again **automatically** once the persistence path heals (e.g. after a brief TimescaleDB outage), instead of requiring manual intervention. Because the dead-letter lists live in shared Redis, the drain leader can replay a batch that a *different*, now-stalled replica parked. Every park pairs the `RPUSH` with a `CHAT_DEAD_LETTER_TTL_SECS` (72h) TTL in one atomic pipeline (`RedisClient::rpush_with_expiry`), so a parked batch can never linger in Redis without an expiry - the TTL is the backstop for the case where draining has stopped entirely.
- **Supervised worker.** The flush worker runs under a supervisor (`workers::supervisor::supervise`). If it panics - or returns without being asked to shut down - the supervisor logs at `error`, increments `chat_flush_worker_restarts_total`, and starts a fresh worker after a backoff (1s doubling to 30s). Without this a dead worker stopped message persistence silently until the next process restart, while ingest kept buffering and events (written synchronously, not through this buffer) stayed current.
- **Bounded concurrency.** Each tick flushes up to 4 accounts at once, so one large or slow account no longer holds back every other account's persistence. Missed ticks are delayed rather than burst, so a slow pass does not turn into a back-to-back drain loop.
- **Backlog visibility.** `ChatBuffer::push()` and `ChatBuffer::requeue()` emit a `warn` (with `account_id` and length) whenever an account's buffer *crosses* a multiple of `CHAT_BUFFER_WARN_THRESHOLD` (10 000) messages - an edge check, so a bulk re-queue that jumps over a multiple still warns. The flush worker also exports Prometheus series so backlog is visible **before** anyone reports it: `chat_buffer_depth` / `chat_pending_accounts` (live-buffer lag), `chat_dead_letter_depth` (parked backlog awaiting replay - a value that does not fall back to `0` means a batch is stuck un-replayable), `chat_dead_letter_recovered_total` (messages the drain replayed), and `chat_flush_worker_restarts_total`. The depth gauges are measured **from Redis** (the index sets `lumio:chat:buffer:pending` / `lumio:chat:deadletter:pending` + pipelined `LLEN`, every ~30s, on every replica) - not from the worker's in-process state, which would read empty exactly when the backlog belongs to a dead worker or another process. See [Metrics › Chat-domain series](../developer-guide/metrics.md#chat-domain-series-zaf-680-2).
- **Restart recovery + periodic rescan (ZAF-1565).** The pending-account set is in-process, so an API restart - or a replica whose flush loop has stalled - would otherwise orphan a buffer whose account does not chat again. Every buffer write keeps a Redis index set current in the same `MULTI`/`EXEC`: a push or re-queue adds the account to `lumio:chat:buffer:pending`, the flush's read-and-delete removes it (the dead-letter list has the twin `lumio:chat:deadletter:pending`). Every ~30s the flush worker reads that set (`ChatBuffer::buffer_backlog`, the same pass that feeds the depth gauges) and re-seeds the pending set, so a buffer written on a now-stalled replica is picked up and drained by any live replica; members whose list is gone (an expired dead-letter TTL) are pruned in the same pass. A full keyspace `SCAN` runs only at worker start and once more ~15 minutes later (`ChatBuffer::buffer_backlog_full_scan`); it adds every buffer it finds to the index, which covers buffers written before a restart, or during a rolling deploy, by a replica on older code. Cross-replica double-flush is harmless (ingestion is idempotent).

#### Chatter tally (`platform_users` write cadence)

Every chat ingest path (Twitch and YouTube workers, Kick webhook) records the message's sender in an in-process tally (`lo_chat::ChatterTally`) instead of writing `platform_users` per message. Each flush tick, `workers::chat_flush::flush_chatter_tally` drains the tally and writes **one multi-row upsert per account** (`lo_chat::upsert_chatter_batch`), keyed by distinct chatter:

- `message_count` adds the messages seen since the last tick, `last_seen_at` keeps the latest sighting (`GREATEST`).
- Profile fields are last-write-wins: an absent value (no display name, avatar, colour or badge data, or an empty username) keeps the stored one, the role flags take the newest message. Kick writes `[]` badges for a sender without badges, so a demoted moderator still loses the badge.
- The tally holds at most 250 000 distinct chatters per process (~75 MB). Chatters already in it keep counting; a message from a new chatter beyond the cap (a stalled flush tick, a long Postgres outage) is not tallied, is counted in `chat_tally_dropped_total{reason="cap"}` and is logged at `warn` at most once a minute with the number of drops since the last warning.
- A failed write puts the rows back into the tally for the next tick (counts add up, newer profile values win), within the same cap; rows that no longer fit are counted in `chat_tally_dropped_total{reason="restore"}`. A crash or an unhandled `SIGTERM` loses at most one tick of counts; the next message rewrites the profile.
- `platform_users` keeps 20 % free space per page (`fillfactor = 80`). The counters are unindexed, so the per-tick update of an unchanged profile stays HOT instead of writing a new tuple plus every index entry.
- Moderation and treatment paths that touch a user who may never have chatted (`lo_chat::upsert_platform_user`) write the row directly and count no message.

The Kick webhook resolves the connection of every chat delivery through a 60 s in-process cache (`db::connections::find_cached_ingest_route`), which holds only the connection id, account id and channel login, never tokens. Connection writes, disconnects and a scheduled dissolution clear it on the replica that made the change; other replicas pick the change up when their entry expires.

#### Buffer-push failures

Every chat ingest path - `POST /v1/chat/message`, the GraphQL `sendChatMessage` mutation, the Kick webhook, and the Twitch and YouTube workers - goes through one helper, `lo_chat::buffer_or_persist()`. Before it existed, a failed Redis `LPUSH` was logged and swallowed while the message was still broadcast, so it appeared live and never reached the history read path. Now:

1. The message is pushed onto the Redis buffer (the normal, batched path) and the account is armed for the flush worker.
2. If the push fails, the single message is written **directly** to TimescaleDB. The insert is idempotent (`ON CONFLICT DO NOTHING`), so a message that reached Redis anyway is never duplicated by the later flush. Counted as `chat_buffer_push_failures_total{outcome="direct_insert"}`.
3. If the direct insert fails too, the loss is logged at `error` and counted as `chat_buffer_push_failures_total{outcome="lost"}` and `chat_messages_dropped_total{reason="push_failed"}`. It is never silent.

What step 3 means depends on the caller:

- **REST `POST /v1/chat/message` and GraphQL `sendChatMessage`** fail the request with the same message on both protocols (`Failed to persist chat message`, HTTP `500` on REST) and do **not** broadcast it. The caller can retry safely, because the insert is idempotent.
- **Platform ingest (Kick webhook, Twitch, YouTube)** still broadcasts the message. It exists on the platform whether or not Lumio could store it, and hiding it from the live feed would not bring it back. On Twitch, persistence runs after the broadcast anyway (ZAF-904).

#### Inspecting and replaying a backlog

Replay of dead-lettered batches is automatic - there is no manual replay command. The drain leader retries every parked batch each ~60s, so once the cause of the failed insert is fixed (TimescaleDB reachable again, or the offending data/schema corrected) the next drain pass writes the batch and `chat_dead_letter_depth` falls to `0`. A batch that still cannot persist after `CHAT_DEAD_LETTER_TTL_SECS` (72h) without a successful drain expires; that window is the time to fix the cause. To look at the backlog directly on an instance:

```sh
# Live buffers and dead-letter lists, largest first (read the index sets, no keyspace walk)
redis-cli smembers lumio:chat:buffer:pending | while read a; do echo "$(redis-cli llen "lumio:chat:buffer:$a") $a"; done | sort -rn | head
redis-cli smembers lumio:chat:deadletter:pending | while read a; do echo "$(redis-cli llen "lumio:chat:deadletter:$a") $a"; done | sort -rn | head
# One parked batch (JSON-encoded ChatMessageInput rows) and its remaining TTL
redis-cli lrange lumio:chat:deadletter:<account_id> 0 -1
redis-cli ttl lumio:chat:deadletter:<account_id>
# Worker gauges/counters on the internal metrics listener
curl -s 127.0.0.1:9100/metrics | grep -E '^chat_'
```

The `lumio:chat:deadletter:drain:leader` key in that namespace is the drain leader lock, not a parked batch.

`ChatMessageInput.user_treatment` is a live-broadcast-only snapshot and is intentionally **not** persisted per message - the durable source is the `platform_users.user_treatment` column, read back by the profile/GraphQL layer on load.

## Retention

Each plan advertises a chat retention window via `plans.chat_retention_days` (shown in Admin and on billing): **Free 365 days, Pro 1095 days** (3 years). The value is DB-canonical and admin-editable; the windows are published maxima. Enforcement is handled by a background sweep (`apps/api/src/workers/chat_retention.rs`) that hard-deletes rows in the `platform_chat_messages` and `platform_event_logs` hypertables older than each account's plan window.

- **Per-account, not a table-wide TimescaleDB policy.** Retention is plan-dependent while `add_retention_policy` is table-wide, so the sweep resolves each account's window (`api::db::plans::list_account_chat_retention`) and issues per-account deletes (`lo_chat::delete_old_messages`, `lo_events::delete_old_events`).
- **Bounded slices.** Each account's delete walks from the table's oldest chunk up to the cutoff in slices of at most 30 days (`SLICE_DAYS`), so one statement plans over and locks at most ~31 one-day chat chunks however long the window is. Because the walk starts at the oldest chunk, a row stored with an old timestamp (a backfill) is still deleted.
- **Chunk tail.** Row deletes never drop a chunk. After the per-account pass the sweep calls `drop_chunks` on both hypertables for every chunk older than the longest effective window + 1 day; those rows are past every account's maximum. Every effective window is finite, so an account with a stored value of `0` does not prevent the chunk tail from running.
- **Per-platform caps.** `apps/api/src/retention.rs` holds a per-platform maximum table (`PLATFORM_RETENTION_CAP_DAYS`). It is empty: every platform keeps the plan window.
- **Per-account override respected.** The effective window is the account's `account_limits.chat_retention_days` override when set, otherwise the plan's `plans.chat_retention_days` - the same `COALESCE(override, plan)` precedence the admin limits API applies. An account granted extended retention is never purged on the shorter plan default.
- **`chat_retention_days = 0` uses the 1095-day maximum.** The sweep clamps each account's effective window to the published maximum. A stored value of `0` resolves to 1095 days for chat and events, just as it does for chatter profiles and moderation data. No channel data is kept indefinitely by this setting.
- **Config-gated.** The worker only runs when `chat.retention_enforcement_enabled` is true. It is **disabled by default** (dev/test/staging keep their history so test data is not purged too quickly) and **enabled in production** (`config/production.toml`). Cadence is `chat.retention_sweep_interval_secs` (default 86400 = daily); a sweep also runs once on startup.

| Setting | ENV | Default |
| --- | --- | --- |
| `chat.retention_enforcement_enabled` | `LUMIO__CHAT__RETENTION_ENFORCEMENT_ENABLED` | `false` (dev) · `true` (production) |
| `chat.retention_sweep_interval_secs` | `LUMIO__CHAT__RETENTION_SWEEP_INTERVAL_SECS` | `86400` |

Deletion is permanent - retention runs in addition to moderation soft-deletes (which only set `deleted_at`/`deleted_by` and keep the row).

## Erasure (GDPR Art. 17)

Retention is time-driven (plan-scoped for messages and events, fixed for the [chatter tables](#chatter-retention)); **erasure** is event-driven and removes a data subject's chat PII **immediately**, independent of any retention window. Chatter PII lives in five tables (`api::services::chat_privacy`):

| Table | Store | Personal data |
| --- | --- | --- |
| `platform_chat_messages` | TimescaleDB | message text, `username`/`display_name`, `avatar_url`, platform `user_id`, badges/emotes (JSONB) |
| `platform_event_logs` | TimescaleDB | `raw` payload: usernames, donation/cheer messages |
| `platform_users` | Postgres | one chatter profile per account: name, avatar, badges, ban reason |
| `platform_user_notes` | Postgres | moderator notes about a chatter |
| `platform_moderation_log` | Postgres | bans, timeouts, deletes with target names and reasons |

None of them is reached by the main-database `DELETE FROM accounts … CASCADE`: the first two live in TimescaleDB, the other three have no foreign key to `accounts` (deliberately — the `platform_users` upsert runs on every chat flush and a foreign key would add a lookup and a lock on the account row to each one). They are deleted explicitly:

- **On account deletion.** Channel dissolution (immediate, or by the job at the end of the grace period — see [Accounts › Account Dissolution Flow](./accounts.md#account-dissolution-flow)) and the operator delete (`DELETE /v1/admin/accounts/{id}` / GraphQL `adminDeleteAccount`) erase **all five tables** for the account **before** deleting the account itself, so a failure leaves the account in place and the erasure retryable. The account's [stream history](./stream-history.md) is deleted in the same run, also before the account row ([Accounts › Account Dissolution Flow](./accounts.md#account-dissolution-flow), step 4; founder ruling ZAF-2626). After the delete both paths drop the channel's live AutoMod held queue instead of waiting out its 30-minute TTL (best-effort).
- **Not on platform disconnect.** Disconnecting a platform (`DELETE /v1/connections/channel/{platform}` / GraphQL `disconnectChannel`, the operator twins `DELETE /v1/admin/accounts/{id}/connections/{platform}` / `adminDeleteAccountChannelConnection`, and the credential-delete cascade) deletes only the connection and its tokens. The account's `platform_users`, `platform_user_notes`, `platform_moderation_log` and AutoMod log rows for that platform stay, like its chat messages and platform events: they belong to the channel and follow the plan retention window (founder ruling ZAF-2626). The retention sweeps work per account, not per connection, so they keep running after a disconnect.
- **On the channel's instruction (data-subject request).** Channel data belongs to the channel: Lumio processes its chat participants' data on the channel's behalf, so a person's data in a channel is deleted only on **that channel's** instruction, and only in that channel (founder ruling ZAF-2626). There is no cross-account erasure of channel data; a request for several channels is one request per channel. `POST /v1/admin/privacy/chat/erase` (GraphQL `eraseChatSubjectData`), gated by `admin:privacy-erase`, takes the instructing channel (`account_id`, required), the `instruction_reference` (ticket or e-mail id, required, at most 200 characters), the `reason` (why, required, at most 500 characters, kept in the audit event only), `initiated_by` (required: `channel` when the channel itself initiated the erasure, `subject` when the person asked for it) and the subject, and hard-deletes **in that account only** every chat row authored by the subject, their `platform_users` profile, the moderator notes about them, their AutoMod history log and every `platform_moderation_log` entry that targets them (bans, timeouts, unbans, deletes, treatment changes and AutoMod decisions). Entries in which the subject is the acting moderator stay: they record a moderator's action, not data about the subject as a chatter. The subject's platform events (`platform_event_logs` - follows, subscriptions, Bits, raids and the messages sent with them) are **not** deleted: they belong to the channel's history and stay until the plan retention window expires or the channel is dissolved (founder ruling ZAF-2626; the privacy policy says so under "Chat messages and events"). It also deletes the subject's entry in the account's bot list (`account_bots`) and removes their name from the account's frozen [stream history](./stream-history.md): wherever a finalized session's top chatters, links, commands or keywords list them, or its announcements and pins name them as author, deleter, sender or pinner, the entry keeps its counts but loses its identity (`user_id` null, `login` and name empty, no avatar, command arguments empty, `erased: true`; an announcement or pin they wrote also loses its message id), and their key leaves the session's `account_bot_keys`. Reports, exports and the public share show such an entry as "Deleted user". This reaches sessions whose chat was already removed by retention, because the stream history is kept longer than the chat. List entries without a user id are matched by login on Twitch and Kick, using the logins found on the subject's own entries and bot-list rows. Their still-open messages in the channel's live AutoMod held queue are closed with a text-free tombstone, the same close as the single-record erasure of an AutoMod entry (best-effort: Redis is a cache with a 30-minute TTL; the response reports `removed_held_queue_entry_count`). Other channels keep the same person's data untouched, and crawled sessions are not touched; they hold no chat lists. The subject is identified by **exactly one** of `lumio_user_id`, or `platform` + `user_id`; a `lumio_user_id` is resolved to its chatter identities through the user's login connections and the `(platform, user_id)` of the chat rows erased. An unknown `account_id` returns 404 "Account not found". The YouTube member-erasure endpoint (`DELETE /v1/admin/privacy/youtube/member/{id}?account_id=…&instruction_reference=…&initiated_by=…`) runs the same purge in the instructing account for the member's `(platform = 'youtube', user_id)` ([Memberships](./memberships.md)). Both erasures also record the subject's identities (with their Twitch/Kick logins) in that account's suppression list (`account_chatter_suppressions`), so the channel's sessions frozen **later** do not name them either ([Stream History → Suppressed chatters](./stream-history.md)). The entry keeps `initiated_by`; once any erasure of the person in that channel was `subject`, it stays `subject`. The entry is written before the history scrub, and a failure fails the erasure. If the channel withdraws an erasure it initiated itself, an operator deletes that entry with `POST /v1/admin/privacy/chat/erase/withdraw` (GraphQL `withdrawChannelChatterSuppression`, gated by `admin:privacy-erase-withdraw`) and `{account_id, platform, user_id, instruction_reference}`: sessions frozen from then on name the person again, while everything the erasure deleted or blanked stays gone. It acts on that channel's list only (404 when it has no entry). An entry the person asked for (`initiated_by: subject`, which includes every entry recorded before the initiator was stored) cannot be lifted on the channel's instruction: the withdrawal answers 409 and the entry stays. Only a successful withdrawal writes one system-scoped `privacy:channel_suppression_withdrawn` event, without the user id or login. After the deletes the channel's owner gets a confirmation e-mail with the channel, the date, what was deleted (kinds and counts) and a case number, never the person or the operator's instruction reference (ZAF-2640 F9; no mail when nothing was deleted, and a failed mail never fails the erasure). The case number is the first 8 characters of the `case_id` that the response and the audit event carry.
- **Orphan sweep.** Rows of accounts that no longer exist — written before account deletion erased them, or by an ingest worker between the erasure and the delete — are removed by a daily sweep (`apps/api/src/workers/chatter_orphan_sweep.rs`) across all five tables. It is gated by `chat.orphan_sweep_enabled` (off by default, on in production), because it treats every TimescaleDB account id without an account row in the main database as orphaned — only correct when the TimescaleDB belongs to that database alone.

| Setting | ENV | Default |
| --- | --- | --- |
| `chat.orphan_sweep_enabled` | `LUMIO__CHAT__ORPHAN_SWEEP_ENABLED` | `false` (dev) · `true` (production) |
| `chat.orphan_sweep_interval_secs` | `LUMIO__CHAT__ORPHAN_SWEEP_INTERVAL_SECS` | `86400` |

Both subject lookups are indexed — `(platform, user_id, created_at DESC)` and `(lumio_user_id, created_at DESC) WHERE lumio_user_id IS NOT NULL` — so on compressed chunks TimescaleDB skips every batch whose bloom filter rules the subject out instead of decompressing it. Chunks compressed before the indexes existed gain the filter when they are recompressed. The indexes are built chunk by chunk (`timescaledb.transaction_per_chunk`), which can leave an invalid chunk index behind if the build is interrupted. After deploying them, `SELECT indexrelid::regclass FROM pg_index WHERE NOT indisvalid;` on the TimescaleDB must return no rows; drop and rebuild any index it lists.

### Objection (GDPR Art. 21)

After an objection or erasure removes content from an indexed Lumio Stats
channel or directory page, the operator requests a search-engine refresh for
the affected URL (Google's **Remove Outdated Content**, "Veraltete Inhalte
entfernen") and records the request with the case. Search results can retain
an older snippet until the refresh is processed. Stream and channel-history
pages are `noindex, follow`.

A chatter can object to being shown on Lumio's own surfaces without asking for their data to be erased. A Lumio operator records the objection with `POST /v1/admin/privacy/chat/objections` (GraphQL `addChatterObjection`, gated by `admin:privacy-objection-create`) and the body `{"platform": "twitch" | "youtube" | "kick", "user_id": "…", "login": "…"}`; `login` is optional, Twitch and Kick only, and also covers the chatter's entries that have no user id. The objection is stored in the global `chatter_suppressions` list, which acts on the public [Lumio Stats](./public-stats.md) leaderboard only: it masks the chatter on read, including on streams published before the objection. Nothing is deleted, and no channel's data is touched: the chat log, profiles, AutoMod history log, stream reports, exports and history share links of every channel stay as they are — that data belongs to the channel, and an objection to it is assessed per channel and carried out through the channel's instructed erasure (founder ruling ZAF-2626). Recording an objection twice changes nothing; for a chatter whose entry is an erasure entry the response reports `reason: "erasure"`.

A person who asks Lumio itself to erase them is handled the same way on Lumio's own surfaces: `POST /v1/admin/privacy/lumio/erase` (GraphQL `eraseChatSubjectAtLumio`, gated by `admin:privacy-erase`) with `{platform, user_id, login?, instruction_reference, reason}` (`reason` required, at most 500 characters, audit only) writes an `erasure` entry in the global list (Lumio Stats leaderboard) and, on YouTube, clears Lumio's member cache across every account. It touches no channel's data; erasing their data in a channel needs that channel's instruction (above). It is idempotent and writes one system-scoped `chat_pii_erasure` event with `target: "lumio"`.

When a channel asks to erase a **single record** instead of everything about a person, `POST /v1/admin/privacy/records/erase` (GraphQL `eraseChatRecord`, gated by `admin:privacy-erase`) erases just that record in that channel: one chat message (by its id and `created_at`; the text copy a moderator delete left in the moderation log goes too), one moderator note, one moderation-log entry, one AutoMod-log entry (with its AutoMod moderation-log rows and a still-open held-queue entry), one bot-list entry, or one person's entries in one finalized stream report, including their slots in its announcements and pins (place and counts stay, the name goes). `account_id`, `instruction_reference` and a `reason` are required. A record of another account answers like a missing one (`404 Record not found`). No suppression entry is written, so later stream reports of the channel and Lumio Stats are not affected; recounts from the chat log skip a report that holds an erased entry, so the name does not come back there. A deleted chat message can still appear in its stream report as a command argument or a posted link: erase the person in that report as well. Each erased record writes one system-scoped `chat_pii_erasure` event with `target: "record"`, without names, texts or platform user ids.

`DELETE /v1/admin/privacy/chat/objections/{platform}/{user_id}` (GraphQL `removeChatterObjection`, gated by `admin:privacy-objection-delete`) lifts the objection: the public Stats leaderboard shows the name again. It returns 404 when no objection is recorded, and 400 for an erasure entry, which cannot be lifted this way. Both protocols share the validation and the error texts, and both return `{platform, suppressed, reason}`. Each change writes a system-scoped audit event (`privacy:chatter_objection_added` / `privacy:chatter_objection_removed`) whose metadata names only the platform, never the user id or login.

Every account and subject erasure writes a `chat_pii_erasure` audit event with a count per table (account-scoped for an account deletion; exactly one system-scoped event for an instructed subject erasure, naming the target account and the instruction reference but never the subject — see [Audit Log](../admin/audit-log.md#chat_pii_erasure)). A platform disconnect writes no `chat_pii_erasure` event; it is recorded by the disconnect's own event (`account:connection_removed`, or `system:account_connection_deleted` for the operator delete). Erasure is a **hard delete**, distinct from moderation soft-deletes that keep the plaintext.

## Chatter retention

The three main-database chatter tables are also bounded in time, by the same plan window as chat and events: the account's effective `chat_retention_days` (the `account_limits` override if set, else the plan's value — Free 365 days, Pro 1095 days). The window is clamped to 1095 days, the longest published maximum: a stored value of `0` resolves to 1095 days for all channel data. Every row uses the same window `W`:

| Rows | Deleted |
| --- | --- |
| `platform_users` without a moderation state | `W` after `last_seen_at` |
| `platform_users` in a moderation state: a permanent ban or an **unexpired** timeout, `user_treatment` other than `none`, or at least one moderator note | `W` after the last moderation activity: the latest of `last_seen_at`, `banned_at`, `treatment_updated_at` and the newest note edit — together with the chatter's notes |
| `platform_user_notes` whose chatter row is already gone | `W` after `updated_at` |
| `platform_moderation_log` | `W` after `created_at` |

Reading or refreshing a chatter (opening the profile card, profile enrichment, the timeout expiry) never restarts the moderation clock, because a read must not extend retention. An expired timeout is not a moderation state: once it has run out and nothing else is set, the chatter's clock is `last_seen_at` again. A platform with a published per-platform maximum (`PLATFORM_RETENTION_CAP_DAYS` in `apps/api/src/retention.rs`, currently empty) uses the shorter of that maximum and `W`. Downgrading from Pro to Free shortens the window on the next daily cycle. The sweep (`apps/api/src/workers/chatter_retention.rs`) runs daily and once on startup, on one replica at a time (advisory lock). It does not replace the event-driven deletes above: dissolution, the operator delete and Art. 17 requests still delete immediately. A platform disconnect deletes none of these rows.

There is no index on `last_seen_at`: the chat flush rewrites it on every tick, and an index would turn those updates into non-HOT updates. The sweep instead walks each account's chatters in key windows of 5,000 over the `(account_id, platform, platform_user_id)` index, and re-checks the retention predicate on the `DELETE` itself, so a chatter seen again during the sweep survives. Each cycle logs the deleted rows per table and warns when a cycle takes longer than its interval or keeps failing, because then rows outlive the published window. Metrics on the internal `/metrics`: `chatter_retention_rows_deleted_total{table}`, `chatter_retention_cycles_total{outcome}` (`ok`, `partial`, `failed`, `skipped`), `chatter_retention_last_success_timestamp_seconds` and `chatter_retention_last_cycle_seconds` (the walk reads every retained row each cycle, so its duration grows with the window; alert well before it reaches the interval).

| Setting | ENV | Default |
| --- | --- | --- |
| `chat.chatter_retention_enabled` | `LUMIO__CHAT__CHATTER_RETENTION_ENABLED` | `false` (dev) · `true` (production) |
| `chat.chatter_retention_interval_secs` | `LUMIO__CHAT__CHATTER_RETENTION_INTERVAL_SECS` | `86400` — also the maximum, because a row outlives its window by up to one interval: the API refuses to start with a larger value or `0` |

The window itself has no setting: it comes from the plan and the account override. The admin APIs refuse a `chat_retention_days` above 1095 (or below 0) on plans and account limits, on REST and GraphQL alike, and CHECK constraints on both tables hold the stored value to 0–1095.

## Moderation Permission Matrix

Moderation availability is gated by two independent layers:

1. **Actor → target hierarchy** - `getChatPermissions` (`apps/web/src/app/(main)/(app)/dashboard/chat/chat-permissions.ts`) encodes each platform's role model (who may act on whom). The matrix below mirrors it.
2. **Platform capability** - `platformSupportsModeration` (`apps/web/src/lib/moderation.ts`) greys out actions the platform's API simply cannot perform, regardless of role. Twitch, YouTube and **Kick** all support delete + timeout + ban. `platformMaxTimeoutSecs` in the same file caps the custom timeout in the dropdown and the user info card at the platform maximum (Kick 7 days / 10 080 minutes, Twitch 14 days); a longer value is refused with a localized hint, never clamped silently.

If an action still reaches the backend and is rejected, the mutation returns `success: false` with a human-readable `details` reason and a machine `errorCode`. The client shows an error toast and does **not** hide the user's messages. `moderationErrorKey` (`apps/web/src/lib/moderation.ts`) maps the known codes to localized hints - `login_scope_missing` → "log in with Kick again (Account → Profile → Reconnect)", `login_reconnect_required` → "reconnect your login", `moderation_forbidden` → "no moderation rights in this channel", `internal_error` and any 5xx → the generic "Moderation failed" line - and otherwise shows `details` verbatim. The multichat dropdown, the chat user info card and the Events user info card all use this mapping. The matrix below mirrors the actor → target hierarchy:

**Twitch** - broadcaster, lead-mod, mod hierarchy (Twitch's three-tier model):

| Actor → Target | Self | Broadcaster | Lead Mod | Mod | User |
|----------------|------|-------------|----------|-----|------|
| Broadcaster | only delete (own) | - | delete + ban + timeout | delete + ban + timeout | delete + ban + timeout |
| Lead Mod | only delete (own) | - | delete only | delete only | delete + ban + timeout |
| Mod | - | - | - | - | delete + ban + timeout |

Lead Mods and Mods cannot ban or timeout other moderators (only the broadcaster can). Lead Mods can delete other mods' messages but not ban them.

**YouTube** - strict three-tier (broadcaster + mod = "staff"). YouTube's Data API rejects `liveChatBans.insert` / `liveChatMessages.delete` against staff with HTTP 403 even when the broadcaster is the actor. Lumio therefore hides the moderation dropdown entirely when the target is a moderator or the broadcaster:

| Actor → Target | Self | Broadcaster | Mod | User |
|----------------|------|-------------|-----|------|
| Any role | only broadcaster can delete own | - | - | delete + ban + timeout |

UI labels also differ on YouTube - "Timeout" reads as "Vorübergehend blockieren" / "Block temporarily" and "Ban" reads as "Auf diesem Kanal ausblenden" / "Hide on this channel" to mirror YouTube Studio's wording.

**Kick** - the actor → target hierarchy follows the same lenient pattern as Twitch's broadcaster ↔ mod tier (broadcaster can act against mods, mods cannot act against staff). On top of that hierarchy the platform-capability layer applies: **Kick** supports delete, timeout (whole minutes, at most 7 days) and ban, all through the acting user's Kick login token, which must carry `moderation:ban` and `moderation:chat_message:manage`.

## Ban / Timeout Sweep (`chat:clear_user`)

A successful ban or timeout on any platform triggers a server-side sweep that mirrors the platform's native chat behaviour:

1. `lo_chat::soft_delete_user_messages` sets `deleted_at`, `deleted_by`, `action` (`"ban"` | `"timeout"`), and `action_duration_secs` on every undeleted row of the affected user **from the last 24 hours** — the lines the platform's own chat clears. Older history stays as stored. The window equals the chat compression delay, so the sweep only touches uncompressed chunks; an unbounded sweep had to decompress the account's entire history and failed outright on large channels once that passed TimescaleDB's per-statement decompression limit (100 000 tuples), leaving even the recent lines un-flagged (ZAF-2195). Per-chatter lookups are indexed by `(platform, user_id, created_at DESC)`, which also gives compressed batches a `user_id` bloom filter for GDPR erasure.
2. The server publishes a `chat:clear_user` event to `lumio:chat:{account_id}` with payload `{platform, platform_user_id, deleted_by, action, duration_secs}`.
3. All connected clients (dashboard + popouts + member sessions) immediately grey out the matching messages and append the localised suffix:
   - Twitch ban → "Banned by X" / "Gebannt von X"
   - Twitch timeout → "Timed out 5min by X" / "Timeout 5min von X"
   - YouTube ban → "Hidden by X" / "Ausgeblendet von X"
   - YouTube timeout → "Blocked 5min by X" / "Vorübergehend blockiert 5min von X"

After a page refresh the suffix survives because `action` and `action_duration_secs` are persisted in `platform_chat_messages`.

**Kick moderation.** Delete, timeout and ban are issued from Lumio through Kick's official public API, on the moderator's Kick **login** grant (not the channel connection). The grant must carry `moderation:chat_message:manage` (delete) or `moderation:ban` (ban/timeout). Lumio checks the stored login scopes before calling Kick. A grant without the scope, or a Kick `401`, returns `errorCode = login_scope_missing`, and the moderator logs in with Kick again to grant it. A Kick `403` returns `moderation_forbidden` (not a moderator in this channel). Kick timeouts are whole minutes: seconds are rounded **up** (minimum 1 min), and anything above 7 days is rejected. Timeouts and bans done on kick.com itself arrive via the `moderation.banned` webhook. When that webhook echoes an action already issued from Lumio within **60 s**, it is deduplicated (`KICK_BAN_WEBHOOK_DEDUP_SECS`), so the user gets one log entry and one `chat:clear_user`.

**Live moderation log.** Every stored moderation-log entry is also published live as `chat:moderation_log`, built from the same fields as the row: Lumio-issued actions (all platforms, both protocols), Twitch EventSub ban/unban, the Kick webhook, and the Kick chat-moderation listener (delete, unban). The payload carries `duration_secs` / `ends_at`, so an open user card shows the real timeout length without a reload.

External ban/timeout events (e.g. issued from a platform's own UI) flow through the same code path: `apps/api/src/workers/twitch_eventsub.rs` reacts to Twitch `channel.ban` notifications, and `apps/api/src/routes/webhooks.rs` reacts to Kick `moderation.banned` webhooks, each performing the identical sweep + broadcast. Unbans made on kick.com arrive from the [Kick chat-moderation listener](../developer-guide/kick-chat-listener.md) and are deduplicated against an unban issued from Lumio within the same 60 s window. (Chat messages live in TimescaleDB, so the sweep targets `tsdb`, not the main Postgres pool.)

## Single-message delete ingest

Beyond bans, individual message removals made **outside** Lumio are ingested so the Multichat stays in sync. Every ingested deletion follows the same invariant as Lumio's own moderation: the message is **never hard-deleted** - it is soft-deleted (`deleted_at` marker) via `lo_chat::soft_delete_message` and additionally recorded in the affected user's **moderation log** (`platform`, `target_user_id`, `action`, `target_message_id`). The soft-delete's `deleted_at IS NULL` guard makes ingest idempotent: a duplicate delete (e.g. an EventSub echo of a Lumio-initiated delete) flips no row and is skipped, so no duplicate log entry is written.

| Platform | Single-message delete ingest | Source |
|----------|------------------------------|--------|
| Twitch | ✅ moderator delete | EventSub `channel.chat.message_delete` (`twitch_eventsub.rs`). The event carries the target user + message id but **not** the acting moderator, so the removal is attributed generically (`"moderator"`). |
| YouTube | ✅ moderator delete + author retract | gRPC live-chat `MessageDeletedEvent` / `MessageRetractedEvent` and the InnerTube `MessageDeleted` path (`youtube.rs`). |
| Lumio | ✅ | `moderateChat` / `POST /v1/chat/moderate` (`graphql/chat.rs`, `routes/chat.rs`). |
| Kick | ✅ moderator delete + Kick AutoMod (unofficial source) | Kick's webhook catalog has no message-delete event (declined upstream, `KickEngineering/KickDevDocs#310`). Deletes arrive as `App\Events\MessageDeletedEvent` on Kick's **unofficial** public Pusher chat socket, picked up by the [Kick chat-moderation listener](../developer-guide/kick-chat-listener.md). The event names no moderator: a delete is attributed to `"moderator"`, or to `"Kick AutoMod"` when Kick flags it `aiModerated` (its `violatedRules` go into the log entry's `details`). An id Lumio does not know changes nothing. |

### Kick: which kick.com action arrives how

Kick's official webhooks do not cover every moderation action taken on kick.com itself. Lumio combines two sources:

| Action on kick.com | Source | Result in Lumio |
|--------------------|--------|-----------------|
| Ban, timeout | Official `moderation.banned` webhook | Moderation log `ban` / `timeout`, ban state, `chat:clear_user` sweep |
| Delete one message (moderator or Kick AutoMod) | **Unofficial** Pusher chat socket, `MessageDeletedEvent` | Soft-delete, moderation log `delete`, `chat:delete` |
| Unban, lifted timeout | **Unofficial** Pusher chat socket, `UserUnbannedEvent` | Moderation log `unban` with the acting moderator, ban state reset, `chat:moderation_log` ("Unbanned" in the user card) |
| Clear chat | none | Not picked up |

The unofficial source is **best effort**: Kick documents no contract for it, is moving its own web client to another provider, and can break it without notice. When it fails, deletes and unbans made on kick.com stop reaching Lumio; chat, events, bans and moderation issued from Lumio are unaffected. Operations: [Kick Chat-Moderation Listener](../developer-guide/kick-chat-listener.md).

## YouTube Channel Emotes (display only)

Channel-custom emotes (`:_yourchannel-purr:` style) live inside InnerTube `messageRuns` and are not exposed by YouTube's Data API or our gRPC `streamList`. Lumio harvests them out-of-band:

| Component | Role |
|-----------|------|
| `apps/api/src/workers/youtube.rs` (poll cycle) | The YouTube chat worker polls `get_live_chat` for chat + member badges and, from the same response, extracts channel-custom emotes (`emojiId` of form `<channelId>/<emoteId>`) via `parse_emote_observations` |
| `crates/lo-chat/src/emote_catalog.rs::EmoteCatalog::upsert` | Upserts the observations into the durable `chat_emotes` table (the [emote catalog](../developer-guide/emote-catalog.md)) and invalidates the Redis map `lumio:emotes:map:youtube:{channel_id}`. Postgres is the truth; Redis (6h) and an in-process LRU (~60s) are caches in front of it. |
| `apps/api/src/workers/youtube.rs::process_text_chat` | At chat ingest, scans `displayMessage` for `:shortcut:` patterns, resolves them through the catalog's three-tier read-through, attaches matching entries to `ChatMessageInput.emotes` in the same JSON shape as Twitch ingest |
| `apps/web/src/app/(main)/(app)/dashboard/chat/message-content.tsx` | Emote renderer; per-message channel emotes take **priority over the static standard-emote set** (`:smile:`, `:cry:`, etc.) so a streamer's `:smile:` upload wins over the platform fallback |

Lumio is read-only on this - we never upload emotes/badges to YouTube and we don't host the images (URLs point at `yt3.ggpht.com`). Cold-start caveat: the very first occurrence of an emote on a channel may render as plain `:shortcut:` text until the chat worker's next InnerTube poll has recorded it. A *cache* expiry no longer has that effect - the mapping is durable, so a cold or flushed Redis falls through to Postgres instead of dropping enrichment.

## Twitch GIFs (display only)

Twitch's GIF keyboard (Tier 2/3 subscriber feature) delivers each posted GIF as a `gif` fragment on the EventSub `channel.chat.message` payload - a `gif` object carrying the GIPHY `url` and a `gif_id`, with the bracketed GIF caption (e.g. `[Y A Y Yes GIF by Djemilah Birnie]`) in the fragment's `text`, **not** the URL. Lumio ingests this into its own per-message field:

| Component | Role |
|-----------|------|
| `apps/api/src/workers/twitch_eventsub.rs` | At chat ingest, collects every `gif` fragment into an ordered list of `{id, url, provider, alt}` (`id` = `gif_id`, `alt` = caption). A fragment missing its `gif` object or `url` is skipped, never a panic. |
| `platform_chat_messages.gifs` (JSONB) | The persisted per-message GIF list - its **own** column, deliberately never folded into `emotes` (which feeds frozen stream-history `emote_total`/`top_emotes` counts). NULL for every non-GIF message. |
| `ChatMessage.gifs` (GraphQL) / `ChatMessageResponse.gifs` (REST) | The read field, exposed identically on both protocols; the live WebSocket `chat:message` payload carries it automatically via the `ChatMessageInput` broadcast. |

The GIF `url` is stored and rendered **verbatim** - Twitch's terms forbid rewriting, proxying, or resizing it. GIF support is Twitch-only (no YouTube/Kick equivalent) and read-only (Lumio never sends GIFs). GIFs are intentionally **not** surfaced in the automation template context (like emotes and badges).

Rendering is gated by the **Show GIFs** display setting (General settings tab, default **on**, per-browser `localStorage["popout-settings:chat"]`). With it off the image is not rendered and **nothing** is fetched from GIPHY - enforced at every render surface: the Multichat feed and reply preview, and the user-info card's message history (which has no `PopoutSettings` host and reads the same store via `readChatShowGifs`). A GIF is likewise never rendered on a moderation placeholder or a deleted row.

## Inline stream events

### Announcements and pins

Twitch `channel.chat.notification` announcements enter the ordinary chat-message
path with `message_type = announcement` and `announcement_color` set to
`primary`, `blue`, `green`, `orange` or `purple`. A missing or unrecognised
colour resolves to `primary`, rendered in Lumio's fixed teal. Shared Chat
announcements retain their source channel. The stored colour reaches GraphQL,
REST and `chat:message`, so history and reload use the same presentation as live
chat. Twitch does not permit deleting or pinning an announcement. A timeout or
ban of its author can still mark it deleted through the usual chat path.
Announcements participate in the ordinary keyword, command, automation and
chatter counts; there is no announcement-specific exclusion. Bare domains are
linked by the shared message renderer in ordinary, announcement, first-chatter
and watch-streak rows. Twitch watch-streak `raw.emotes` carries the attached
message's emotes.

`chatPins` / `GET /v1/chat/pins` reads the current Twitch and Kick state with
`chat:read` and `feature:multichat`. A `chat:pins` update on the account's
existing chat WebSocket channel replaces both platform states. Pin actions need
`chat:pin` and `feature:multichat`; they use the acting member's Twitch login,
which must moderate the channel and grant `moderator:manage:chat_messages`.
Twitch supports pin, duration change and unpin; Kick is read-only in Lumio.
Pin durations are 30–1,800 seconds or until stream end. Twitch is polled every
10 seconds while live and every 30 seconds while offline, including connected
channels without a stream; Twitch has no IRC or EventSub pin trigger. At stream
end Lumio polls Twitch rather than clearing its state. Kick socket pins are
treated as permanent, including a socket value of `duration: "1200"`; a pin set
while offline stays until Kick removes it, while a live-to-offline transition
clears it. A rejected **already pinned** Twitch action resyncs the current card.

The current state lives in Redis under `lumio:chat:pins:{account_id}:twitch`
(120-second TTL) and `lumio:chat:pins:{account_id}:kick` (no TTL). A single
`lumio:chat:pins:poller:leader` lease coordinates polling. Five pin events in
`platform_event_logs` record transitions; there is no separate pin table.
An unpin and an expiry both arrive from Helix as an absent pin and are
distinguished by the stored `ends_at`. Changing a duration keeps `starts_at`;
re-pinning the same message starts a new `pin_removed` / `pin_added` pair.

The card's `sent_at` is the message's original time, never the pin time. It is
nullable when no source timestamp is known. A browser can hide or collapse the
card locally without changing the platform pin. Pin event rows use the
account's Events filters and history; their chat presentation has avatar and
name but no badges, plus a separate **To message** link. The Events feed shows
badges only beside the pinned message's sender.

Twitch `channel.moderate` v2 role events use a centred chat capsule with the
platform icon first when that event-row setting is on. Grants use role colour;
removals use grey and a dashed treatment. The four Mod/VIP types are each
switchable and default on. The VIP fallback glyph is a diamond. Twitch does
not report a Lead Moderator distinction, so the text always says Moderator;
Kick and YouTube have no corresponding role event rows.

Live stream events (subscriptions, resubs, gift subs, cheers/tips/superchats, raids, follows, the stream go-live/ad-break lifecycle, the hype-train lifecycle, watch streaks, …) are surfaced **inline in the multichat feed** as compact event lines, interleaved with chat messages by timestamp - the Twitch-native "notice line then message" shape. This keeps the streamer's attention in one place instead of a separate events panel.

The **Discord** member events (`discord:member_join`, `discord:member_leave`, `discord:boost`) are deliberately **not** shown as inline chat event lines (`CHAT_EVENT_EXCLUDED_TYPES` in `chat-display.ts`); they remain on the events feed and in the events settings, but carry no chat toggle.

| Component | Role |
|-----------|------|
| `apps/web/src/hooks/use-chat-events.ts` | Bounded rolling buffer (500 deep) fed by **three** sources: live events off the `events:{account_id}` WebSocket channel (dispatched as the `lumio:ws-event` window event); the **server-merged history cursor** — event rows split out of each `mergedChatHistory` page by `use-multichat.ts` and folded in as they page down with the messages (see [Server-merged history read](#server-merged-history-read-mergedchathistory) below); and a **reconnect gap-fill** over `GET /api/events` for events that streamed in while the socket was down. Buffers **every** line-eligible type; per-type visibility is applied downstream, so toggling a type on reveals events already received while it was hidden. All sources dedupe on the shared event `id`; past the cap the ring keeps only the events **bound to the loaded message span** — every event **reachable** (`created_at >= floorAt`, the oldest buffered message: the interleaved region plus the live tail above the newest message) survives, and everything **below the floor** is dropped (ZAF-1535: it has no message in the buffer, so keeping it would build the render-time event wall). This floor is a **pure function of the loaded data**, never of the scroll position (keying it on scroll dropped the newest event lines when the reader scrolled up); a just-loaded scroll-up batch survives a full ring because its merged page lowers `floorAt` in the same render that publishes the events. At the start of the view's history (no older page left, oldest message still buffered) the floor lifts and the events before the first message are kept (ZAF-2329). |
| `apps/web/src/hooks/use-event-reconnect-gapfill.ts` | Shared **reconnect gap-fill** used by both `use-chat-events.ts` (event lines) and `use-first-time-chatters.ts` (the first-message highlight): on each socket reconnect it fetches `GET /api/events` for `[newest known event, now]` so events missed while the socket was down still light up. History scroll-up no longer fetches here — that rides the merged cursor. It deliberately does nothing on mount: the mount's events arrive complete for the loaded span over the merged cursor (see [First load](#server-merged-history-read-mergedchathistory)). **Fail-silent** (see below). |
| `apps/web/src/lib/chat-display.ts` | `CHAT_EVENT_LINE_TYPES` - the line-eligible catalog, **derived** from the canonical `EVENT_CATALOG_TYPES` (so it never restates the list and grows automatically when a type is added), minus the `row-highlight` exceptions **and** minus `CHAT_EVENT_EXCLUDED_TYPES` (the Discord family - kept in the feed, dropped from the chat). `interleaveDisplayItems` merges events into the message list by `created_at`, applying the visibility filter, and binds events to the loaded message span: events older than the oldest displayed message are dropped (the ZAF-1535 floor — otherwise they stack as a message-less wall above the first row) while events newer than the newest message stay at the tail (open ceiling, so a chat-quiet channel still shows its live events). The floor is derived only from `messages`, never the scroll position (ZAF-1529). It lifts at the **start of history** (`atHistoryStart` from `useMultichat`: no older page exists and the buffer still holds its oldest message), so events before the very first message — a follow or raid before the first chat line, a fresh account — render above it in time order (ZAF-2329). |
| `apps/web/src/app/(main)/(app)/dashboard/chat/chat-event-row.tsx` | The event line, styled at chat density after the events-feed `EventRow` and reusing its exact colour and label tables - so the chat can never drift against the events feed on accent or wording. Its accent **glyph** comes from a chat-only override table, `LINE_ICONS`, which falls back to the shared `EVENT_TYPE_ICONS` table and then to a generic `Zap` bolt, so the Events page keeps its own icon slot. `LINE_ICONS` is keyed per action across platforms: follows show a `Heart` (`twitch:follower`, `kick:follower`, `youtube:subscribe`), new subs and memberships a `Star` (`twitch:subscribe`, `kick:subscribe`, `youtube:member`), gifted subs and memberships a `Gift` (`twitch:gift`, `kick:gift`, `youtube:gift_membership`, `youtube:gift_membership_received`), resubs a `Repeat`, reward redemptions a `Ticket`, stream go-live/offline a `Radio` and title/category changes a `Pencil`. Platforms are paired by meaning, not by name - a YouTube `subscribe` is a follow and a YouTube `member` is a sub - and a parity test fails when an action's glyph differs between the platforms that have it. Only the glyph is per-action; the accent colour, label, tier, `×N` plaque and recipient list are unchanged. Takes a `variant: "compact" \| "full"` that is always the global chat density - the same for every event type and for the message rows (there is no per-type density). Renders an avatar (shared `resolveEventAvatar`, same order as `EventRow`) and a Spotify now-playing line (track/artist from `raw`, cover as the avatar). For the message-bearing types (gated on `MESSAGE_EVENT_TYPES`), it renders the **viewer's own message in a grey box** (`bg-muted`, `rounded`) with a muted `MessageCircle` icon inside - the same treatment the events-feed `EventRow` uses, so a written message is visibly set apart. The box sits on **its own line below the event summary** (founder ruling 2026-09-17): the platform recap - the label, name, per-type context, and plaques - stays **inline on the event line**, and only the viewer's **typed** text drops into the box beneath it, so an automatic recap never masquerades as something the viewer wrote. That recap is **built and translated by Lumio** from the structured `raw` fields (the subscription tier and cumulative months, e.g. "Stufe 1 · 30 Monate"), **not** Twitch's own `system_message` sentence - Twitch writes that recap in English only, so echoing it verbatim printed English lines like "subscribed at Tier 1. They've subscribed for 30 months!" into a German UI. Twitch's `system_message` is therefore never rendered on the line at all. The box is a block-level (`flex`) element rendered inside the line's text span, so it inherits the line's text size (no `fontSize` on the box) while breaking onto the next line; its spacing is `em`-relative (it never re-introduces the feed's root-relative padding), it carries no leading separator (the box **is** the separator), and it hugs its text (`w-fit max-w-full`). Text + per-message emotes come from the shared `extractEventMessage` (`lib/event-message.ts`, the same extractor the events feed uses, so the two surfaces never drift on which `raw` field an event stores its text in), drawn with `MessageContent` (not `EmoteText`) so emotes inherit the chat's `--lm-emote-scale` and the line's text size. The message **wraps within the box** and is shown in full, never clipped with an ellipsis or a "show more" (no expand chevron - that stays on the events feed). The **displayed name** is itself role-aware and shared: `resolveEventDisplayName` (`lib/event-user.ts`) resolves an **outgoing** raid / unraid (`twitch:raid_out` / `twitch:raid_done` / `twitch:unraid`) to the raid **recipient** (`to_broadcaster_user_name`) and an **incoming** raid (`twitch:raid`) to the raider (`from_broadcaster_user_name`), so a completed raid names the channel that was raided rather than the streamer's own channel; every other type keeps the former display chain (including the anonymous-gifter fallback). The feed row and the chat line read this one resolver, so they never disagree on which side of a raid they show. Every per-type **context** - the Spotify artist, the channel-point reward's title + price, the Hype Train's `Level N` + total, the incoming Raid's title/category + viewer count, the **outgoing raid**'s viewer count + initiator (`by <name>`), the **stream go-live**'s title + category, the **ad-break**'s length (e.g. `180s`, accepting Twitch's string form) + manual requester, the **stream-update**'s changed title/category, the **Twitch goal**'s description + goal type (all seven Twitch types, `follow` and `follower` both read as Follower, an unknown type as a neutral "Other goal", never the raw value), with `current/target` as a locale-formatted plaque (`13.284/14.000` in German) - the row **label** names the goal's phase via the shared `resolveEventLabelKey`: `twitch:goal` is always a goal start ("Ziel gestartet"; Twitch's `channel.goal.progress` arrives as a broadcast-only `twitch:goal` that neither surface renders) and `twitch:goal_end` reads "Ziel geschafft" / "Ziel nicht geschafft" from `is_achieved` (Twitch has no separate cancel event; without the flag it stays "Ziel beendet"), the **stream-offline**'s duration on Twitch, YouTube and Kick as a `clock` plaque (`3h 12m`, from `duration_seconds`, else `ended_at − started_at`; a missing, zero, negative or unparseable duration shows no plaque), the watch-streak count, and the subscription family's tier + cumulative months (translated, month counts pluralised via next-intl ICU) - is derived by **one** shared resolver (`lib/event-details.ts`, mirroring `event-message.ts` / `event-user.ts`), never a per-type `if`-ladder in the row: it returns muted ` · <text>` suffix **segments** and accent **plaques** (`{text, icon?}`, icon ∈ `flame`/`users`/`clock`), and a missing field drops only its own part - never an empty separator. The events feed (`event-row.tsx`) reads the **same** resolver for these raid/stream/ad-break/goal/stream-offline types - it stacks the segments under the name (a goal's description stays the row title and is not repeated) and renders the plaques (outgoing-raid viewers, ad-break length, goal `current/target`, stream duration) as chips in its badge column beside the type badge, like the incoming raid's viewer chip - so the detail can never drift between the two surfaces. Reading order is label → name → segments → plaques → recap on the event line, then the viewer's message in the box below. The event line's text renders at the **same size as a chat message** - the row never grades its own text - and the trailing copy/report/recommend actions follow that same size. The variant only changes the line's spacing; the text size of the whole list is set once by the global density (below). Event lines and message rows share one leading-strip build (`ChatAxis`, `dashboard/chat/chat-axis.tsx`): the timestamp, platform icon, avatar, badges, chips, event icon and plaques are centred geometrically on the first text line's line box, so they stay level with the text at every font-size step and next to a tall emote; the message text still wraps under the strip across the full width. A **gift** line reads its count and recipient list through a second shared resolver, `lib/gift-summary.ts` (the same one the events feed `EventRow` and the User Info Card read, so all three surfaces share one field path across `twitch:gift` / `kick:gift` / `youtube:gift_membership` and both YouTube raw forms): the count renders as an accent `×N` plaque and the recipients as a muted wrapping suffix (`to A, B, C, D, E`) that names every recipient - never capped and never CSS `truncate`d, with the recipient names as plain text (the clickable name is the gifter). A bundle with no recipients yet renders the count and omits the "to …" segment. |

**First messages are a row treatment, not a line.** `twitch:first_message` turns the correlated message row into the first-time-chatter spotlight card instead of adding a separate line - the event *is* the message, so a standalone "X sent their first message" line above X's message would double every first message. This `line` vs `row-highlight` decision lives in `CHAT_EVENT_TREATMENTS` (the single source; a `row-highlight` type is excluded from the line catalog).


### Spotlight cards

Announcements, first-time chatters and watch streaks share the **B-family highlight row**: a 4 px gradient edge and a soft tint over the normal chat line. Full density has an icon, label and hint above the message; compact density keeps the icon and tooltip in the message line with no label. A moderation treatment replaces the highlight frame with its red or amber edge.

| Piece | Where | Role |
|-------|-------|------|
| `ChatHighlightRow` | `dashboard/chat/chat-spotlight-card.tsx` | Shared presentational frame for announcement, first-chatter and watch-streak rows. Full uses a heading above a normal `ChatAxis` line; compact puts only the type icon and tooltip before the time, with no visible label. Both keep the normal text renderer, badges and avatar settings. Narrow full rows omit the hint. |
| First-time chatter | `chat-message-row.tsx` | Rendered when `isFirstMessage` and the treatment is `none`. Wins over role tints, keyword-tab and highlight-users colours and the upcoming plaque (badges still show mod/VIP); a self-mention stays marked in the text. A `restricted` / `active_monitoring` treatment wins over the card: the row stays a plain moderation row with a small first-chat pill, no animation, no Greet. The hover bar is the message bar, always mounted on the card and revealed by `group-hover` / `group-focus-within` (keyboard-reachable); plain rows keep rendering it only on hover. `onGreet` is in the memo comparator. |
| Watch streak | `watch-streak-card.tsx`, branched in `multichat.tsx` | `twitch:watch_streak` renders `WatchStreakCard` instead of `ChatEventRow` (so the event-row comparator gains no props). Badges, colour and avatar come from the optional `raw.badges` / `raw.color` / `raw.avatar_url` ([payload](./events.md)); the count from `resolveEventDetails` (its plaque now carries the raw `value`), the message from `extractEventMessage`. Icon and time follow the event-line display options, badges the chat `showBadge`; `highlightStyle` and the event avatar/label options do not apply. |
| Moderation on the streak | `watch-streak.ts` | Reuses `ModerationDropdown` + `onModerate` against a `ChatMessage`-shaped target built from the event (`user_id`, login, display name, the USERNOTICE `message_id`). Fail-closed: `watchStreakPermissions` returns no rights when the event has **no `badges` key** (pre-ZAF-1726 events), because `getChatPermissions` treats an empty badge list as a moderatable viewer; ZAF-1726 always sends `badges` (`[]` included). **No delete** on the streak card (Helix documents message deletion for PRIVMSG ids only); no reply either. |
| Arrival rule | `lib/spotlight-arrivals.ts` | The entry animation runs only when the key arrived over the **live WS** ≤ 3 s ago **and** has not played in this document. Only the live handlers stamp it (`use-chat-events.ts` for the streak by `chatEventKey`, `use-first-time-chatters.ts` by `platform_message_id`); history and the reconnect gap-fill - which is deliberately not tagged as history - never do. The card decides in a `useLayoutEffect` and writes `data-enter` straight onto its node (no state); the played set covers every remount path (empty-state unmount, filter in/out, `loadLatestWindow` history copies, card ↔ row on a treatment change, a second multichat). |
| Motion switch | `shared/ui/src/globals.css`, `apps/web/src/app/globals.css` | Every spotlight animation (entry, glow, sparks, count-up, flame) sits under the `motion-ok` custom variant: `prefers-reduced-motion: no-preference` and no `data-motion="reduced"` or `"off"` on the element or above it (the global "Animations in Lumio" setting writes it on `<html>`). It is **not** coupled to `data-season-motion` (that attribute only exists while a season runs). `useMotionAllowed()` (from `useMotionPreference()`) is the JS twin, used only to skip the flame observer. Only `transform` / `opacity` / `box-shadow` animate; the card has its final height from the first frame. |
| Count-up | card CSS | A registered `@property --lm-spot-n` counted via `counter()`; armed (`data-countup`) only when `CSS.registerProperty` exists and n < 1000. The real number stays in the DOM (transparent while the `aria-hidden` overlay counts). |
| Living flame | `spotlight-assets.tsx`, `spotlight-observer.tsx` | `flame-live.svg` with CSS motion on its part hooks and a per-card phase (negative delay hashed from the event key). One shared `IntersectionObserver` per feed (`SpotlightObserverContext`, root = the scroll container, `rootMargin: 200px 0px`) sets `data-offscreen`, which pauses the flame. A moderated streak card holds it still. |
| Tokens | `shared/ui/src/globals.css` | `--first-chatter` / `-2` / `-foreground` and `--watch-streak` / `-2` / `-foreground` (light + dark) with `--color-*` Tailwind bindings. In light the pill and tone-coloured text use the darker second stop (white on the first stop is below 4.5:1); in dark the full gradient holds ≥ 5.4:1. |
| Assets | `assets/chat/spotlight/` | `flame-live.svg`, `flame-glyph.svg` (streak pill), `spark.svg` (first-chat pill + arrival sparks); inline components copy the geometry, `spotlight-assets-parity.test.tsx` fails on drift. |

**Greet** (first-time chatter only) calls `handleReply(msg)` - the same reply target as the reply button - then `prefillGreeting` fills the input only when it is empty, via `ChatInputHandle.setText` (`execCommand("insertText")`, never `innerHTML`; resets the history cursor, mention query and saved emote range). It never sends. The text comes from `chatGreetingText` in the popout-settings blob (`null`/absent = `chat.greetChatterDefault` in the current UI language, `""` = reply only, otherwise the own text with `{name}` replaced literally by `display_name`; max 300). Gated like the reply button: `canWrite` ∧ platform access.
### Event lines in history

Event lines and the first-message highlight are **loaded back with the message history**, not only streamed live — without this the feed showed up to 100 messages of scrollback and **zero** event lines until the next live event arrived. History events now ride the **server-merged cursor** (see [Server-merged history read](#server-merged-history-read-mergedchathistory) below): each `mergedChatHistory` page carries messages **and** events for the same time span, so `use-multichat.ts` splits the event rows out of every page (mount and every scroll-up `loadMore`) and hands them to the event ring as they page down with the messages. There is no second event cursor to drift against; the only remaining `GET /api/events` history query is the reconnect gap-fill (`use-event-reconnect-gapfill.ts`), which fetches `[newest known event, now]` on a socket reconnect, parallel to the message `fillGap`.

These properties keep the ring correct across all sources:

- **Dedupe on `id`.** The WS frame, the merged-page event, and the gap-fill row carry the same uuid `id`, so live and history copies of one event collapse to one line.
- **Replay-safe merge.** The buffer update is a **pure** `(prev, incoming, window) → next` fold (`mergeEventBatch`): its dedupe set is rebuilt from `prev` on every call, with no external "seen" bookkeeping. This matters because React invokes a `useState` updater more than once for the same `prev` (StrictMode in development, the non-eager path in production). An earlier version mutated a shared `seen` set inside the updater and, on the replay, found every key already present and returned `prev` — silently dropping the **entire** batch, which is why a refresh restored the chat messages but showed no event lines until the next live event. The same discipline applies to the first-message highlight ring, which derives eviction order from its own set rather than a replayed side-list. A **known key is replaced in place** when the incoming copy is a richer enrichment of the same event: a sub-gift **bundle** is broadcast on arrival (header only) and re-broadcast under the same event id once its recipient names are collected, so the merge swaps the header line for the enriched copy at the same position — same buffer index, a fresh object identity only for that one row so its memo repaints — instead of skipping it. The replacement is monotonic on recipient count, so an out-of-order re-delivery of the bare header can never clobber the enriched line back to no-names.
- **Span-bound eviction (scroll-independent).** Past the 500-deep cap the ring keeps every event **reachable** from the loaded message span (`created_at >= floorAt`, the oldest buffered message — the interleaved region plus the live tail above the newest message) up to `MAX_HISTORY_EVENTS = 5000`, trimming the **oldest reachable** first so the newest are never evacuated (ZAF-1530 / ZAF-1533). Events **below the floor** are dropped unconditionally (ZAF-1535) — they have no message in the buffer, and the merged cursor re-fetches them with their messages on scroll-up. The floor is a **pure function of the loaded data** — the oldest buffered message — never of the scroll position (ZAF-1529). A just-loaded scroll-up batch survives a full ring because its merged page lowers `floorAt` in the same render that publishes its events (otherwise the batch would be evacuated as below-floor before it reached the screen). At the start of the view's history the floor is lifted (ZAF-2329, see below), so the events before the first message stay in the ring.
- **No fetch budget, no density cap; rendering is scroll-independent.** Because messages and events page down together on one bounded, timestamp-ordered cursor, a scroll-up can no longer pull a message-less run of events out of a multi-day gap — so the client neither budgets how many events it fetches per step nor caps how many render per gap (hiding events to rebalance the ratio is falsification, founder ruling ZAF-1442 / ZAF-622 §73). What renders is a **pure function of the loaded data, never of the scroll position** (ZAF-1529). `interleaveDisplayItems` carries exactly one bound, derived only from `messages`: a **floor** at the oldest displayed message (events older than it are dropped, so no message-less event block can stack above the first row — the ZAF-1535 event wall) and an **open ceiling** (events newer than the newest message append at the tail, so a chat-quiet, event-loud channel still shows its freshest live events). Every surviving event renders at its true `created_at`, identically wherever the reader has scrolled. **The floor lifts at the start of history** (ZAF-2329): it only guards a range whose messages can still page in. Once the view has no older page left (`hasMore === false`, from the mount window or a scroll-up that loaded the last, possibly empty page) and the buffer still holds its oldest message, no older message will ever arrive — so every visible event older than the first message (a follow or raid before the first chat line, a fresh account, the beginning of the retention window) renders above it in time order, without any further action. While `hasMore` is true the floor stays. A buffer at its cap (500, or 5000 after a scroll-up) counts as "not at the start", because a trim may have shed the oldest rows. Keyword tabs stay event-free (§62).
- **History, not new arrivals.** History events never move the unread counter or the "new messages" divider and never play the notification sound — those read the message buffer, which folding events does not touch.
- **Fail-silent, correctly gated.** Events are gated on `feature:events` + `events:read` — a **different** guard than the chat messages (`feature:multichat` + `chat:read`). The merged endpoint applies both gates independently server-side (see below), and the reconnect gap-fill is fail-silent on the client (a `502` is treated as "stop, silently"; a **development** build logs a `console.warn` so "no permission", "server broke" and "there was nothing" can be told apart, production stays silent). A member who holds multichat but not events sees the chat **exactly as before**: no error, no empty state, no retry loop.

### Server-merged history read (`mergedChatHistory`)

Reading the message history and the event lines over **two independent cursors** (`chatHistory` plus a parallel event window over `GET /api/events`, merged in the browser) drifts on a chat-quiet, event-loud channel: a 24h window can hold 4 messages but hundreds of events, the two streams page apart, and the reader scrolls into a wall of message-less event lines. Capping or hiding events to rebalance the ratio is falsification (founder ruling, ZAF-1442 / ZAF-622 §73). The fix is a single **server-merged** history read that returns messages **and** events already interleaved:

- **GraphQL** `mergedChatHistory(filter: MergedChatHistoryFilterInput): ChatHistoryPage!` · **REST** `GET /v1/chat/history/merged` — identical fields, filters, gates and errors (three-protocol parity; WebSocket live-append is unchanged, this is the history read path only).
- **One page, three sources.** `ChatHistoryPage { items: [ChatHistoryItem!]!, nextCursor, hasMore }`; each `ChatHistoryItem` is tagged `kind: MESSAGE | EVENT | AUTOMOD` and carries the full row in `message` (the `ChatMessage` type), `event` (the `Event` type) or `automod` (the `AutomodLogEntry` type of the Stream History log: outcome `open`/`approved`/`denied`/`expired`, `resolvedVia` `lumio`/`twitch`, moderator, reason, text, `emotes` and the sender look) — no field drifts from the standalone endpoints. An AutoMod item's `id` is the log row id and its `created_at` is `held_at`; REST tags it `kind: "automod"`. A merged message row is the exact `chatHistory` row: both reads select one shared column list (`SELECT_COLUMNS` in `crates/lo-chat/src/queries.rs`), including `reply_parent_login`, and `apps/api/tests/chat_history_merged.rs` asserts field-for-field equality with no `null` on a fully populated row.
- **Keyset cursor, not page/offset.** Ordered `created_at` DESC with an `id` tiebreak; pass the opaque `before` cursor (a page's `nextCursor`, or any item's `cursor`) to fetch the strictly-older page. One cursor spans both sources, so the two streams can never page apart — loading is synchronous across the same time span, with nothing dropped. `limit` is total items across both streams, default 50, max 100. It is **one budget shared by both sources**: the merge guarantees that every message and every event newer than a page's oldest item is in that page (no drift), but not a ratio — on an event-loud, chat-quiet channel the newest page can be all events and hold no message at all.
- **Filters.** `platform` narrows every source, and a non-Twitch `platform` skips the AutoMod source; `liveChatId` narrows messages only (YouTube broadcast) and skips the AutoMod source; `types` (REST comma-separated `type`) is the enabled event-type set and narrows events only — the same master-switch / platform / group / per-type gating the client decides today, passed through unchanged.
- **Bounded walk window.** One request reads at most 30 days of history below its cursor (`HISTORY_WALK_WINDOW_DAYS` in `apps/api/src/services/chat_history.rs`), so it opens at most ~31 one-day chunks per hypertable however old the account's history is (ZAF-2251). When the account's retention window is enforced (`chat.retention_enforcement_enabled`) and shorter, the read stops at the retention cutoff instead and ends the history there — older rows are being deleted by the retention sweep. With the sweep off (development, staging) the full stored history stays reachable. The history also ends 7 days before the account was created (`ACCOUNT_BACKLOG_GRACE_DAYS`; the slack keeps a YouTube live-chat backlog reachable, whose messages are stored with their original timestamps when a channel is connected mid-broadcast). When a window is exhausted while older data still exists, the page ends with `hasMore: true` and a `nextCursor` at the window edge, so **a page can be short or even empty and still have `hasMore: true`**. Keep paging until `hasMore` is `false`. An account created within the last 23 days gets `hasMore: false` on its first page once that page is exhausted; an older account without history gets it once the walk reaches its creation date or no chunk of the hypertable reaches below the window, whichever comes first.
- **Independent, server-side gates.** Messages are included only with `feature:multichat` **and** `chat:read`; events only with `feature:events` **and** `events:read` — the same split the back-fill enforces client-side, now enforced in one place on both protocols. AutoMod holds are included only with `feature:multichat` **and** `chat:read` **and** `chat:automod-read` (one shared helper on both protocols): with `history:read` across the account's full chat window, without it for the last 24 hours. The AutoMod source always applies the plan-window floor, even with `chat.retention_enforcement_enabled` off, and its continuation probe is a per-account `EXISTS`, so a 24-hour caller's history ends instead of paging empty windows. A member holding one gate but not another gets only the streams they may read (no error, no empty state); none yields an empty page. Popout tokens (`lm_pop_*`) are accepted and scoped exactly like a member, so the pop-out runs the same path (founder ruling, ZAF-2531). Overlay, shared-overlay, widget, extension, developer and system keys and anonymous callers get no AutoMod items. The app-side k-way merge of the per-source keyset cursors is bounded to `limit` rows per source and is lossless (`apps/api/src/services/chat_history.rs`).

The multichat history view — dashboard **and** both pop-out kinds — consumes this endpoint for its general history (mount and every scroll-up `loadMore`), splitting each page into the message buffer (`use-multichat.ts`), the event ring (`use-chat-events.ts` / `use-first-time-chatters.ts`) and AutoMod holds (`use-held-messages.ts`).

**First load always shows the newest messages (ZAF-1566).** Because the page budget is shared, the mount does not rely on the merged page alone for messages. `loadLatestWindow` issues two reads **in parallel**, neither of them throttled: the newest merged page, and the newest 100 messages from the message-only `chatHistory` read (same `platform` / `liveChatId` filters). Both are unioned (deduplicated on `platform_message_id ?? id`) into the buffer, so the newest messages are on screen after one round trip — independent of how event-loud the channel is and of the order in which the WebSocket connects. Where those messages reach further back than the merged page, the client then pages the merged cursor down over exactly that span (`pageMergedSpan`, at most 10 pages per pass), so **every event inside the span the reader sees is loaded too** — nothing hidden, nothing capped, and messages and events cover the same span. A scroll-up that lands inside an already-loaded span keeps paging in the same trigger, so the top sentinel always makes progress. The reconnect `fillGap` (throttled, ZAF-907) is no longer what delivers the newest messages on mount; it only catches messages flushed just after the reads.

**Short and empty pages are walked, not treated as the end (ZAF-2252).** Because of the server's 30-day walk window, a page can be short or empty and still carry `has_more`. The client does not stop there: the mount and every scroll-up `loadMore` keep requesting the next page from the window-edge cursor until a page's worth of rows (100 messages or events) has landed, `has_more` is `false`, or 5 pages have been read in this trigger (`walkMergedPages` in `apps/web/src/lib/merged-history.ts`). The cap keeps a long empty stretch from looping without end; the next scroll-up resumes from the cursor where the walk stopped. While it walks, the feed shows its normal loading skeleton — on mount the history skeleton, on scroll-up the *loading older messages* line at the top of the feed. Only `has_more: false` ends the history; an empty page with `has_more: true` never shows the end-of-history state. Without the walk, an empty page would leave the buffer unchanged, the top sentinel would stay in view without firing again, and older history would be unreachable — on mount, an account whose last chat is older than 30 days would show nothing at all.

#### Gap-fill: closing the span between history and the live tail

`fillGap` (ZAF-1572) runs after every WebSocket (re)connect, once after the mount load, and on jump-to-bottom. It fetches every message persisted **after the buffer's history high-water mark** and merges it in, so after mount plus gap-fill no message is missing between the loaded history window and the newest message received live.

- **Anchored on history, not on the newest live row.** The gap-fill starts from the newest `created_at` up to which the buffer is known to hold every persisted message — set by the mount window (a database read) and advanced by each completed gap-fill. A live message does **not** move that anchor when it follows a discontinuity: on mount, on a socket drop, and the moment a gap-fill is requested (before its throttled read runs), the anchor is frozen, so a live row that lands first can never make the catch-up skip the span below it. Once a gap-fill completes, live rows extend the anchor again while the socket stays connected.
- **Pages forward over the whole span.** `chatHistory` / `GET /v1/chat/history` with `from` returns the **newest** `limit` (at most 100) rows at or after `from`, so a single page would leave a hole whenever more than 100 messages arrived. The gap-fill walks `page = 1, 2, …` (newest first — a row inserted between two reads can only cause an overlap, never a skip) until a short page or the last page. It stops early only at the buffer's own trim cap (`MAX_MESSAGES = 500` for a fresh buffer at the live end, `MAX_HISTORY_MESSAGES = 5000` otherwise): anything beyond that would be trimmed from the oldest end anyway, and the newest rows it did fetch are contiguous. A failed read keeps the anchor frozen, so the next gap-fill retries the same span.
- **Ordered and deduplicated.** Gap rows are merged into the buffer by `created_at` (`mergeGapFill`), not appended, because they are older than any live row that arrived after the reconnect. Duplicates — the inclusive `from` bound, the overlap between pages, a row already received live — collapse on `platform_message_id ?? id`. Gap rows are not tagged as older history: they streamed in while the reader was away. Nothing is hidden and the trim only ever sheds the oldest rows.
- **Throttled.** At most one gap-fill starts per 5 s (ZAF-907); further calls inside the cooldown coalesce into one trailing catch-up that starts from the frozen anchor.

Both history proxies (`/api/chat/history`, `/api/chat/history/merged`) answer `Cache-Control: no-store`, and the client requests them with `cache: "no-store"` — the mount URL is byte-identical on every load, so no HTTP cache may ever replay a stale window. A merged row whose `kind` is unknown or whose payload is missing is never dropped silently: `splitMergedHistory` returns it in `dropped` and the client logs a `console.warn` with per-reason counts, so a schema rename is visible instead of eating rows. Keyword tabs stay on the message-only `chatHistory` search (they render no inline event lines and the merged read has no keyword filter). The client passes the inline-line catalog plus `twitch:first_message` as `type=`, so events that never render never consume a page's slots.

### Where inline events appear (and where they don't)

Inline event lines - and the first-time-chatter / watch-streak spotlight cards - are driven by the `events:{account_id}` WebSocket channel (live) and the server-merged history read (restored on scroll-up). Both carry the **same** authorization: subscribing to the channel requires `events:read` (and the account to hold `feature:events`) at the [WS gate](../api-reference/websocket.md#rbac-gate-subscribe-time), and the merged read enforces `events:read` + `feature:events` server-side for its event source - so history events light up on exactly the surfaces that receive live events, never a half-state where one shows and the other doesn't. Which surfaces show them therefore follows directly from which WebSocket channels each subscribes to:

| Surface | WebSocket channels | Inline events? |
|---------|--------------------|----------------|
| Dashboard chat | `chat:{account_id}` + `events:{account_id}` (shared `useChatWebSocket`) | ✅ |
| Logged-in chat pop-out (own account, cookie/`issueWsToken`) | `chat:{account_id}` + `events:{account_id}` | ✅ |
| Delegated / shared chat pop-out - default subset (`chat:read`) | `chat:{account_id}` **only** | ❌ |
| Delegated / shared chat pop-out - token granted `events:read` (account holds `feature:events`) | `chat:{account_id}` + `events:{account_id}` | ✅ |

A delegated/shared pop-out is **event-free by default**, and this is a fail-closed authorization decision, not an oversight. A shared popout token authenticates as a popout session carrying only the **permission subset its creator delegated** - a chat pop-out is normally shared with just `chat:read`, not `events:read`. The event stream carries the account's full live event feed (subscriptions, cheers/tips/superchats, revenue-adjacent events, follows), so it is **not** widened onto a third-party share token merely to decorate chat rows; the account owner must deliberately grant that popout token `events:read` first. The pop-out resolves `events:read` + `feature:events` server-side (SSR) and subscribes to `events:` **only** when both hold - a single shared socket that subscribed to a channel its token cannot read would draw an `UNAUTHORIZED` frame that the resilient client escalates to a reconnect, so a surface only subscribes to the channels its credential can actually read (see [WebSocket → Client reconnection](../api-reference/websocket.md#client-reconnection)). No backend gate is widened and no share token is broadened: a delegate sees inline events exactly when, and only when, the owner chose to delegate `events:read`.

The **All** chat tab shows the mixed feed: every message plus every visible inline event line. A concrete platform tab keeps message rows for that platform and usually keeps event lines whose type has the same platform prefix (`twitch:*` in Twitch, `youtube:*` in YouTube, `kick:*` in Kick). A `7tv:*` emote-set event is the exception: it appears in each chat platform listed in `raw.platforms`, both live and in server-merged history. Without that list it appears only in **All**. The always-on rules still apply inside that platform scope: first-message highlighting stays attached to its message row, and watch-streak lines remain exempt from the Events-tab visibility switches. A **keyword tab** is different: it is a message-only view. It shows only the messages matching its keywords and renders **no** inline event lines at all - on any platform and for every event type, the always-on types included. Nothing the viewer typed is lost, because the watch-streak `USERNOTICE` text also arrives as an ordinary chat row, which still appears in the keyword tab whenever it matches the keyword; the always-on exception affects the standalone event line only, and standalone event lines never appear in a keyword tab. First-message row highlighting is a message-row treatment, so a first-time-chatter card on a keyword-matched message keeps rendering there too.

**7TV emote-set lines.** Additions, removals, renames and active-set switches
appear in the Multichat, chat popout/OBS and Events feed when `feature:events`
is enabled. The editor's 7TV name is plain text, with no user card. The line
shows the emote image and name, a dimmed struck-through removal, an `old → new`
rename, or the set name and an emote count when known on a switch. Adjacent
additions or
removals of the same type by the same known editor in the same set group into
one chat line when each is within 30 seconds of the previous change. Any
intervening message or event breaks the group. A group shows at most 12 emote
images and then `+N more`. Renames and set switches never group. Each change
remains a separate stored event and Events-feed row. Live arrivals animate
according to [Animations in Lumio](/developer-guide/motion) and the Chat
override; history, gap-fill and tab switches show the final state immediately.

### The Events settings tab

The **7TV** group contains four per-type switches, one for each emote-set
change. They are on by default, including in existing saved settings. The
Events feed also has a 7TV platform chip and type chips. The test-event panel
offers all four 7TV types.

The chat settings (dashboard chat and popout chat alike) have three tabs: **General · Events · Filters**. The inline event lines are configured under **Events** (the one exception is the global **Density** control, which lives on **General** - see below), which carries a count badge of how many event types are currently enabled - so a fully-silenced event feed is visible without opening the tab. All of it is per-browser, persisted in the same `localStorage["popout-settings:chat"]` blob as the other chat display settings - no separate mechanism.

**Master switch** - at the top of the **Events** tab, a **Show Event Lines** toggle turns the inline event lines off at once, so a busy streamer can silence the whole event feed without unticking each type. It is a display gate only: turning it off leaves the per-type selection below untouched (the rest of the tab dims so the selection is visibly resting, not lost), and turning it back on restores exactly that selection. Persisted as an optional `chatEventsEnabled` key in the same blob (absent → on), so an existing browser and an imported preset without it keep showing events.

**Always-on exception** (ZAF-1340 / ZAF-622 §46, founder ruling 2026-09-17) - the master switch is not absolute. `ALWAYS_ON_CHAT_EVENT_TYPES` in `chat-display.ts` (currently `twitch:watch_streak`) lists the inline types that carry the **viewer's own typed chat text** and must always be shown. `resolveVisibleEventTypes(stored, enabled)` unions this set in on **both** paths: with the switch off it returns exactly that set (not the empty set), and with it on it unions the set onto the resolved selection - so a Watch Streak survives the master switch, an unticked per-type toggle, **and** a stored or imported `{"twitch:watch_streak": false}` blob. These types therefore have **no per-type toggle** in the tab (one fixed "always visible" note replaces the dead switches), and the tab's count badge excludes them, so with the master switch off it still reads 0. `twitch:first_message` is deliberately **not** in the set: it is a `"row-highlight"` treatment (it turns the correlated message row into the spotlight card and never becomes a standalone line), so it never flows through this resolver and is always visible structurally - listing it would be a misleading no-op.

**Per-platform switch** (ZAF-622 §56) - each platform heading in the per-type list below is itself an on/off switch for that **whole platform's** event lines. Switching *Twitch* off drops every Twitch event line at once, without touching the per-type selection under it (the group dims and inactivates, so it is visibly resting), and switching the platform back on restores exactly that selection. Precedence is a pure AND: master switch → platform → per-type. Persisted as an optional `chatEventPlatforms` (`prefix → boolean`) map in the same blob; a platform **absent → on**, so an existing browser, an imported preset, and any platform added later all default to showing events. The **always-on exception** still wins: a Watch Streak line survives even with its platform switched off (the resolver unions `ALWAYS_ON_CHAT_EVENT_TYPES` in *after* the platform filter). There is deliberately **no** "all platforms off" button - that is exactly what the master switch is for. `resolveVisibleEventTypes(stored, enabled, platforms?)` applies all three gates at the single render-time site, so the dashboard chat, the popout and the count badge stay in lock-step.

**Feature & permission gate** (ZAF-622 §72) - an event **category** only appears at all - as a per-type toggle in this tab, as a chip on the [events feed](./events.md), and as an inline line - when the account holds the feature that category depends on **and** any RBAC permission its backend guard requires. The rule lives once in `apps/web/src/lib/event-access.ts` (`EVENT_GROUP_ACCESS` + the pure `filterEventTypesByAccess`), keyed by the event-type prefix, and both surfaces read it, so they can never drift on which categories are visible. The feature side maps Twitch/YouTube/Kick/Discord to their platform features, 7TV to `feature:events`, Spotify to `platform:spotify` + `feature:music`, Shopify to `integration:shopify`, StreamElements to `feature:streamelements`, and Copyright to `feature:copyright_detection`; the permission side is added only where a real backend guard demands it. Today **Copyright** is the only category with a permission: its lines and toggles show only when the account has `feature:copyright_detection` **and** the viewer holds `copyright:read` - exactly the pair the GraphQL/REST copyright guard enforces (`FeatureGuard("feature:copyright_detection").and(PermissionGuard("copyright:read"))`), so the UI never advertises a category the API would refuse. A category with no entry (`system`) is always shown. The gate sits **above** every user switch, including the always-on exception and a saved per-type selection: a `{"copyright:warning": true}` blob saved while the feature was on does **not** resurface a Copyright line after the feature is switched off - the render path (`resolveVisibleEventTypes`) drops the gated-off type regardless of the stored map, and the events feed filters the same categories out of its rendered rows, not just its chips. The chat popout resolves the feature list server-side and threads it in (it has no `FeatureProvider`); the dashboard reads the live feature/permission contexts. Before the feature/permission state has loaded the gate fails **open**, so a category never flickers away on first paint, and an *unknown* feature key never hides a category on its own.

**Connected sources in the controls** - the per-type groups in this tab and the platform/type chips in the events feed list Twitch, YouTube, Kick, and Spotify only when the account has a channel connection for that platform. A connection row still counts while it needs reconnecting. StreamElements needs a stored StreamElements token instead, and 7TV needs at least one connected Twitch, YouTube or Kick channel (the 7TV listener only watches those channels' emote sets). Discord, Shopify, Copyright, and System do not use this connection check. If the connection or token status cannot be read, the affected groups stay listed; a member without `se-tokens:read` therefore still sees StreamElements. This check only limits the settings and filter controls: it does not remove past events from chat or the events feed, or rewrite saved switches. The shared rule is `filterEventTypesBySource` in `apps/web/src/lib/event-sources.ts`.

**Display options** - how the event lines look. Each defaults to today's behaviour so the tab is invisible until touched:

- **Avatar** - show the viewer's avatar, or the track cover for a now-playing line (default **off**).
- **Platform Icon** / **Timestamp** - *inherit* the chat's own icon/timestamp display settings until overridden here, then detach.
- **Event Label** - the coloured label ("Sub", "Raid", …); default **on**. When off it still renders as a fallback for events with no username (channel events like hype train), so a row is never blank.

**Density is global and lives on the General tab, not here.** The **Density** control (`Compact` · `Full`, default `Full`) applies one density to every row of the chat feed - message rows and event lines of every type alike: `Compact` tightens the line spacing, `Full` keeps the standard spacing. There is no per-event-type density; a stored or imported `auto` value from before this change resolves to `Full` (settings migration v4, `normalizeChatDensity`). `Compact` also shrinks the **whole chat list** together - message rows, event lines, date/unread separators, chips, avatars and emotes - to `0.875×` of the font-size setting (`chatDensityTextScale` in `lib/chat-display.ts`, applied once on the list wrapper in `multichat.tsx`), so the font-size slider still scales it and the separate emote scale still multiplies on top. `Full` keeps the list at the font-size setting. GIFs and stickers keep their fixed pixel cap. The value persists in the same `popout-settings:chat` blob.

**Which event types show inline** is a per-type toggle list grouped by platform, labelled identically to the events-feed filter chips. Each platform's group heading doubles as the per-platform switch described above.

- **Defaults.** All line-eligible types, including the four 7TV changes, are on until the viewer turns them off. Saved per-type choices remain in effect.
- **Spotify now-playing** (`spotify:track` and the rest of the `spotify:*` family) is line-eligible; enabling `spotify:track` surfaces a now-playing line per track change with the album art as the avatar.
- **New-type defaulting.** A type absent from a saved selection defaults to on, so it does not silently disappear.
- **Independent of the events feed.** The inline chat visibility is a *separate* setting from the events feed's own filter (`lumio:event-filters`): the chat and the events feed are different consumption contexts, so a filter change in one never surprises the other.

## Motion preferences

The user-profile `motion_preference` (`system`, `reduced`, `off`) applies to the dashboard and popouts. Chat's settings panel stores a stricter `motion` override (`inherit`, `reduced`, `off`) per browser and user/account pair; `?motion=reduced|off` tightens a single popout URL. The effective level is the strictest of the operating system, profile and override. The seasonal animation row only controls seasonal decoration. Chat spotlight, scrolling and the watch-streak flame follow the effective level; animated emotes and GIFs continue playing as viewer content. See [Animations in Lumio](/user-guide/preferences#animations-in-lumio) and the [Motion developer guide](/developer-guide/motion).

## Settings export/import (browser-local)

All Multichat, Events and Music **settings live in the browser's `localStorage`** —
nothing is stored server-side. Export/import (ZAF-622) lets a user save a selection
of those settings and re-import it on another device, an OBS browser source, a fresh
browser, or a different account. It is **purely client-side**: no API endpoint, no
RBAC, no audit event (the data never leaves the browser except as something the user
themselves copies or downloads).

The UI is one section inside the shared `PopoutSettings` panel, so it appears in the
dashboard and every popout, in both modes and all three variants (chat/events/music).

**Four transports, one data model (§4a).** The same envelope is offered four ways,
all converging on the same `parseImport` validator:

- **Code string** (`LS1Z.<base64url(deflate-raw(utf8(JSON)))>`, or `LS1P.<base64url(utf8(JSON))>`
  when `CompressionStream` is unavailable). Compression uses the native
  `CompressionStream`/`DecompressionStream` - **no dependency**. `LS1` versions the
  *transport*; the JSON's `format` still versions the *content*; the decoder reads
  both forms and tolerates injected whitespace/zero-width spaces (messengers wrap
  long lines). It is reversible cleartext, not a hash or encryption.
- **Share link** carrying the same code in its **URL fragment**
  (`{origin}/dashboard/{chat|events|music}#s=LS1…` - the path is the variant's own
  dashboard route, origin from `window.location.origin`, never hard-coded; a link built
  inside a popout still points at the dashboard, since it is clicked on a device with no
  popout token). The fragment never reaches the server (RFC 3986 §3.5), so this stays
  backend-free. A link has no hard length ceiling - the dialog only shows a soft hint
  for very long links (some messengers wrap them). Both the code and the link react live
  to the section selection.
- **Copy JSON** and **Download** a `lumio-settings-YYYY-MM-DD.json` file - the file is
  the transport you want for a backup.

Import is **one input field with auto-detection** (§4c): content starting with `{`
is JSON, with `LS1` is a code, a value starting with `http` that contains `#s=` is a
share link (everything up to and including `#s=` is stripped and the rest decoded as a
code), anything else is a defined error - no toggle to set wrong. When a share link is
opened, the matching feature shell (chat / events / music, dashboard *and* popout) reads
`location.hash` on mount, decodes it and opens that feature's settings-import panel with
the preview directly (it never writes on its own).

File shape (envelope is snake_case; each section payload is the store value **verbatim**,
so `chat.display` is camelCase and `chat.filters` is snake_case - no field-name mapping to drift):

```json
{
  "kind": "lumio.settings",
  "format": 1,
  "app_version": "2026.9.93",
  "exported_at": "2026-09-14T19:40:00.000Z",
  "sections": {
    "chat.display": { "fontSize": 16, "settingsVersion": 1 },
    "chat.filters": { "hide_users": [], "highlight_users": [], "match_mode": "substring" },
    "chat.keyword_tabs": [ { "id": "…", "label": "Raid", "keywords": ["raid"] } ],
    "events.filters": { "platforms": ["twitch"], "types": ["twitch:follower"], "allPlatforms": [], "allTypes": [] }
  }
}
```

Sections: `chat.display`, `chat.filters`, `chat.keyword_tabs`, `events.display`,
`events.filters`, `music.display`. **Deliberately excluded** (device/account
properties or transient UI state, not feature settings): theme, language, streamer
mode, active account, the active platform/keyword-tab selection, the YouTube
broadcast id, send-platform selection, emote/recent-emote caches, and alert-box
runtime state.

Design invariant: the registry's `parse`/`write` reuse the **existing** store
parsers and writers (`parseChatFilters`/`saveChatFilters`,
`parseKeywordTabs`/`saveKeywordTabs`, `parsePopoutSettings`/`savePopoutSettings`,
`parseStoredEventFilters`/`saveStoredEventFilters`) - there is no second validator,
so an imported value can never reach a state the normal load path could not also
produce. Chat filters and keyword tabs are written through the Pattern-B
scoped-key + unscoped-mirror writer, so an import is visible to token popouts too.

Import semantics (v1): a selected section **replaces** its store wholesale (it does
not merge - the protection is the pre-write preview). The page reloads after import
because components read the stores once on mount and a `storage` event does not fire
in the writing tab. Envelope validation is fail-safe: bad JSON, a wrong `kind`, or a
`format` newer than the app aborts with a message and writes nothing; an older
`format` is accepted (the versioned per-section parsers handle it); an unknown
section id is listed as skipped; a corrupt section is marked unusable while the rest
stay importable.

> **Note:**
> An export that includes `chat.filters` or `chat.keyword_tabs` contains the viewer
> names the user hid/highlighted and their keyword lists. Because the code/link/JSON/file
> are all reversible cleartext, sharing them shares those names - the export dialog
> warns about this next to the **Copy code**/**Copy link** buttons. It is the user's own
> local data, exported by the user, with no server involved.

Key files: `apps/web/src/lib/settings-transfer.ts` (registry + build/parse/apply,
plus `encodeTransferCode`/`decodeTransferCode`, `parseImportInput` auto-detection and
`buildTransferUrl`), `apps/web/src/lib/popout-settings-defaults.ts` (display-blob
type/defaults/parse extracted from the client component),
`apps/web/src/components/settings-transfer.tsx` (the export/import dialogs +
`ImportReview`), `apps/web/src/components/settings-import-fragment.tsx`
(`SettingsImportFromFragment`: each feature shell mounts it once; it reads a
`#s=<code>` URL fragment on mount and opens the import preview), `apps/web/src/lib/download.ts` (`downloadBlob`).

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/chat.rs` | GraphQL queries and mutations |
| `crates/lo-chat/src/` | Core chat crate (buffer, filter, profile service, emotes, moderation) |
| `apps/api/src/services/emotes.rs` | Emote fetching from Twitch, YouTube, Kick, 7TV, BTTV, and FFZ |
| `apps/api/src/services/moderation.rs` | Per-platform Twitch/YouTube/Kick moderation HTTP calls invoked from `moderateChat` and `POST /v1/chat/moderate` |
| `apps/api/src/services/chat_moderation.rs` | Moderation orchestration shared by `moderateChat` and `POST /v1/chat/moderate` (validation, login-token refresh, Kick scope pre-check, dispatch, error codes, moderation log + live broadcasts) and the Kick `moderation.banned` webhook handling (60 s dedup) |
| `apps/api/src/workers/chat_retention.rs` | Config-gated background sweep that enforces per-plan `chat_retention_days` by deleting expired `platform_chat_messages` and `platform_event_logs` in 30-day slices, then dropping the chunk tail |
| `apps/api/src/workers/chatter_retention.rs` | Config-gated daily sweep that deletes `platform_users`, notes and `platform_moderation_log` after the account's effective plan window (Free 365 days, Pro 1095 days; ceiling 1095 days) — [Chatter retention](#chatter-retention) |
| `crates/lo-chat/src/emote_catalog.rs` | Durable `chat_emotes` catalog + three-tier (LRU → Redis → Postgres) read-through - written and read by the YouTube chat worker |
| `crates/lo-chat/src/youtube_emote_cache.rs` | YouTube `:shortcut:` tokenizer and message enrichment (storage-independent) |
| `apps/api/src/workers/youtube.rs` | The single YouTube chat worker: harvests member-tier badges and channel-custom emotes inline from its InnerTube poll cycle and enriches chat messages |
| `apps/api/src/state.rs` | `PendingChatAccounts` shared state |
| `shared/chat-filters/src/` | Shared hide/highlight and keyword-tab matcher used by dashboard, popout, and tests |
| `apps/web/src/hooks/use-multichat.ts` | Browser hook for live chat, history paging, keyword-search back-fill, token fetches, and per-tab paging state |
| `apps/web/src/lib/chat-display.ts` | Pure display filter for platform/broadcast scoping, deleted-message hiding, keyword-tab views, and hidden-message removal (default) or placeholders |
| `apps/web/src/lib/chat-persistence.ts` | Defensive `localStorage` persistence for chat filters, keyword tabs, and active platform selection (exports the Pattern-B `readScoped`/`writeScoped` helpers reused by the alert box) |
| `apps/web/src/lib/chat-alerts-reducer.ts` | Pure `applyAlertEvent` reducer + live-state shapes for the five alert cards; folds live WS events and replayed history identically |
| `apps/web/src/lib/chat-alert-persistence.ts` | Alert-box persistence: types, defensive parsing, reconciliation, the `GET /api/events` server replay (build/fetch/fold), the Layer-A/Layer-B merge, and the cross-tab dismiss registry |
| `apps/web/src/app/(main)/(app)/dashboard/chat/chat-alerts.tsx` | The alert-box component: renders the five cards and wires the load/save, replay, and cross-tab dismiss effects |
| `apps/web/src/components/info-user-modal.tsx` | The user info card (`UserInfoModal`): full-page `FullscreenPanel`, all permission/actor-target gates, the moderation confirmation and link warning as panel layers; sub-components (header, profile facts, action bar, the four tabs and their data hooks) live in `apps/web/src/components/user-card/` |
| `apps/web/src/components/keyword-tab-dialog.tsx` | Keyword-rule editor for tab visibility, platform scope, match mode, color, and notification sound |
| `apps/web/src/components/popout-settings.tsx` | General/Filter settings tabs for display toggles, deleted-message visibility, hidden-message style, notification volume, and keyword-rule management |
| `apps/web/src/lib/settings-transfer.ts` | Settings export/import registry - declarative section list whose `parse`/`write` reuse the existing store parsers/writers, plus `buildExport`/`parseImport`/`applyImport`, the `LS1` code encode/decode, `parseImportInput` auto-detection and `buildTransferUrl` (share link) |
| `apps/web/src/lib/popout-settings-defaults.ts` | The display-blob type, defaults, constants and parse/save path extracted from the client component so pure modules can reuse them |
| `apps/web/src/components/settings-transfer.tsx` | The Transfer-settings panel section + export dialog (section selection, copy code/link/JSON, download) and import dialog (file/drag, one auto-detecting field, preview with replace notes); exports `ImportReview` |
| `apps/web/src/components/settings-import-fragment.tsx` | `SettingsImportFromFragment`: mounted once per feature shell (chat/events/music, dashboard + popout); reads a `#s=<code>` URL fragment on mount and opens that feature's settings-import panel with the preview; never writes on its own |

---

## Features / Chatter List

Source: https://docs.lumio.vision/features/chatter-list

# Chatter List

## Overview

The chatter list shows **who is in the chat right now**, grouped as **Broadcaster → Moderators → Bots → VIPs → Viewers**, each with avatar, display name and **how long they have been in the chat** (`first_seen_at`). People who left stay for 30 minutes in a separate **recently left** group with the time they were last seen (`last_seen_at`). Twitch and Kick are providers behind one registry. Kick appears in `supported_platforms` only when the account has a usable Kick channel connection; Twitch is listed even without a connection.

- **Drawn from two sources.** A platform snapshot (Twitch: Helix `GET /chat/chatters`, every 30 s; Kick: kick.com's undocumented active-chatters web endpoint, every 60 s) is the baseline. Everyone who writes in the chat is added **immediately** from the normalised `chat:message` stream every platform already produces. Kick's source lists recent writers, not lurkers, and caps its ordinary chatter group at 100; its role groups are complete. The panel can therefore show "100 of N" ("100 von N" in German) using Kick's full `total`, while fewer rows may appear until user ids resolve.
- **Logged-out viewers are invisible** to everyone, Twitch included. The list therefore counts *chatters* (logged-in chat participants), not viewers, and its number is less than or equal to the viewer count.
- **Platform latency, stated honestly.** Twitch updates the Helix list with a delay: someone who only watches shows up after 30 s to a few minutes, and leaving is just as slow. Kick's web list contains recent writers only, so someone who only watches never appears there. People who write show up immediately on either platform. The `chatters_snapshot_lag_seconds` metric measures snapshot delay. An IRC `JOIN`/`PART` source is a possible later source inside the Twitch provider; it is not built.

## In / out rule

Twitch announcements count as ordinary chat messages for the chatter tally;
their authors are subject to the same inclusion rules as other chatters.

The key of an entry is `(platform, platform_user_id)` — never the name.

- **In:** in the last platform snapshot, **or** wrote in the last 10 minutes.
- **Out:** missing from **two consecutive** snapshots **and** no message since the first miss, and no message in the last 10 minutes. The two-snapshot rule keeps the slow platform list from making entries flicker.
- **Recently left.** An entry that is out is not removed. It becomes `present = false` with its `last_seen_at` frozen and stays for `recently_left_retention_secs` (30 min) counted from `last_seen_at`; then it is dropped. Someone who comes back within that time is `present = true` again with a **new** `first_seen_at`.
- **Never counted.** Recently-left entries are never part of a count: `platforms[].total` is the platform's own in-the-chat count, and without it a client counts `present = true` entries only.
- **Times.** `first_seen_at` is when the key entered the list in the current stream (snapshot or message) and never moves while the person stays. `last_seen_at` is the later of the last snapshot that listed them and their last message. Both are cleared with the whole state when the stream goes offline, so times never span two streams.
- **No duplicates.** A snapshot and a chat message write into the **same** entry. A `join` is sent only for a key that is new; anything else is an `update`, and nothing is sent when nothing visible changed. A rename changes only the display, never the row. The same login on two platforms is two rows (two people may own it).

## Roles

Roles are neutral: `broadcaster | moderator | bot | vip | viewer`. Each provider maps its platform onto them.

Twitch:

| Group | Source |
|---|---|
| Broadcaster | the connected channel's own user id |
| Moderators | Helix Get Moderators (cached 10 min, dropped on EventSub `channel.moderate` `mod`/`unmod`) — falls back to the `moderator`/`lead_moderator` badge when the list can't be read |
| Bots | a curated list of known bots (Nightbot, StreamElements, Moobot, Fossabot, …), **Lumio's own `lumiobot`**, the account's own custom bot account, the `bot` badge, and accounts on [Channel settings → Bots](../user-guide/channel-settings.md#bots) |
| VIPs | Helix Get VIPs (cached like moderators, dropped on `vip`/`unvip`) — badge `vip` as fallback |
| Viewers | everyone else |

**Bot wins over moderator/VIP:** almost every bot is a moderator; without this rule the bot group would nearly always be empty. An unknown bot appears as a viewer until the channel marks its account, Lumio recognises it from its curated list, or it carries the `bot` badge. The channel list matches stable platform user IDs, so a matching display name alone does not move someone into Bots. [Stream History](./stream-history.md#bot-messages) uses the same bot definition to leave bot messages out of its chat figures.

Kick maps the connected channel owner to **Broadcaster**, its moderator, bot and VIP groups to the matching roles, and its OG group and ordinary chatters to **Viewers**. Kick chat badges can supply moderator, VIP or bot roles; OG, founder and subscriber badges do not change the neutral role. Known and account-owned bots take precedence over moderator/VIP, as on Twitch.

Twitch avatars come from Helix `GET /users` (100 ids per call) through the Redis cache `lumio:avatar:{platform}:{uid}` (24 h). Kick resolves the website list's usernames to stable user ids through the channel-user lookup before adding entries, so snapshots and messages share the same key. Unresolved names wait for a later poll. Kick avatars come from that lookup. Broadcaster, moderators, bots and VIPs are resolved first; missing avatars arrive later as `update` deltas.

## Polling: open panel or live stream

An (account, platform) is polled while **a panel is open**, **or** while `live_polling` is on, the account **uses the list** and that platform's **stream is live**. Nothing is polled for an account that never opened the list.

1. Subscribing to the WebSocket channel `chatters:{account_id}` sets the interest key `lumio:chatters:interest:{account_id}` (TTL `interest_ttl_secs`, 90 s). Every API replica renews it every 5 s for each `chatters:*` channel it holds open.
2. Every subscription also renews the **wanted marker** `lumio:chatters:wanted:{account_id}` (TTL `wanted_marker_ttl_secs`, 7 days) and adds the account to the index set `lumio:chatters:wanted`. While the marker exists and the platform is live, the account is polled without an open panel, so `first_seen_at` and the recently-left group stay true. An account that does not open the list for 7 days drops out (its index member is pruned).
3. **Live signal:** the per-account online set `lumio:channel_online:{account_id}`, maintained by the channel-status service from Twitch EventSub `stream.online` / `stream.offline` (plus the Helix check at worker start), the Kick live-status path and the YouTube poller, and rebuilt from Postgres at API start.
4. Per (account, platform), one replica takes the lock `lumio:chatters:lock:{account_id}:{platform}` (`SET NX`) and runs the poller. Replicas never poll twice.
5. The poller reads the platform snapshot every `poll_interval_secs` (Twitch 30 s, Kick 60 s), at most `max_chatters` (5000 by default) entries. A larger chat reports `truncated = true` with the platform's full `total`; Kick can truncate at its own 100 ordinary chatter entries even when Lumio's configured cap is higher.
6. **Stream offline:** when the poller sees its platform go from live to offline, it drops the whole state (a `leave` for every entry) and its meta. If no panel is open it then stops.
7. With neither interest nor (marker + live), the poller stops. The state hash then expires 5 minutes later.

**Cost.** Live polling makes one Helix list call per 30 s for Twitch and one kick.com list call per 60 s for Kick per live account that used the list in the last 7 days, plus lookups for new user ids and avatars. `chatters_snapshot_requests_total` shows it. `live_polling = false` is the kill switch and returns to panel-only polling.

State lives **only in Redis** — `lumio:chatters:{account_id}:{platform}` (hash, field = platform user id, TTL 5 min, renewed on every poll). There is no database table and no history. A present chatter's moving `last_seen_at` is written at 5-minute granularity (exact in memory, exact once frozen at departure), so a snapshot can show it up to 5 minutes old; clients render "in the chat since" from `first_seen_at`.

## Availability

`platforms[].available = false` comes with a `reason`:

| `reason` | Meaning | What still works |
|---|---|---|
| `missing_scope` | The Twitch connection was made before the chatter scopes existed | People who write still appear; reconnect Twitch once for the full list |
| `not_connected` | No usable channel connection | Nothing for this platform |
| `disabled` | Switched off by the operator (`[chatters]` / `[chatters.<platform>]`) | Nothing for this platform |
| `source_unavailable` | The connected platform's list source failed or returned an unexpected response (for example, Kick's undocumented endpoint was blocked or changed) | Recent writers still appear; no reconnect is needed. After two failed polls, snapshot-only entries move to recently left. Other platforms keep working |

The Twitch list needs `moderator:read:chatters`; the moderator and VIP groups need `moderation:read` and `channel:read:vips` (see [Channel Connections OAuth Scopes](../developer-guide/channel-connections-oauth-scopes.md)). Without the latter two, roles fall back to chat badges.

Kick's active-chatters source is read without an OAuth token. It needs no additional channel scope or reconnect. If it is unavailable, `total` becomes `null`, `truncated` becomes `false`, and the panel explains that only people who write are shown.

## API

All three protocols carry the same fields, the same guard — **`chat:read` + feature `feature:chat-viewer-list`** — and the same errors. Popout tokens work on all three (the chat popout authenticates with a popout token / ws-token).

| Protocol | Surface |
|---|---|
| GraphQL | `chatters(platforms: [String!]): ChattersSnapshot!` |
| REST | `GET /v1/chat/chatters?platform=twitch` (comma-separated, optional) |
| WebSocket | channel `chatters:{account_id}` — snapshot as `bootstrap`, then `chatters:delta` events |

An unknown platform is `Bad request: Unsupported chatter platform: <name>` (`BAD_REQUEST`) on GraphQL and REST. See [GraphQL](../api-reference/graphql.md#chatter-list), [REST](../api-reference/rest-api.md#chatter-list) and [WebSocket](../api-reference/websocket.md#chatters-channel) for the exact shapes.

## Plan gating

`feature:chat-viewer-list` (category `feature`) is enabled on the same plans as `feature:multichat`. A plan without a `plan_features` row resolves to off. The multichat entitlement alone does not grant the list.

## The panel (web)

The list is a side panel of `ChatShell`, so the chat page and the chat popout share one implementation; `EventsShell` has none. User-facing walkthrough: [Viewer List](../user-guide/viewer-list.md).

- **Opt-in, setting = visible.** A "Viewer list" section on the General tab of the chat settings (`chat` variant only). On means the panel is open on load, in the popout and after a preset. The header button next to the settings cog (and the panel's X) is a quick hide, persisted per browser under its own `(user, account)`-scoped localStorage key `lumio:chat-viewer-list-hidden:<userId>:<accountId>` — **not** in the `popout-settings:chat` blob, so presets, export and import never carry it. The chat page and the chat popout in the same browser share it; an OBS dock keeps its own. Applying a preset or import of the chat display section, or switching the setting off → on, clears it, so the panel opens. An unknown stored value reads as shown.
- **Gating.** Button and panel need `chat:read`, `feature:chat-viewer-list` and a channel on at least one platform from `supported_platforms`. Without feature or permission the settings section is absent; without a connected supported platform it is shown locked, naming the supported platforms.
- **Data.** A one-shot `GET /api/chat/chatters` (GraphQL `chatters` through the chat proxy, popout-aware) tells the shell which platforms are supported. The `chatters:{account_id}` WebSocket channel is subscribed **only while the list is enabled and not quick-hidden** — list off or hidden means no subscription and therefore no platform polling; the one-shot snapshot still runs so the header button stays available. Popouts mint their WS token from the popout session.
- **Loading state.** The list body shows the chat's loading indicator — the regular spinner, or the active season's icons when the season look is on (`SeasonalSpinner`; pulsing instead of bobbing with "Animations: Off" or `prefers-reduced-motion`) — instead of text. `chatterListPhase()` in `lib/chatter-list.ts` picks the body: **rows** whenever the client holds any (a re-subscribe after a quick hide refreshes the existing list in place, never a spinner); otherwise **loading** before the first answer (REST snapshot or WS bootstrap) and while every *available* platform still has `updated_at = null` — an empty snapshot taken before the backend ever polled is not "nobody in chat". Unavailable platforms (`missing_scope`, `not_connected`, `disabled`, `source_unavailable`) never count as waiting, so their hint shows at once. The wait is capped at 15 s from the first answer since the list went live (`CHATTER_FIRST_POLL_GRACE_MS`); after that an empty list shows the empty state. The indicator sits centred in the list area; the ring follows the panel's font scale (20·s px); the head shows no count while loading.
- **Client dedupe.** The client holds a `Map` keyed by (`platform`, `user_id`). A bootstrap replaces it, a duplicate `join` is applied as an `update`, a `leave` of an unknown key is ignored. An `update` with `present = false` moves the row into the **Last seen** group; the `leave` after the retention removes it.
- **Groups and counts.** Present people sit in the five role groups; every `present = false` entry, whatever its role, sits in **Last seen** at the bottom (newest departure first), collapsible like the others (group id `recent`). The panel head and the group headers count present people only; the header button carries no number (`platforms[].total` where known, else present rows).
- **Two-line rows (38 px at 14 px font size).** A 26 px avatar beside the 13 px display name (with the ZAF-1452 trailing login) and a muted 11 px time line with tabular figures, formatted by `chatterTimeLabel()` in `lib/chatter-list.ts` and translated (`chat.viewerList.time.*`). Present: clock icon + "here 48 min" from `first_seen_at` ("just arrived" under a minute, "here 1 h 52 min" from an hour). Last seen: eye icon + "last seen 4 min ago" from `last_seen_at`, avatar at 45 % opacity, name muted; rows stay clickable. The line is never blank: without `first_seen_at` it falls back to `last_seen_at`, then to "in chat". One shared clock re-renders the rows every 30 s (no per-row timers); "updated 12 s ago" in the head has its own 5 s clock.
- **Own font size, decoupled from the chat.** The whole panel scales with the list's own font size — blob field `viewerListFontSize`, 8–32 px, default 14, set by the *Font size* slider in the Viewer list settings section — by `s = viewerListFontSize / 14` (`chatterRowMetrics(viewerListScale(settings.fontSize))` in `lib/chatter-list.ts`, where `settings = resolveViewerListSettings(blob)`). The chat's `fontSize` never reaches the list, on the chat page or in the chat popout: row height 38·s, group header 28·s with its 10·s name and count, avatar 26·s, name 13·s, time line and avatar initial 11·s, row icons 12·s; in the head the title and count 12·s, "updated…" 10·s, the filter trigger, search box and close button 28·s high with 12·s text and 14·s icons, the status notes 11·s and the filter menu 14·s — at 14 px exactly the unscaled values. A list font-size change re-measures the virtual list and the *Auto* width live; a fixed width is left alone.
- **Platform-neutral.** Nothing in the UI names a platform on its own; the platform filter and per-row platform icons (at the row end) appear only from two connected supported platforms on. The filter is a single-select `Select` from `@lumio/ui` left of the search: an icon-only trigger (layers icon for *All platforms*, else the platform icon; tooltip and `aria-label` name the choice) whose items are *All platforms* plus every platform in `supported_platforms` the account is connected to — no hard-coded platform list. The choice filters groups, group counts, the head count and the search results.
- **Rows** open the existing user info card through the same selected-user state as a chat-row name (works for lurkers without messages); without `chat:userinfo` rows are plain text. Long lists are virtualised (`@tanstack/react-virtual`) with sticky group headers.
- **Layout.** The chat keeps at least 420 px. The panel docks while the chat area (its own width, not the viewport) is at least 420 px + panel width, re-docking 16 px above that threshold; a docked panel is never squeezed below its width. Otherwise it overlays the feed and leaves a 48 px chat strip. The resize separator (`role="separator"`, arrows ±8 px, `Home` = Auto, double-click = Auto) works docked and — from 288 px chat-area width — in the overlay; a drag never switches mode. The chat page opens the popout at 420 px + panel width (Auto counts as its upper limit at the list font size: 740 px at 14 px) while the list is on. *Auto* fits the widest row — the wider of name and time line (measured in the scaled fonts) plus the avatar, paddings and, from two platforms on, the platform icon — clamped to `200 … min(480, 320·s)` px; the time line is measured as of the latest snapshot. While dragging the separator shows no tooltip or pixel readout; the hover hint appears before a drag only, and `aria-valuenow` carries the width.
- **Settings fields** in the `popout-settings:chat` blob, all optional (absent = default, no schema-version bump, validated at read time): `viewerListEnabled`, `viewerListSide` (`left`/`right`), `viewerListWidth` (`"auto"` or 200–480), `viewerListCollapsed` (role ids plus `recent`), `viewerListPlatform` (`"all"` or one platform id; a platform that is no longer connected applies as `"all"`), `viewerListFontSize` (8–32, rounded; missing, non-numeric or non-finite ⇒ 14). The retired multi-select `viewerListHiddenPlatforms` may still sit in old blobs and is ignored. They travel with presets, export and import; the export summary reads "Viewer list on · right · Auto".
- **Motion** uses `motion`: panel slide + fade (200 ms in, 150 ms out) only after a user action, row fade-in (150 ms, small joins only) and fade-out (120 ms); someone who leaves cross-fades from their group into Last seen (old place fades out in 180 ms, new row fades in over 220 ms, then the rows below glide up 200 ms instead of jumping) — none of it for batches of more than 20 changes; only at the `full` motion level (OS, "Animations in Lumio" and the chat surface override, strictest wins); instant under `reduced` / `off`.

## Audit

**No audit event, on purpose.** The chatter list is a read-only, ephemeral surface: it changes no rights, no roles and no credentials, and stores nothing beyond an ephemeral Redis state that is cleared at stream end (departed people at most 30 minutes). Live polling does not change that: it is a background read of the same public list. The audit log is a security record, not an activity stream (see [Audit Events](../developer-guide/audit-events.md)). The one-time Twitch reconnect for the new scopes runs through the existing connection flow, which already emits `account:connection_added`.

## Privacy

The list processes public chat usernames, display names and avatars that the platform itself shows to everyone in the chat, plus when each person was first and last seen in the current stream.

**Data lifetime:**

- A present chatter's entry lives as long as they are in the chat during the stream.
- A person who left is kept for at most **30 minutes** (`recently_left_retention_secs`) after they were last seen, then dropped.
- **Everything is cleared when the stream goes offline.** If polling stops for another reason, the Redis state expires 5 minutes after the last poll.
- The avatar cache keeps avatar URLs for 24 hours. The wanted marker stores only the account id (7 days).

There is no database table and no history.

## Configuration

See [Installation → Chatter list](../getting-started/installation.md#chatter-list) for `[chatters]`, `[chatters.twitch]` and `[chatters.kick]`.

## Metrics

| Series | Labels | Meaning |
|---|---|---|
| `chatters_snapshot_lag_seconds` | `platform`, `outcome` (`seen` \| `missed`) | Seconds until a snapshot first shows someone who already wrote (`seen`), or until such a writer left without any snapshot showing them (`missed`) |
| `chatters_snapshot_requests_total` | `platform`, `outcome` (`ok` \| `missing_scope` \| `not_connected` \| `source_unavailable` \| `error`) | Every platform list read. Flat while no panel is open and no live-polled stream is live |

## Adding a platform

See [Chatter List Providers](../developer-guide/chatter-list-providers.md).

---

## Features / Events

Source: https://docs.lumio.vision/features/events

# Events

## Overview

The Events module handles platform event logging and alerting for streaming events such as followers, subscribers, cheers, raids, channel point redemptions, and tips. Events are stored in a TimescaleDB hypertable with automatic compression for efficient time-series queries. Events are broadcast in real time via Redis pub/sub to WebSocket clients for overlay alerts and dashboard panels. The module supports paginated queries with filters by type, platform, date range, and full-text search.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/events.rs`) -- Queries for listing/fetching events with filters. Mutation for emitting test/manual events.
- **Crate** (`crates/lo-events/src/`) -- Core event logic including `EventFilter`, `EventInput`, `EventRow` types, `list_events`, `get_event`, `insert_event`, and `broadcast_event` functions.
- **Database** -- Events are stored in TimescaleDB (`platform_event_logs` hypertable) with time-based partitioning and compression.
- **Real-time** -- Events are broadcast via `RedisPubSub` using the `GqlPubSub` wrapper to all WebSocket subscribers for the account.

### Frontend

- Next.js API proxy routes call GraphQL internally.
- A shared `EventsShell` component (`apps/web/src/components/events-shell.tsx`) renders
  the live feed with filters by type and platform. It backs three surfaces: the
  dedicated **Events** page (`/dashboard/events`), the compact panel on the Dashboard
  home, and the `/popout/events` window (cookie or popout-token auth).
- **Event categories are feature- and permission-gated (ZAF-622 §72).** A category's
  filter chips **and** its rendered rows appear only when the account holds the feature
  that category depends on and any RBAC permission its backend guard requires. The rule is
  the shared `EVENT_GROUP_ACCESS` map in `apps/web/src/lib/event-access.ts`, read by both the
  events feed and the [chat event settings](./chat.md#the-events-settings-tab) so the two never
  drift. **Copyright** is the only category with a permission today: its chips and lines show
  only with `feature:copyright_detection` **and** `copyright:read` (the exact pair the copyright
  GraphQL/REST guard enforces). The API still returns a disabled category's historical rows
  (`GET /v1/events` filters only on `feature:events` + `events:read`, never per event type), so
  the feed drops them **client-side** in the rendered list, not just from the filter chips — a
  category the account cannot see never appears.
- **Expired-connection alert.** Events are produced by the account's channel connections, so a
  dead grant makes the feed stop silently. When a channel connection is flagged
  `reconnect_required`, the header's per-platform pill shows an icon-only warning marker and a
  red entry appears in the connection notices directly under the topbar, carrying a **Reconnect**
  button that starts that platform's OAuth flow in place. It is shown only to viewers holding
  `connections:create` (Owner / Administrator among the default roles). See
  [Connections → Connection notices](./connections.md#connection-notices).
- **User info card.** Clicking a username opens `EventUserInfoModal` (`apps/web/src/components/user-info-modal.tsx`), which resolves the event's user via the shared `resolveEventUser` and renders the same full-page user info card the chat uses (see [Chat](./chat.md) and [User Info Card](../user-guide/events.md#user-info-card)) - without the chat-only Highlight/Hide filter buttons. Moderation from the card goes through `/api/chat/moderate`, gated by the session's own permission subset (also in the events popout).
- Overlay alerts consume events via WebSocket for real-time display.
- **Localized subject names show the login (ZAF-1452).** A row's subject renders as
  `display (login)` when the platform display name is genuinely localized - the reported
  Twitch case is `こさむん (pocom_2026)`, where the display name is non-Latin but the login
  stays the ASCII handle. The decision is the shared three-condition AND rule in `@lumio/ui`'s
  `formatPlatformName`: the display name differs from the login by more than case, **and**
  carries a non-Latin letter, **and** the source `platform` is one where the display name is a
  freely-editable field over an immutable login — **Twitch only** today (founder ruling
  ZAF-1452, 2026-09-27). So an ordinary Latin follower like `Cruex` stays un-bracketed, umlaut
  and accent names (`Ömer`, `Renée`) are not bracketed, and — crucially — the *same* localized
  values render as **`こさむん`** (no bracket) on a YouTube event, where "channel title ≠
  handle" is the normal case and bracketing would fire on every non-Latin channel. The events
  feed (`event-row.tsx`) and the inline chat event line (`chat-event-row.tsx`) read one shared
  resolver (`apps/web/src/lib/event-user.ts` → `resolveEventDisplayName`, which returns both
  the display name and the login) and thread `event.platform` into the helper, so the two
  surfaces can never drift and an unknown platform is fail-closed (no bracket).
- **First-time chatter & watch streak (Twitch).** Both appear as rows in the feed
  and are toggleable in the type filter. A `twitch:first_message` row shows the
  chatter and their first message. A `twitch:watch_streak` row shows the viewer, a
  flame streak-count badge, and - resub-style - their attached chat message when
  they left one (otherwise Twitch's "watched N streams in a row" line). The
  first-time-chatter signal additionally tags the matching inline row in
  [Multichat](./chat.md).

## API

### GraphQL Queries

Every account-facing event operation additionally requires the `feature:events`
feature flag. On GraphQL the guard is `FeatureGuard("feature:events")` combined
with the permission below; the four REST handlers call the same
`require_feature` after their permission check.

| Query | Permission | Description |
|-------|-----------|-------------|
| `events(filter: EventFilterInput)` | `feature:events` + `events:read` | Paginated event list with filters for types, platform, search, date range. Returns `PaginatedEventResult!`. Without `from` it reads the 30 days before `to` (or now). `total` is capped at 10 000: `totalCapped: true` means more events match, and `pages` covers the capped total. The count runs only when `total`, `totalCapped` or `pages` is selected. |
| `event(id: UUID!)` | `feature:events` + `events:read` | Get a single event by ID (account-scoped) |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `emitEvent(input: EmitEventInput!)` | `feature:events` + `events:create` | Emit a broadcast-only test event without persisting it. Returns `EmitEventResult!`. |
| `emitBotEvent(accountId: ID!, eventType: String!, platform: String!, username: String!, raw: JSON!)` | System key with `bots:internal` | Bot-worker ingest path with an explicit account id. Broadcast-only - like a test event, it is **not** persisted. |

### REST Endpoints

All paths live under `/v1`. Bodies are snake_case.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/events` | `feature:events` + `events:read` | Paginated event list (accepts the same filters as `EventFilterInput`). Same 30-day default window and 10 000 cap as GraphQL; `_meta.total_capped: true` when more events match |
| `GET` | `/v1/events/{id}` | `feature:events` + `events:read` | Fetch a single event by ID (account-scoped) |
| `POST` | `/v1/events/emit` | `feature:events` + `events:create` | Emit a manual event (insert + broadcast) |
| `POST` | `/v1/events/test` | `feature:events` + `events:create` | Emit a test event - broadcast only, never persisted |

The dashboard's Test Event side sheet and `/popout/test-events` send through the broadcast-only test path. The popout's delegated token must contain `events:create`; without it the catalog is replaced by a permission notice. Both surfaces list only the event sources the session could receive: the category's feature and RBAC rule (the same map that gates the events feed) and, for Twitch, YouTube, Kick, Spotify and StreamElements, a connected source. An unreadable connection list keeps those sources listed. This is display filtering only; the send path itself checks `feature:events` + `events:create`. Tests appear in the account's overlays and dashboard activity with a **TEST** badge, but the Events page and Events popout filter them out. They do not enter stored history, metrics or milestones. `POST /v1/events/emit` is the separate persisted manual-event route.

### WebSocket

| Channel | Gate | Feature flag |
|---------|------|--------------|
| `events:{account_id}` | `events:read` on the account in the channel key | none |

Subscribing streams every event inserted or broadcast for that account in real
time - the same payloads the `events` query returns. The gate is resolved by
`channel_gate_for` / `channel_feature_for` in `crates/lo-websocket/src/gate.rs`;
`events` carries no feature flag, so an account without `feature:events` can
still stream (the REST/GraphQL read paths remain flag-gated).

### Filter Options (EventFilterInput)

| Field | Type | Description |
|-------|------|-------------|
| `types` | `[String!]` | Filter by event types (e.g., `["twitch:follower", "twitch:subscribe"]`) |
| `platform` | `String` | Filter by platform (comma-separated for multiple) |
| `userId` | `String` | Filter by platform user ID (matches `raw->>'user_id'`) |
| `search` | `String` | Case-insensitive text search in raw JSON data |
| `from` | `String` | ISO 8601 timestamp -- only events after this time |
| `to` | `String` | ISO 8601 timestamp -- only events before this time |
| `page` | `Int` | Page number (1-based, default 1) |
| `limit` | `Int` | Items per page (default 25, max 100) |

## Permissions

| Permission | Description |
|-----------|-------------|
| `events:read` | Read/list events. Enforced on `events`, `event`, `GET /v1/events`, `GET /v1/events/{id}`. |
| `events:create` | Create events (test events, emit). Enforced on `emitEvent`, `POST /v1/events/emit`, `POST /v1/events/test`. |
| `events:userinfo` | View user cards/profiles from event entries. Enforced client-side by the `EventsShell` component (`<Gate permission="events:userinfo">`); the underlying profile lookup is guarded by `chat:userinfo`. |

There is no `events:delete` permission: no manual event-deletion surface exists on
either protocol. Events are aged out automatically by the per-plan retention sweep
(see **Database** below), not on demand - so the former `events:delete` account
permission was **removed** in ZAF-1094 (it gated nothing).

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `platform_event_logs` | TimescaleDB | Hypertable, segmented by `account_id`, compressed after 7 days. Columns: `id` (UUID), `account_id`, `type` (the `platform:action` string - GraphQL exposes it as `eventType`), `platform`, `external_id`, `raw` (JSONB), `created_at`. Primary key `(id, created_at)`. A partial unique index on `(account_id, external_id, created_at)` where `external_id IS NOT NULL` makes webhook re-delivery idempotent. |

### Retention

Events are retained on the **same per-plan window as chat messages** - the privacy policy groups "chat messages and events" under one rolling, plan-dependent window. A background sweep (the chat/event retention worker, gated by `chat.retention_enforcement_enabled`) hard-deletes each account's `platform_event_logs` rows older than its effective `plans.chat_retention_days` window (a per-account `account_limits.chat_retention_days` override takes precedence). Because the window is per-plan, it is enforced by a per-account `DELETE` sweep rather than a table-wide TimescaleDB retention policy. An account whose effective window is `0` keeps its events indefinitely. Events belong to the channel: the channel's instructed data-subject erasure (`POST /v1/admin/privacy/chat/erase` and the YouTube member erasure, see [Chat › Erasure](./chat.md#erasure-gdpr-art-17)) does not delete them, so they leave only through this window or channel dissolution (founder ruling ZAF-2626).

### Event Types

Events follow the `platform:action` naming convention. There are two distinct
lists and they are not identical - quote the right one for your use case.

#### Extension-subscribable catalogue

`LUMIO_EVENT_TYPES` in `packages/protocol/src/events.ts` is the closed enum an
extension may pass to `useLumioEvent()`. It is validated by a Zod schema, so a
type outside this list is rejected at the SDK boundary:

- **Twitch:** `twitch:follower`, `twitch:subscribe`, `twitch:gift_sub`, `twitch:resub`, `twitch:cheer`, `twitch:raid`, `twitch:reward`, `twitch:reward_status`, `twitch:reward_add`, `twitch:reward_update`, `twitch:reward_remove`, `twitch:hype_train`, `twitch:hype_train_end`, `twitch:poll`, `twitch:poll_end`, `twitch:prediction`, `twitch:prediction_lock`, `twitch:prediction_end`, `twitch:goal`, `twitch:goal_end`, `twitch:ad_break`, `twitch:ban`, `twitch:unban`, `twitch:stream_online`, `twitch:stream_offline`, `twitch:stream_update`
- **YouTube:** `youtube:subscribe`, `youtube:member`, `youtube:superchat`, `youtube:supersticker`, `youtube:gift_membership`, `youtube:gift_membership_received`, `youtube:poll`, `youtube:stream_online`, `youtube:stream_offline`
- **Kick:** `kick:follower`, `kick:subscribe`, `kick:resub`, `kick:gift`, `kick:kicks`, `kick:reward`, `kick:reward_status`, `kick:stream_online`, `kick:stream_offline`, `kick:stream_update`
- **Spotify:** `spotify:track`, `spotify:play`, `spotify:pause`, `spotify:skip`, `spotify:volume`, `spotify:queue_add`, `spotify:device`, `spotify:playlist_add`, `spotify:playlist_remove`, `spotify:playlist_create`, `spotify:playlist_edit`, `spotify:playlist_delete`
- **StreamElements:** `streamelements:tip`
- **Chat (cross-platform):** `chat:message` (fires for all platforms)

#### Reward lifecycle and redemption status (`raw`)

| Lumio type | Source | Stored | `raw` |
|------------|--------|--------|-------|
| `twitch:reward` | EventSub `channel.channel_points_custom_reward_redemption.add` | yes | `id`, `user_id`, `user_login`, `user_name`, `user_input`, `status` (`unfulfilled`), `redeemed_at`, `reward { id, title, cost, prompt }` |
| `twitch:reward_status` | EventSub `channel.channel_points_custom_reward_redemption.update` | yes | the `twitch:reward` shape with `status` `fulfilled` or `canceled` |
| `twitch:reward_add` / `twitch:reward_update` / `twitch:reward_remove` | EventSub `channel.channel_points_custom_reward.add` / `.update` / `.remove` | no (`broadcast_only`) | the Twitch reward: `id`, `title`, `cost`, `prompt`, `is_enabled`, `is_paused`, `is_in_stock`, `is_user_input_required`, `should_redemptions_skip_request_queue`, `max_per_stream`, `max_per_user_per_stream`, `global_cooldown`, `cooldown_expires_at`, `redemptions_redeemed_current_stream`, `background_color`, `image`, `default_image`, `broadcaster_user_*`. `.remove` carries the reward as it was. |

The three lifecycle types are configuration changes, not audience events: they
reach extensions, overlays and automations live on `events:{account_id}` and
are never written to the event history, so the dashboard feed and chat (which
drop `broadcast_only` frames) do not show them. The Twitch subscriptions need
`channel:read:redemptions` or `channel:manage:redemptions`; Lumio already
requests both for every Twitch channel connection, so no reconnect is needed. Kick sends no reward lifecycle webhook, so
there is no `kick:reward_add/update/remove`. Lumio's own [rewards module](/features/rewards)
emits no events; changes made there are not platform rewards.

#### Kick payloads (`raw`)

The Kick webhook receiver normalizes every delivery before it is stored and
broadcast (`lo_kick_api::normalize_event`). The original Kick payload stays
complete, and Lumio's canonical fields are **added** at the top level, so Kick
events render and filter through the same fields as Twitch:

| Lumio type | Kick event | Top-level fields added |
|------------|-----------|------------------------|
| every type with an actor | — | `user_id` (string), `user_login` (channel slug), `user_name`, `avatarUrl` (omitted when Kick sends none), `is_anonymous` |
| `kick:follower` | `channel.followed` | only the actor fields |
| `kick:subscribe` / `kick:resub` | `channel.subscription.new` / `.renewal` | `cumulative_months`, `expires_at` |
| `kick:gift` | `channel.subscription.gifts` | `giftCount`, `total`, `is_gift`, `giftRecipients`; `recipient_user_{id,login,name}` for exactly one giftee; `gifter_is_anonymous` for an anonymous gifter |
| `kick:kicks` | `kicks.gifted` | `kicks` (amount, a counter like Twitch `bits`, not money), `message`, `kick_gift_name`, `kick_gift_type`, `kick_gift_tier`, `kick_pinned_time_seconds`; for a known gift also `kick_gift_id`, `kick_gift_image` and `kick_gift_color` (see below) |
| `kick:reward` / `kick:reward_status` | `channel.reward.redemption.updated` | `id`, `status`, `user_input`, `redeemed_at`, `reward { id, title, cost, prompt }`. The first delivery of a redemption `id` is `kick:reward`, every later status change is `kick:reward_status`. |
| `kick:stream_online` / `kick:stream_offline` | `livestream.status.updated` | none for `kick:stream_online` (`title`, `started_at`, `ended_at` are already top level); `kick:stream_offline` adds `duration_seconds`, and `started_at` when Kick sent none (see [Stream offline payloads](#stream-offline-payloads-stream_offline)) |
| `kick:stream_update` | `livestream.metadata.updated` | `title`, `category_id`, `category_name`, `language`, `has_mature_content`, `title_changed`, `category_changed`, `language_changed`, and `old_title` / `old_category_name` / `old_language` for a changed field (see below) |

Mapping, deduplication and live-status handling:
[Webhooks → Kick](/features/webhooks#kick).

**KICKs gift graphics.** Kick's webhook names the gift but carries no gift id
and no image, and Kick has no image API. `lo_kick_api::kicks_gifts` holds a
static table of Kick's 10 gifts; `normalize_event` matches `gift.name` against
it (case-insensitive) and adds:

| Field | Example | Meaning |
|-------|---------|---------|
| `kick_gift_id` | `"rage_quit"` | Kick's gift id |
| `kick_gift_image` | `{"static": "https://files.kick.com/kicks/gifts/rage-quit-static.webp", "animated": "https://files.kick.com/kicks/gifts/rage-quit.webp"}` | Gift sticker. `animated` is `null` for the four BASIC gifts, which have a static image only |
| `kick_gift_color` | `"#45ADFC"` | Kick's accent colour for the gift |

A gift name the table does not know adds none of the three fields; the event
then renders as before (coin icon). An `#[ignore]` smoke test
(`cargo test -p lumio-api --test kick_gifts_smoke -- --ignored`) compares the
table with Kick's catalog.

#### Twitch cheer payloads (`twitch:cheer`)

`channel.cheer` delivers `message` as plain text without fragments. The EventSub
worker matches every word of the form `<prefix><amount>` (case-insensitive,
only prefixes the channel's [cheermote catalog](./emotes.md#twitch-cheermotes)
knows) and adds:

| Field | Meaning |
|-------|---------|
| `emotes` | One entry per cheermote word in `message`, in the chat [cheermote entry](./emotes.md#twitch-cheermotes) shape (`kind: "cheermote"`). Absent when nothing matched |
| `cheermote` | The image set for the **total** `bits`: the highest global `Cheer` tier with `min_bits <= bits`, as `{prefix, bits, min_bits, color, urls{dark,light}{animated,static}}`; a theme also carries the scale-4 `animated_hd` / `static_hd` pair when Twitch has both (see [Twitch cheermotes](./emotes.md#twitch-cheermotes)) |

Both fields are render data and fail-open: when the catalog cannot be loaded
they are absent and the event is stored unchanged.

#### Twitch Shared Chat session events

The four Twitch-only session types are `twitch:shared_chat_begin`,
`twitch:shared_chat_join`, `twitch:shared_chat_leave` and
`twitch:shared_chat_end`. They appear at their event time in both chat and the
Events feed. Start shows the host-first channel stack, the channel sum and
partner details; join shows the joining channel; leave shows its duration and
message count; end shows the duration, peak sum and every partner seen in the
session. Missing Helix enrichment omits only that value. A join found during
reconciliation is marked **Detected later**. Repeated pushes do not create
duplicate rows.

The four switches live in the existing **Twitch** type group in chat, the
Events feed and popout settings and are on by default. The feed also offers a
**Shared Chat** filter chip. Chat shows session rows only in **All** and
**Twitch**, with start/end details collapsed; the feed expands those details.
These events do not open chat alerts. They are separate from partner-channel
subs, Bits and raids described below.

#### Twitch Shared Chat partner events

During a [Twitch Shared Chat](./chat.md#twitch-shared-chat) session, events that
happen in a **partner** channel of the session are stored and broadcast as the
**same event types** as the own channel's, labelled with the channel they
happened in:

| Partner event | Twitch source | Lumio event type |
|---------------|---------------|------------------|
| Sub, resub | `channel.chat.notification` `shared_chat_sub` / `shared_chat_resub` | `twitch:subscribe` / `twitch:resub` |
| Gift sub, community gift | `shared_chat_sub_gift` / `shared_chat_community_sub_gift` | `twitch:gift` (bundled like an own community gift) |
| Gift / Prime upgrade | `shared_chat_gift_paid_upgrade` / `shared_chat_prime_paid_upgrade` | `twitch:gift_upgrade` / `twitch:prime_upgrade` |
| Pay it forward | `shared_chat_pay_it_forward` | `twitch:pay_it_forward` |
| Raid **into the partner** | `shared_chat_raid` | `twitch:raid` (raider in `user_*` / `from_broadcaster_user_*`) |
| Bits | the `channel.chat.message` `cheer` field of a partner-channel message (`channel.cheer` fires only for the own channel) | `twitch:cheer` (`external_id` `chat_cheer:<message_id>`) |

`raw` carries the same flattened fields as the own-channel event plus:

| Field | Meaning |
|-------|---------|
| `is_shared_chat` | `true` |
| `source_channel` | The partner channel, `{platform_channel_id, login, display_name, avatar_url}` - exactly the chat-message [`source_channel`](./chat.md#twitch-shared-chat) shape |
| `notice_type` | The **base** type (`sub_gift`, not `shared_chat_sub_gift`), so gift bundling and the bundled-recipient history filter treat it like an own notice |
| `shared_chat_notice_type` | Twitch's original `shared_chat_*` notice type (notices only) |

A notice counts as a partner event only when its `notice_type` starts with
`shared_chat_` **and** `source_broadcaster_user_id` is set and differs from the
receiving channel. An own cheer derives nothing from the chat message - it stays
the single `channel.cheer` event. Shared-chat announcements, like own
announcements, produce no event.

Some documented `channel.chat.notification` notice types produce no event,
whether they come from the own channel or as a `shared_chat_*` twin:
announcements, unraids, charity donations, modiversaries and gifted Drops
summaries (`gifted_drops_summary`; its payload is only a `recipient_count`).
Watch streaks reach Lumio through the IRC path as `twitch:watch_streak`. Only a
notice type Twitch has **not** documented is logged for capture (see
[Logging](../developer-guide/logging.md)).

Partner events are **displayed only**. They are not the own channel's revenue or
activity, so they never count toward [stream history](./stream-history.md) and
summary stats, never fire [automation](./automations.md) event triggers, and
never touch the own channel's gift-sub straggler safeguard. Channel-points
redemptions in a partner channel are not delivered by Twitch; see
[Channel-points messages](./chat.md#channel-points-messages).

In the dashboard and popouts a partner event (a row whose `raw` carries `is_shared_chat`
and a named `source_channel`) leads with a **channel chip**: the square origin avatar plus the
channel name, truncated at about 12em, with the full name in the tooltip and accessible name.
It renders on the chat event line, in the events feed (full and compact, and the dashboard
home activity) and, as name next to the avatar, in the stream report's announcement list,
independent of the label, badge and avatar settings. Shared-chat messages keep the bare
origin avatar. Twitch does not deliver follows of partner channels, so there is no partner
follow row.

The display setting **Events from Shared Chat partners** (`showSharedChatPartnerEvents` in
the `popout-settings:chat` and `popout-settings:events` blobs, absent = on) hides every event
with `raw.is_shared_chat: true` in the chat event lines and the events feed. The four session
types `twitch:shared_chat_begin|join|leave|end` are always shown. It filters at display time
only: buffered events reappear when it is switched back on, and history, counts and alerts
are unaffected.

#### Stream update payloads (`twitch:stream_update`, `kick:stream_update`)

Both platforms report a channel-metadata change as the **new** state only. Lumio
diffs it against the last known state (the *baseline*) and adds what changed,
so the Events page and the chat inline event can show it:

| Field | Twitch | Kick | Meaning |
|-------|--------|------|---------|
| `title`, `category_name` | yes | yes | New title / category (game) |
| `language` | yes | yes | New broadcast language as the platform sends it (Twitch ISO 639-1 or `other`, Kick e.g. `en`) |
| `title_changed`, `category_changed`, `language_changed` | yes | yes | Whether that field changed |
| `old_title`, `old_category_name`, `old_language` | yes | yes | Previous value — only present when that field changed |
| `tags` | yes | — | Current channel tags (Helix `GET /channels`) |
| `tags_changed` | yes | — | Whether the tags changed (compared as a set — reordering alone is no change) |
| `old_tags` | yes | — | Previous tags — only present when they changed |

Rules (`apps/api/src/services/stream_update_diff.rs`):

- **No empty events.** An update where every `*_changed` flag is `false` (a
  redelivery, a change Lumio does not diff such as Kick's mature flag or
  Twitch's content-classification labels) is neither stored nor broadcast.
- **First observation is not a change.** A field is compared only when the
  baseline already knows it; the first observation records the baseline and
  emits nothing.
- **Twitch baseline** is seeded from Helix `GET /channels` (title, category,
  language, tags) every time the EventSub session (re)connects, so the first
  change after an API restart is reported. If that seed fails, the previous
  baseline stays.
- **Twitch tags** are not part of the `channel.update` payload; Lumio reads
  them from Helix `GET /channels` when `channel.update` arrives. If that call
  fails, the `tags*` fields are omitted — the title/category/language diff is
  still emitted. **Known limitation:** Twitch fires `channel.update` only for a
  change to the category, title, content classification labels or broadcast
  language — **a tag-only edit fires nothing**, so it is reported together with
  the next change that does fire.
- **Kick baseline** lives in Postgres (`platform_channel_metadata`, one row per
  account and platform), independent of the live status: Kick lets a streamer
  edit title and category while offline, and those edits are reported too. The
  baseline survives restarts; the start reconcile seeds title and category for
  a new connection (never overwriting an existing baseline), the first webhook
  fills the language. Kick has no tags.

#### Stream offline payloads (`*:stream_offline`)

`twitch:stream_offline`, `youtube:stream_offline` and `kick:stream_offline`
carry how long the stream ran. The two fields are added to the platform's
`raw` payload; no other field changes:

| Field | Type | Meaning |
|-------|------|---------|
| `started_at` | string, RFC 3339 (UTC) | When the stream started. For Kick it is Kick's own value, kept exactly as Kick sent it. |
| `duration_seconds` | integer ≥ 0 | `ended − started`, in whole seconds. For Kick, `ended` is Kick's `ended_at`; for Twitch and YouTube it is the moment Lumio processed the offline transition. |

**Both or neither.** When the start is unknown, or the computed duration would
be negative, both fields are absent - never `null` and never `0`. (For Kick, a
`started_at` Kick sent itself stays even then; only `duration_seconds` is
absent.)

Where the start comes from:

- **Twitch / YouTube** - the `channel_status.started_at` of the platform's
  online rows (`MIN` over them), read **before** the offline write clears it.
  Twitch sets it from EventSub `stream.online` `started_at` and, when the API
  starts mid-stream, from Helix `GET /streams` `started_at`, so a restart keeps
  the duration. YouTube discovery (InnerTube, no Data API quota) has no start
  time; Lumio stores the moment it first sees the broadcast live, so the YouTube
  duration can be up to one discovery poll short. The stored start does not
  move while the broadcast stays online (a title change does not reset it).
  After an API downtime in which a YouTube stream ended, the startup correction
  emits the offline event with the duration up to the correction.
- **Kick** - Kick's own `started_at` / `ended_at` from the
  `livestream.status.updated` webhook. If Kick's `started_at` is missing or
  unusable (Kick's zero timestamp), the start captured in `channel_status`
  fills it; if `ended_at` is missing, the time of receipt is the end.

The chat line and the events feed show the duration as a `clock` plaque
(`3h 12m`).

#### Types the platform workers actually emit

The `type` column on a `platform_event_logs` row is a free-form `VARCHAR(100)`,
so the ingest workers write several types that are **not** in the extension
catalogue above:

| Source | Additional emitted types |
|--------|--------------------------|
| Twitch EventSub (`workers/twitch_eventsub.rs`) | `twitch:gift` (sub gifts - the worker's name for what the extension catalogue calls `twitch:gift_sub`), `twitch:gift_upgrade`, `twitch:prime_upgrade`, `twitch:pay_it_forward`, `twitch:bits_badge`, `twitch:poll_delete`, `twitch:raid_out`, `twitch:raid_done`, `twitch:unraid`, `twitch:mod_added`, `twitch:mod_removed`, `twitch:vip_added`, `twitch:vip_removed` |
| Chat pin worker / Kick chat socket | `twitch:pin_added`, `twitch:pin_updated`, `twitch:pin_removed`, `kick:pin_added`, `kick:pin_removed` |
| Twitch IRC-tags listener (`workers/twitch_irc_tags.rs`) | `twitch:first_message` (first-time chatter - PRIVMSG `first-msg=1`), `twitch:watch_streak` (USERNOTICE `viewermilestone` / `watch-streak`; see [payload](#twitch-watch-streak-payload)) |
| Discord bot (`apps/discord-bot`) | `discord:member_join`, `discord:member_leave`, `discord:boost` |
| 7TV EventAPI (`workers/seventv_events.rs`) | `7tv:emote_added`, `7tv:emote_removed`, `7tv:emote_renamed`, `7tv:emote_set_switched` |

#### 7TV emote-set changes (`raw`)

The 7TV listener watches active emote sets belonging to connected Twitch, Kick,
and YouTube channels. Each change is stored once per account with
`platform = "7tv"` and an `external_id` that deduplicates replayed dispatches. These types
are stream events in `platform_event_logs`, not extension-subscribable types in
`LUMIO_EVENT_TYPES`. They use the existing `events:{account_id}` WebSocket
channel and its `events:read` guard; account-facing reads also require
`feature:events`. They are not audit events.

| Type | `raw` fields |
|------|--------------|
| `7tv:emote_added`, `7tv:emote_removed`, `7tv:emote_renamed` | `emote_id`, `emote_name`, `animated`, `emote_set_id`, `emote_set_name`, `actor`, `platforms`; rename also has `old_name` |
| `7tv:emote_set_switched` | New `emote_set_id`, `emote_set_name`, `emote_count`, `actor`, `platforms` |

`actor` contains the 7TV editor's `display_name` and `login` when known, without
an avatar or linked Lumio user. `platforms` lists the connected chat platforms
whose channels use the set. A 7TV row appears under **All** and those platform
tabs in chat, including server-merged history. Without `platforms` it appears
only under **All**. On the Events page, the **7TV** platform filter matches
these rows; a Twitch, Kick, or YouTube Events-page filter does not. The
Events-page type filters include all four types. The [7TV listener guide](/developer-guide/seventv-event-listener)
explains the subscription and cache behaviour.

History keeps each change separately and follows the account's normal event
retention window. Changes made before the listener ran, or during a complete
listener outage, are not backfilled by 7TV.

#### Twitch watch-streak payload

The `raw` payload of a `twitch:watch_streak` event:

| Key | Type | Notes |
|-----|------|-------|
| `user_id`, `user_login`, `user_name` | string | The viewer who shared the streak. |
| `streak_count` | number | Consecutive streams watched (`msg-param-value`). |
| `category` | string | Always `watch-streak`. |
| `message_id` | string | The IRC `id` tag. |
| `message_text` | string \| null | The viewer's optional shared message. |
| `emotes` | array \| null | Twitch emotes in the attached message, in the same shape as a chat message. |
| `system_message` | string | Twitch's system text for the notice. |
| `badges` | `ChatBadge[]` | Same shape as chat messages: `set_id`, `id`, `info`, `image_url`. Built from the `badges` / `badge-info` tags; `info` holds the `badge-info` value (the subscriber's cumulative months), `""` otherwise. **Always present** - a viewer without badges gets `[]`. `image_url` comes from the channel's Twitch badge cache (the one the EventSub worker builds) and is `null` when no image is known. |
| `color` | string \| null | Name colour as `#RRGGBB`; `null` when the viewer never set one. |
| `avatar_url` | string | Best effort, from the profile cache. **Omitted** when the profile is unknown, has no avatar, or the lookup fails or times out - the event is emitted either way. |

Events stored before `badges` existed have no `badges` key; consumers that gate
on badges (for example moderation actions) treat a missing key as "unknown" and
`[]` as "no badges".

#### Pin and Twitch role events

The five pin types are `twitch:pin_added`, `twitch:pin_updated`,
`twitch:pin_removed`, `kick:pin_added` and `kick:pin_removed`. The platform
worker writes a row only on a state transition; the `platform_event_logs`
rows are also the pin history protocol. They follow the account's ordinary
event retention. Every pin event has `raw.sender`; an added event also has
`raw.pinned_by` and, on replacement, `raw.replaced_sender`. Those people use
the shape
`{platform, user_id, login, display_name, avatar_url, color, badges}`.
Every event has `raw.message_id` and `starts_at`. An added event also has
`text`, `emotes` and `ends_at`; `raw.sent_at` is the message's write time
(Twitch stored chat message or Kick socket event), or `null` when unknown.
An update has `old_ends_at`, `new_ends_at` and `updated_at`. A removal has
`ends_at`, `ended_at`, `duration_seconds` and `reason`:
`unpinned`, `expired` or `message_deleted`; replacement identifies the old
message. Twitch removals observed by polling may have an approximate event
time. A viewer's support-tool erasure does not delete these channel-owned
event rows. See [Stream History](/features/stream-history) for the frozen
report and its separate person-data masking rules.

Twitch `channel.moderate` v2 yields `twitch:mod_added`,
`twitch:mod_removed`, `twitch:vip_added` and `twitch:vip_removed` for the
connected channel. Shared Chat partner actions are ignored. Every grant and
removal gets its own event, including quick toggles; the actor's action on
Twitch creates no Lumio audit event. `raw` carries the target as top-level
`user_id`, `user_login`, `user_name`, `avatarUrl` and `color`, and the actor as
`initiated_by`, `initiated_by_login` and `initiated_by_id`. Twitch does not
expose the Lead Moderator distinction, so the role is always Moderator.

Conversely, `twitch:ban` and `twitch:unban` appear in the extension catalogue
but are not written to `platform_event_logs` - Twitch ban/unban is handled on the
chat path (see [Chat](/features/chat#ban--timeout-sweep-chatclear_user)).

#### Community gift-sub bundling (Twitch)

A community gift of N subs arrives as N+1 EventSub notifications: one
`community_sub_gift` **header** plus N individual `sub_gift` notices that each carry
the same `community_gift_id`. The events panel and popout show only the header row -
the individual `sub_gift` rows are persisted for raw data but hidden by the history
filter (a `sub_gift` row with a `community_gift_id`). The header line itself is
broadcast the moment it is stored, so a bundle always reaches the live feed even if
no per-recipient notice ever arrives. The recipient names render from a
`giftRecipients` array patched onto the header - **all** of them, on every surface
(events feed, inline chat event line, and the user card): the list is never shortened
to the first few names with a "+N", and never clipped. It wraps and grows the row
instead, so a gift of any size names everyone who received one. The header also carries
an index-aligned `giftRecipientLogins` array with each recipient's login/handle, so the
client can show `name (login)` per recipient (Twitch only - YouTube gift memberships have
no per-recipient handle, so their bundles stay display-name only).

#### YouTube login twin (`user_login`)

Every InnerTube-sourced YouTube event (`youtube:superchat`, `youtube:supersticker`,
`youtube:member`, `youtube:gift_membership`, `youtube:gift_membership_received`)
carries a `user_login` field next to `displayName`, mirroring the Twitch login twin
so the events feed resolves the subject's login the same way on both platforms
(`apps/web/src/lib/event-user.ts`). It holds the channel `@handle` **with the `@`
stripped**. This twin still feeds bot variables, automations and moderation
(ZAF-1478); it is **not** shown as a render bracket, because the localized-name
bracket is gated to Twitch (ZAF-1452 / ZAF-1549 — see the localized-subject-names
note above). YouTube "channel title ≠ handle" is the normal case, so surfacing
`こさむん (@kosamun)` would fire on every non-Latin channel title — exactly the "not
on every chatter" the founder rejected. `formatPlatformName` therefore renders a
YouTube subject as the bare display name (`こさむん`). The `@`-prefix rendering is
retained in the helper (`decorateLoginForPlatform`) but unreachable while the
allowlist is Twitch-only; adding `"youtube"` to `LOCALIZED_DISPLAY_NAME_PLATFORMS`
would restore it with no other change.

That recipient list is **derived from the database**, not from in-memory correlation
state: every individual `sub_gift` row is persisted with its `community_gift_id`
regardless of arrival order, and finalisation reads the names back from those rows
(`lo_events::gift_recipient_names`, with the index-aligned logins from
`lo_events::gift_recipient_logins`). The worker keeps only a lightweight in-memory
arrival counter per bundle; it patches `giftRecipients` (and `giftRecipientLogins`)
onto the stored header and
re-broadcasts it - reusing the header's `id` + `created_at` so the live line and the
history row stay one event - when the counter reaches the header's `total` **or** when
a periodic timer ages the bundle out (so the enrichment fires even on a quiet channel
with no further traffic). The bundle tracker outlives WebSocket reconnects. A bundle
therefore lands its **complete** recipient list even when the individual notices
arrive before the header, when Twitch under-delivers them, or across a reconnect. If
no individual rows are persisted yet when a bundle is finalised, the header is left
un-enriched (its line already showed) and a startup backfill
(`lo_events::backfill_gift_recipients`, paginated over the full backlog) repairs it
once the rows land.

#### Internal WebSocket channel messages

These share the `namespace:action` shape but are transient pub/sub payloads, not
`platform_event_logs` rows: `chat:message`, `chat:delete`, `chat:clear_user`,
`chat:moderation_log`, `chat:user_treatment_update`, `channel:online`,
`channel:offline`, `copyright:blocked`/`:warning`/`:clear`,
`obs:action`/`:connection_lost`/`:low_bitrate`/`:high_dropped_frames`/`:recovery`,
`history:session_started`/`:session_updated`, `sound:play`, `overlay:update`,
`widget:update`, `storage:update`, `extension:updated`.

## Data Flow

1. Platform adapter detects an event (e.g., Twitch EventSub webhook receives a follow).
2. Event is inserted into TimescaleDB via `lo_events::insert_event()`.
3. Event is broadcast via `lo_events::broadcast_event()` through Redis pub/sub.
4. WebSocket server forwards the event to all connected clients for the account.
5. Overlay alerts render the event. The Events page, home event panel, and popout update in real time.
6. Users can query historical events with filters and pagination via `events` query.

## Motion preferences

Events follows the user's [Animations in Lumio](/user-guide/preferences#animations-in-lumio) preference. Its settings panel can tighten motion for this view per browser and user/account pair, and `?motion=reduced|off` can tighten one popout URL. New event rows fade briefly at Reduced and appear immediately at Off; scrolling is instant at either level. The seasonal animation row affects decoration only. See the [Motion developer guide](/developer-guide/motion).

## Settings export/import (browser-local)

The events display options (`popout-settings:events`) and the event filters
(`lumio:event-filters`, which platforms/types are shown) are part of the shared,
browser-local settings export/import feature (ZAF-622). A user can save them and
re-import them on another device or an OBS source; it is purely client-side (no
API/RBAC/audit). Four transports carry the same envelope - a copy-pasteable `LS1…`
**code string**, a **share link** (the same code in a URL fragment, so still no
server), **Copy JSON**, and a downloaded **file** - and the import auto-detects a
pasted file, code, or link in one field. The `events.filters` payload keeps its
`allPlatforms`/`allTypes` markers so newly shipped event types auto-enable on the
next load rather than being silently hidden by an older file. See the full format,
transports, section list, exclusions and import semantics in the
[Multichat feature doc](./chat.md#settings-exportimport-browser-local).

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/events.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/events.rs` | REST endpoints |
| `crates/lo-events/src/` | Core events crate - TimescaleDB insert/list plus Redis broadcast and the filter types |
| `apps/api/src/workers/event_relay.rs` | Relays platform-worker events onto the account's WebSocket channel |
| `packages/protocol/src/events.ts` | `LUMIO_EVENT_TYPES` / `ACTION_TYPES` enums consumed by the extension SDK |
| `apps/web/src/components/events-shell.tsx` | Shared live-feed component behind the Events page, dashboard panel, and popout |
| `apps/web/src/hooks/use-event-filters.ts` | Browser-local event-filter state; also exports `parseStoredEventFilters`/`expandEventFilters` reused by the settings export/import registry |

---

## Features / Setting Presets

Source: https://docs.lumio.vision/features/setting-presets

# Setting Presets

## Overview

Setting presets are **named snapshots** of a user's Multichat, Events or Music display settings, saved to the Lumio account so they can be reused later and across devices - for example switching between a "Stream" and a "Chill" layout, or seeding a fresh OBS browser source with a known configuration.

The design keeps `localStorage` as the **live state**: a preset is written **only** when the user explicitly saves one and read **only** when they select one. There is no implicit background sync, so there are no conflict semantics, no migration of existing browser data, and nothing changes for OBS when the server is unreachable - the presets list simply isn't available then.

## Using presets

Presets live in a **Presets tab** inside the settings panel of Multichat, Events and Music - the same panel the gear icon opens, in both the dashboard and the popout. Because Events and Music previously had a single flat settings column, adding the Presets tab gives those two surfaces a **tab bar** for the first time (Multichat already had one for General / Events / Filters).

The tab has:

- A header with a **New preset** button and a quota line ("3 of 5 used"; `0` shows as an unlimited "N saved").
- A **card per preset** of that surface's kind, showing the name, when it was last changed, a **Default** badge where applicable, and how many settings sections it holds. Each card offers:
  - **Load** - apply the snapshot to this browser (replace semantics; the page reloads so every open view picks up the new settings).
  - **Share** (share icon) - open the [share dialog](#sharing-with-your-account) for that preset: copy a **code** or a **share link**, and (with `presets:share` and an active account) toggle whether it is visible to the whole account. The share icon is highlighted while the preset is shared with the account.
  - **Overwrite** (gear icon) - re-save the preset with your current settings, after a confirmation.
  - **Rename** (pencil icon) - rename the preset (and optionally mark it as the kind's default).
  - **Delete** (trash icon) - remove the preset, after a confirmation.

**Saving** opens a full-screen assistant (the same shape as creating a keyword rule): first choose *which* of your current settings to store (the same section list as the export dialog), then give the preset a name and optionally set it as the default.

Below the card list, a **Shared from the channel** section lists presets a teammate has [shared into the account](#sharing-with-your-account). These cards show the name, the owner's display name, the section count and the last-changed time, and offer only **Load** and **Save as your own preset** (which copies the shared snapshot into your own quota-counted list). They carry no overwrite / rename / delete / share - those stay owner-scoped. The section is hidden when nothing is shared into the account.

Below that sits the [export / import](#exporting-and-importing) controls (moved here from the old General tab).

In a **popout** (an OBS browser source authenticated by a popout token) the list is read-only in one direction: you can **Load** a preset (your own; the shared-from-the-channel section never appears over a popout token), but the create / overwrite / rename / delete / share and "save as your own" actions are hidden - presets are authored in the dashboard and loaded in the popout. Export / import stays available in the popout because it is purely local.

## Default preset

Each **(user, account)** may mark **one preset per kind** as its **default** (from the save / rename assistant; the card's **Default** badge marks the current one). The default is applied **automatically the first time** that surface (Multichat, Events or Music) is opened for that pair in a given browser - which is what makes it useful on a **new device or a fresh OBS browser source**: your saved view is seeded there without you re-entering it, popout included.

The seeding is deliberately conservative:

- **Only when the surface is pristine.** The default is applied **only if no settings blob exists yet** for that `(user, account, kind)` in this browser - "no blob" meaning the key is *absent*, not "the blob holds factory values". An existing local state is **never** overwritten, so the seed never fights a view you are already editing.
- **Once per pair.** It runs at most once per `(user, account)` + surface; a second mount never re-applies and never resets an in-progress change.
- **Per (user, account), never global.** The default comes from that pair's own presets, so a second account never inherits the first account's default, and a different team member on the same account starts from *their* own default (or factory).
- **Fail-open.** If the default cannot be resolved (offline, the presets list errors, or no default is set) the surface renders its normal factory defaults - never a blank view.

Marking a default writes nothing to any browser by itself; it only records which preset is seeded the next time a pristine surface mounts. Loading a preset by hand (the **Load** button) is unchanged and always available, whether or not a default is set.

## Scope: per (user, account)

A preset belongs to the pair **(user, account)** (ZAF-622 §52c, founder ruling 2026-09-17) - it is "my view **on this channel account**", not a global per-user view. Each Lumio account needs its own filters, keyword tabs and keys, so a preset created in one account is neither visible nor loadable from another. Creating, editing, renaming, overwriting, deleting and setting-default a preset are all scoped to *(the authenticated user, their active account)* with no `resource:action` RBAC permission: one user can never mutate another user's presets, and no user can reach a preset in an account they are not a member of. The **one** RBAC gate on the surface is `presets:share` - the act of sharing a preset with your account (see [Sharing with your account](#sharing-with-your-account)).

"Channel account" here means the **Lumio account** (`accounts.id` / `me.activeAccountId`), not a single platform connection - one account holds one connection per platform, and the Multichat is one cross-platform window.

Each preset has a **kind** - `chat`, `events`, or `music` - and the presets list is filtered by kind (a chat preset never appears in the events panel). A user may mark **one default per (account, kind)** - so the same user can keep an independent chat default in each of their accounts.

**Fail-closed on membership.** Because a preset is keyed `(user_id, account_id)`, a preset in an account you have **left** is neither readable nor writable, even by its own owner - every read/write re-checks that the row's owner is still a member of the account (its `owner_id` or an `account_memberships` row). The preset row survives (it is removed only when its account is deleted, via `ON DELETE CASCADE`), so an operator can still find it by user; you simply cannot reach it once you leave.

Since ZAF-622 §52b **every** captured setting - the display options *and* the Multichat filter/highlight lists, keyword tabs, alerts and send-platform selection - is keyed to the same *(you, the channel account you are on)* pair. There is no longer a "display follows the browser profile, filters follow the account" split (the old §49 model): a **preset is "my view on this account"**. So loading a preset applies your saved view *into the (you, current account) pair*; switching to another channel account, or signing in as a different team member, still starts those settings from defaults until you load a preset or import them, and a preset is the way to carry a view to a new browser or an OBS source **within that account**.

## Sharing with your account

A user can **share** one of their own presets with the **members of their active account** so the team can load ("use") it in their own dashboard or OBS popout (ZAF-622 §19, E9 Variante A). The **Share** icon on a preset card opens a dialog with two independent ways to hand it over:

- **Code / link (local, no account needed).** A copy-pasteable **code** and a **share link** built straight from the preset's stored snapshot - the exact same transport the [settings export/import](#exporting-and-importing) feature uses (a preset's payload *is* the export envelope). The link carries the code in its URL fragment, which never reaches the server, so this stays purely client-side: no endpoint, no audit event. When the payload holds viewer-name data (chat filter lists or keyword tabs) the dialog shows the "contains your viewer names" note, because a code/link is reversible cleartext.
- **Account visibility (the switch).** A **"Visible to all members of {account}"** switch - shown only with an active account and the `presets:share` permission - that shares the preset with, or un-shares it from, the account. The note spells out that every member can see and load it (but not edit, delete or re-share it).

- **One boolean column, `setting_presets.shared`.** `false` = private; `true` = shared with the members of the preset's **own** account. Because a preset is bound to exactly one account (`account_id`), "shared" can only ever mean "shared with *this* account's members" - a boolean that cannot contradict itself, and that makes cross-account sharing **impossible by construction** (a preset built for account A can never appear in account B's team list). On the wire the API still exposes `shared_account_id` for contract stability, derived as *the preset's own account id when shared, else `null`*.
- **Sharing is a flag, not a copy.** Sharing sets `shared = true` on the existing row (idempotent). It costs **no** quota: `count_presets` counts only the owner's own rows in the account. Loading a shared preset writes nothing server-side (it only updates the reader's `localStorage`), so it costs the reader **no** quota either. Only an explicit "save as my own" creates a real row under the reader's `(user_id, account_id)` and runs the normal atomic quota gate.
- **Read side (membership re-checked, fail-closed).** A first-party member of the account sees, alongside their own presets, every preset shared into that account **whose owner is still a member at read time** (the account's `owner_id`, or an `account_memberships` row). Once the owner leaves the account the shared preset disappears from the team's list even though `shared` is still set. Foreign shared rows are flagged `shared: true` and carry the owner's `owner_display_name` (no e-mail, no other user data).
- **First-party only.** The shared branch is surfaced only to a **first-party** principal (logged-in session / own API key). Over a **popout / overlay token the list stays restricted to your own presets** - a popout authenticates as the member it is bound to (possibly the owner), so surfacing the shared branch there would leak the whole team's presets into an OBS source.
- **Foreign presets are read + load only.** `update` / `overwrite` / `setDefault` / `delete` / `unshare` stay owner + account scoped (`WHERE id = ? AND user_id = ? AND account_id = ?`); a member can never mutate a preset shared by someone else.

Sharing (and un-sharing) requires the granular **`presets:share`** account permission, granted by default to **Owner, Administrator and Moderator**. Reading the shared section needs no permission - account membership is enough; the person who shared is told in the UI that every member of the account can see it.

## Exporting and importing

The settings **export / import** controls (export the current settings to a file, clipboard, code string or share link; import a file / pasted code / link) live in the **Presets tab**, below the card list. Export / import is **plan-free** - it works even on plans without the presets feature. On such a plan there is no Presets tab, so the same controls appear instead at the bottom of the **General tab**. Exactly one of the two locations is shown per session; export / import is never both missing and never duplicated. Because it is purely local, it is rendered outside the presets list's own load path, so it keeps working even if the presets list itself fails to load.

When you **import** a code, link or file, the preview offers - alongside **Apply** (write the settings into this browser) - a **Save as preset** button that stores the imported snapshot directly as a new preset of the current surface's kind, without the "apply, reload, re-save" detour. It is disabled (with the same "limit reached" message as *New preset*) when your preset quota is full.

## Quota

The number of presets a user may keep in an account is a per-plan limit, `plans.max_setting_presets`, spanning **all kinds combined** (one number, not three). The default quotas are **Free = 5** and **Pro = 20**. It is overridable per account via `account_limits.max_setting_presets`, resolved as `COALESCE(account_limits.x, plans.x)`. The quota is **per account** (ZAF-622 §52c): the count and the limit both belong to the active account, so a full account never blocks a different one, and each account's number comes from **its own** plan (plus any override) - there is no "best plan across the accounts you can reach" walk.

This answers the common question "if this account is on Pro, do its members get the Pro preset quota **here**?" - **yes**: the limit is the account's own plan value (20 on Pro), the same for every member of that account. An account-limit override raises (or lowers) the number for that one account. A user who belongs to a Pro account *and* a Free account gets 20 presets in the Pro account and 5 in the Free account - the quotas do not bleed across accounts.

`0` means **unlimited** (the platform-wide convention). The create path enforces the quota **atomically** (a per-`(user, account)` advisory lock plus a count-gated insert), so two browser tabs saving at the limit at the same time cannot both slip through.

The quota is exposed **read-only** as `settingPresetQuota` (GraphQL) and its REST twin `GET /v1/setting-presets/quota`, which return `used` (your own presets in the active account across all kinds) and `limit` (`0` = unlimited). The presets UI reads that one field to render the "N of M used" line and to disable *New preset* / *Save as preset* when the quota is full, without having to create a preset first. Both numbers are resolved by the very functions the create path gates on, so the warning can never disagree with the server's rejection.

Like the rest of the presets surface the quota read is **user-scoped within the account**: it needs no `resource:action` permission, only authentication plus `feature:setting_presets`, and it is popout-token readable. It is deliberately **not** gated on the account permission `plan:read` - routing it through `accountLimits` (which is, correctly, an account-scoped plan read) left every member without that permission with no limit at all, so the warning silently vanished and the cap only surfaced as an error on save. `maxSettingPresets` still exists on `accountLimits` / `GET /v1/billing/account-limits` as the account-scoped plan view for billing surfaces. Neither read carries an audit event: this is personal display/plan information, not a security-relevant action.

### Operator control (AdminApp)

Platform operators adjust the quota from the AdminApp - no SQL required:

- **Per plan** - the plan create/edit form carries a **Max Setting Presets** field (`0` = unlimited), gated on `plans:edit`.
- **Per account** - the account detail limits form carries a **Max Setting Presets** override (empty = inherit the plan, `0` = unlimited), gated on `accounts:edit`. Both account-limit write paths (the full "limits" upsert and the partial "resolved-limits" update) persist the column, and both emit the `system:account_limits_updated` audit event.

Operators can also **delete** a user's presets (see [Deleting presets as an operator](#deleting-presets-as-an-operator) below).

## Feature flag

Presets are gated by the `feature:setting_presets` feature flag (category `feature`), with paired `plan_features` rows so the entitlement is fail-closed. The flag is the *whether* (presets available at all); the `max_setting_presets` column is the *how much*.

## Popout access

The **read** endpoints work with a **popout token**, so the OBS-source popout can list and load presets - the place the feature is most useful (though a popout only ever sees the caller's **own** presets, never the shared team section). The **write** endpoints (create, update, delete, set-default, **share, unshare**) require a **first-party user session** (a logged-in user or the user's own API key); a popout/overlay/widget/extension token is rejected. This is deliberate: a popout token authenticates as the member it is bound to, which is not necessarily the person holding the URL, so allowing writes there would let whoever holds the token act as that member. Authoring happens in the dashboard; the popout only loads.

## Deleting presets as an operator

An operator manages presets by the **owning user** from the **user detail page** in the AdminApp, which lists **all** of that user's presets across every account (name, kind, default badge, last-changed - never the payload) with a **Delete** action. The account detail page mirrors the same list per member for convenience. Both surfaces call the same endpoints:

- **GraphQL:** `adminUserSettingPresets(userId)` (query, `users:read`), `adminDeleteUserSettingPreset(id)` (mutation, `users:edit`).
- **REST:** `GET /v1/admin/users/{id}/setting-presets` (`users:read`), `DELETE /v1/admin/setting-presets/{id}` (`users:edit`).

Deleting a preset removes that single `(user, account)` row - a preset lives in exactly one account, so there is no cross-account copy to clean up. The delete emits the `system:user_setting_preset_deleted` audit event (target user id + preset id/kind, never the payload).

## Audit logging

**User** preset changes (create / rename / overwrite / set-default / self-delete) emit **no audit event**. The audit log is a security record for security-relevant, tenant-visible or irreversible actions; a personal display setting is none of those (the same reasoning as notification preferences). Note this is *not* justified by "the data never leaves the browser" - with server-side presets it does - but by the action not being security-relevant.

**Sharing** a preset with your account **does** emit, because it makes personal data (a preset payload can hold viewer names) visible to other account members - a tenant-visible disclosure. Sharing emits `account:setting_preset_shared` and un-sharing emits `account:setting_preset_unshared`, both **`account`**-scoped (keyed to the preset's account, with the acting owner as the actor), on both GraphQL and REST. The metadata carries only the preset id, kind and name - **never** the payload. Un-sharing fires only when a share was actually removed.

**Operator** actions do emit, because an operator acts on another tenant's/user's data: deleting a user's preset emits `system:user_setting_preset_deleted`, and changing an account's numeric limits (including the preset quota) emits `system:account_limits_updated`. Both are `system`-scoped (platform-operator log only) - see [Audit events](../developer-guide/audit-events.md).

## Privacy

A preset's payload can include entries the user typed themselves - in particular chat **filter terms** and **keyword-tab names** - which may contain viewer usernames. These are the user's own account data; they are disclosed in the privacy policy and are deleted with the user's account (the table is attached to the account/erasure path by an `ON DELETE CASCADE` on the owning user).

## API

Full parity on GraphQL and REST:

- **GraphQL:** `settingPresets`, `settingPreset` (queries); `createSettingPreset`, `updateSettingPreset`, `setDefaultSettingPreset`, `deleteSettingPreset`, `shareSettingPreset`, `unshareSettingPreset` (mutations). See [GraphQL API](../api-reference/graphql.md#setting-presets).
- **REST:** `GET/POST /v1/setting-presets`, `GET/PATCH/DELETE /v1/setting-presets/{id}`, `POST /v1/setting-presets/{id}/default`, `POST/DELETE /v1/setting-presets/{id}/share`. See [REST API](../api-reference/rest-api.md#setting-presets).

The `settingPresets` list result marks each foreign shared row with `shared: true` + `owner_display_name`; own rows are `shared: false`. `shareSettingPreset` / `unshareSettingPreset` and their REST twins require `presets:share`; the share target is always your active account.

---

## Features / Overlays

Source: https://docs.lumio.vision/features/overlays

# Overlays

## Overview

The Overlays module provides a custom streaming overlay editor where users can create, configure, and manage overlays with layered widgets. Each overlay has a unique key used for popout access in browser sources. Overlays support configurable dimensions, background settings, and multiple layer types (alerts, chat, music, custom HTML/CSS). Layers are ordered by `sort_order` and can be individually toggled visible/hidden.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/overlays.rs`) -- Full CRUD for overlays and layers. Queries for listing/fetching overlays and their layers. Mutations for create, update, delete overlays and bulk-replace layers.
- **Database** (`apps/api/src/db/overlays.rs`) -- PostgreSQL operations for overlays and overlay_layers tables. Includes `generate_overlay_key()` which creates a 12-character URL-safe random key.
- **Browser Source Access** -- Overlays render at `/overlay/[key]?token=…`. The `token` is the overlay's own **Overlay Access Token** (`lm_overlay_*`) or a temporary **Shared Overlay Token** (`lm_share_*`) - not a popout token. The page returns `403 - Access token required` when the query parameter is absent.

### Frontend

- Overlay editor UI in the Next.js web app under `/dashboard/overlays`.
- The browser-source renderer (`apps/web/src/app/(overlay)/overlay/[key]/`) loads via the unique overlay key and passes the access token straight into the WebSocket URL.
- Layer configuration per layer type (alert config, chat style, music widget config, custom HTML/CSS/JS).
- Extension layers (`type: "ext:{slug}"`) mount the installed extension inside the layer's box when the overlay's account has the extension installed and enabled. The extension runs with the overlay's own token, so it can use `useLumioAction()` for every action except chat actions (`chat:*`), which an overlay link may never trigger. Without an enabled install the layer stays empty on stream.
- OBS connection parameters can be supplied to a shared link through `obs_host` / `obs_port` / `obs_password` query parameters; for a permanent token they come from the overlay's stored bootstrap configuration instead.

### Token Types on Overlay Surfaces

Three different tokens appear around overlays; they are not interchangeable:

| Token | Prefix | Used for |
|-------|--------|----------|
| Overlay Access Token | `lm_overlay_*` | The overlay's own permanent Browser Source URL (`/overlay/[key]`) |
| Shared Overlay Token | `lm_share_*` | Time-limited shared access to one overlay |
| Popout Token | `lm_pop_*` | Dashboard popout views (`/popout/[view]`) - carries RBAC permissions, unlike the two above |

Dashboard popout views and the API hooks behind them authenticate with a popout
token rather than a session cookie, so every hook they use must accept
popout-token auth as well as cookie auth. The overlay browser source is the
opposite case: its token carries **no** RBAC permissions and can reach only the
overlay's WebSocket channel.

The permanent Overlay Access Token (and the equivalent Widget Access Token) is
stored **AES-256-GCM-encrypted at rest**, the same pattern as `app_credentials`:
auth resolution keys on the token **hash**, and the encrypted copy exists only so
the dashboard can decrypt it on demand to rebuild the Browser Source URL - the
cleartext never sits in the database. Resolution is additionally gated on
`revoked_at` / `expires_at` on every request, like the popout and shared-overlay
tokens. Rotating a token (`copyOverlayUrl`) is a de-facto revocation of the old
one.

## API

### GraphQL Queries

Every overlay query and mutation is gated by a feature flag **and** an RBAC
permission, composed as `FeatureGuard::new(<flag>).and(PermissionGuard::new(<permission>))`
on GraphQL and as `auth.require_permission(…)` + `require_feature(…)` on REST.
The flag differs by area: core CRUD uses `feature:overlays`, folders use
`feature:overlay_folders`, per-overlay access control uses `feature:overlay_access`,
and shared links use `feature:overlay_sharing`.

| Query | Feature | Permission | Description |
|-------|---------|-----------|-------------|
| `overlays` | `feature:overlays` | `overlays:read` | List all overlays for the account |
| `overlay(id: UUID)` | `feature:overlays` | `overlays:read` | Get a single overlay by ID |
| `overlayLayers(overlayId: UUID)` | `feature:overlays` | `overlays:read` | Get all layers for an overlay, ordered by `sortOrder` |
| `overlayAccessUrl(overlayId: UUID)` | `feature:overlays` | `overlays:read` + **Editor** access | Return the overlay's Browser Source URL from the **stored** token, without rotating it. Handing out the cleartext `lm_overlay_*` token requires **Editor**-level access to the overlay (mirrors `copyOverlayUrl`), not merely `overlays:read` - a read-only Viewer cannot fetch it. `null` when the overlay has no retrievable token. |
| `overlayFolders` | `feature:overlay_folders` | `overlays:read` | List the account's overlay folders |
| `overlayAccess(overlayId)` | `feature:overlay_access` | `overlays:access-read` | List per-overlay access entries |
| `overlayAccessCandidates(overlayId)` | `feature:overlay_access` | `overlays:access-read` | List members who can be granted access |
| `overlaySharedLinks(overlayId)` | `feature:overlay_sharing` | `overlays:edit` | List the overlay's temporary shared links |

### GraphQL Mutations

| Mutation | Feature | Permission | Description |
|----------|---------|-----------|-------------|
| `createOverlay(input: CreateOverlayInput)` | `feature:overlays` | `overlays:create` | Create a new overlay (defaults: 1920x1080, "transparent" background, "Main Overlay" name) |
| `updateOverlay(input: UpdateOverlayInput)` | `feature:overlays` | `overlays:edit` | Update overlay name, dimensions, or background |
| `updateOverlayLayers(overlayId: UUID, layers: JSON)` | `feature:overlays` | `overlays:edit` | Bulk-replace all layers for an overlay. Each layer has: type, name, config (JSONB), visible, sort_order. Optionally include id to preserve identity. |
| `deleteOverlay(id: UUID)` | `feature:overlays` | `overlays:delete` | Delete an overlay and all its layers |
| `copyOverlayUrl(overlayId: UUID)` | `feature:overlays` | `overlays:edit` | Rotate the overlay access token and return the fresh Browser Source URL. The previous URL stops working immediately. |
| `revokeOverlayToken(overlayId: UUID)` | `feature:overlays` | `overlays:edit` | Destroy the overlay access token without re-issuing one |
| `moveOverlay(overlayId: UUID, folderId: UUID)` | `feature:overlay_folders` | `overlays:edit` | Move an overlay into a folder; `null` moves it back to root |

### REST Endpoints

Bodies are snake_case and mirror the GraphQL inputs.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/overlays` | `overlays:read` | List overlays for the account |
| `POST` | `/v1/overlays` | `overlays:create` | Create an overlay |
| `GET` | `/v1/overlays/{id}` | `overlays:read` | Get an overlay with its layers |
| `PATCH` | `/v1/overlays/{id}` | `overlays:edit` | Update name, dimensions, background, or layers |
| `DELETE` | `/v1/overlays/{id}` | `overlays:delete` | Delete an overlay and its layers |
| `POST` | `/v1/overlays/{id}/copy-url` | `overlays:edit` | Rotate the access token and return the fresh Browser Source URL |
| `POST` | `/v1/overlays/{id}/revoke-token` | `overlays:edit` | Revoke the access token without re-issuing |
| `POST` | `/v1/overlays/{id}/move` | `overlays:edit` | Move the overlay into a folder (`feature:overlay_folders`) |

The same feature flags apply on REST. Note that `apps/api/openapi.json` currently
registers only the core five plus `move` - `copy-url`, `revoke-token`, the access
endpoints and the shared-link endpoints are served but are not listed in the
generated OpenAPI document.

There is no REST route for reading an overlay's layers on their own or for the
stored Browser Source URL; use the `overlayLayers` and `overlayAccessUrl`
GraphQL queries. The web dashboard reaches both through its Next.js proxy routes
(`/api/overlays/[id]/layers`, `/api/overlays/[id]/url`), which execute those
GraphQL operations server-side.

### Input Types

**CreateOverlayInput:**
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `name` | `String?` | `"Main Overlay"` | Overlay name |
| `width` | `i32?` | `1920` | Canvas width in pixels |
| `height` | `i32?` | `1080` | Canvas height in pixels |
| `background` | `String?` | `"transparent"` | Background color/value |

**UpdateOverlayInput:**
| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID` | Overlay ID (required) |
| `name` | `String?` | New name |
| `width` | `i32?` | New width |
| `height` | `i32?` | New height |
| `background` | `String?` | New background |

## Permissions

| Permission | Description |
|-----------|-------------|
| `overlays:read` | View overlay configuration and layers |
| `overlays:create` | Create new overlays |
| `overlays:edit` | Edit overlay settings and layers |
| `overlays:delete` | Delete overlays |

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `overlays` | PostgreSQL | id, account_id, name, key (unique 12-char URL-safe string), width, height, background, created_at, updated_at |
| `overlay_layers` | PostgreSQL | id, overlay_id (FK), type (layer type string), name, config (JSONB), visible (bool), sort_order (int), created_at, updated_at |
| `overlay_access_tokens` | PostgreSQL | id, overlay_id (FK, unique), account_id (FK), token_hash (SHA-256, unique), created_at. One token per overlay; cascade-deleted with the overlay. |

### Overlay Key Generation

The `generate_overlay_key()` function creates a 12-character random string using characters `A-Z`, `a-z`, `0-9`, `-`, `_`. This key is used in the popout URL: `/overlay/[key]?token=xxx`.

## Access Tokens

Each overlay is protected by a dedicated access token (`lm_overlay_*` prefix). The token is a 75-character hex-encoded string stored as a SHA-256 hash in the `overlay_access_tokens` table. Access requires both the overlay key (in the URL path) and a valid token - a two-secret-layer model that prevents unauthorized subscribes even if one value leaks.

### Security Model

- Anonymous WebSocket subscribes to `overlay:{key}` channels are blocked. `channel_gate_for("overlay")` returns `ChannelGate::OverlayToken`, which requires an `AuthContext::OverlayToken` whose `overlay_id` matches the overlay resolved from the channel key - so one overlay's token cannot subscribe to another's channel.
- The server re-validates the token against the database every 30 seconds, throttled inside the 5-second heartbeat tick. The check reads the token hash, so a rotated, revoked or deleted token causes a disconnect with `TOKEN_REVOKED` on the next check (rotation keeps the row id, but the old secret no longer matches). There is no validity cache that could keep a revoked token alive.
- The re-validation query has a 500 ms timeout and **fails closed**: one timeout or database error keeps the last (valid) result once, a second one in a row disconnects the browser source with `AUTH_UNAVAILABLE`, and it reconnects with backoff. See [Credential re-validation](../api-reference/websocket.md#credential-re-validation).
- The token carries no RBAC permissions and cannot access REST or GraphQL endpoints.
- The `overlay` channel type has no entry in `channel_feature_for`, so the WebSocket layer applies no plan-feature gate to it; the plan check happens when the overlay and its token are managed through GraphQL/REST.

### Token Lifecycle

| Event | Behavior |
|-------|----------|
| Overlay creation (`createOverlay`) | A token is auto-issued and returned in the response |
| Copy URL (dashboard button) | The existing token is revoked and a fresh token is issued (auto-rotation). The old URL stops working immediately. |
| Revoke (`revokeOverlayToken`) | The token is destroyed without re-issue. Use for compromise emergencies - the overlay becomes inaccessible until a new URL is copied. |
| Overlay deletion | The token is cascade-deleted with the overlay row |

### Transport

The token is passed via `?token=lm_overlay_…` query parameter (primary, for browser sources) or `Authorization: Bearer lm_overlay_…` header.

### OBS Setup

1. Open the overlay editor in the Lumio dashboard.
2. Click **Copy URL** - this generates a fresh token and copies the full URL to the clipboard.
3. In OBS, add a Browser Source and paste the URL.
4. The browser source connects automatically; no further configuration is needed.

### Overlays Without a Token

An overlay can exist without an access token - for example after `revokeOverlayToken`, or for rows that predate the token requirement. `overlayAccessUrl` returns `null` for such an overlay and its URL grants no WebSocket access. Clicking **Copy URL** (`copyOverlayUrl`) issues a token and produces a working URL.

## Data Flow

1. User creates an overlay via the editor. A unique key and access token are generated.
2. User adds layers (alert, chat, music, custom) and configures each one.
3. Layers are saved via `updateOverlayLayers` mutation (bulk replace).
4. The overlay is accessed in OBS via its URL containing the overlay key and access token.
5. The popout page loads the overlay and all its layers, connecting to WebSocket for real-time updates using the access token for authentication.

## Folders

Overlays can be organized into flat folders (one level, no nesting). Each account has unique folder names.

### Creating Folders

- **GraphQL:** `createOverlayFolder(name: String!)` - requires `overlays:create` permission and `feature:overlay_folders` feature flag
- **REST:** `POST /v1/overlay-folders` - body: `{ "name": "..." }`

### Moving Overlays

- **GraphQL:** `moveOverlay(overlayId: UUID!, folderId: UUID)` - pass `null` for `folderId` to move back to root
- **REST:** `POST /v1/overlays/{id}/move` - body: `{ "folder_id": "..." | null }`

Requires `overlays:edit` permission, `feature:overlay_folders` feature flag, and per-overlay editor access.

### Folder Management

| Operation | GraphQL | REST | Permission |
|-----------|---------|------|------------|
| List | `overlayFolders` | `GET /v1/overlay-folders` | `overlays:read` |
| Create | `createOverlayFolder` | `POST /v1/overlay-folders` | `overlays:create` |
| Rename | `renameOverlayFolder` | `PATCH /v1/overlay-folders/{id}` | `overlays:edit` |
| Delete | `deleteOverlayFolder` | `DELETE /v1/overlay-folders/{id}` | `overlays:delete` |

All folder endpoints require `feature:overlay_folders` to be enabled for the account's plan.

## Access Control

Per-overlay member access control refines the account-level RBAC permissions. Users with `overlays:access-read` (Owner and Administrator roles by default) bypass all per-overlay restrictions.

### Access Levels

| Level | Can View | Can Edit |
|-------|----------|----------|
| Viewer | Yes | No |
| Editor | Yes | Yes |
| No Access | No | No |

### Resolution Logic

`db::overlay_access::can_access_overlay` resolves in this order:

1. Verify the overlay actually belongs to the caller's account. A mismatch is denied outright - this runs **first**, so the `overlays:access-read` bypass can never reach another account's overlay.
2. If the caller has `overlays:access-read` → full access (bypass)
3. If the caller lacks `overlays:read` → no access
4. If the auth context has no `user_id` → no access (a per-overlay entry is keyed on a user)
5. If no per-overlay entry exists → default Viewer access
6. If entry has role `none` → blocked
7. If entry has role `editor` → full access
8. If entry has role `viewer` → view only

Steps 5–8 are shared with other per-resource access checks via `db::resource_access::resolve_access`.

### Endpoints

| Operation | GraphQL | REST | Permission |
|-----------|---------|------|------------|
| List access | `overlayAccess(overlayId)` | `GET /v1/overlays/{id}/access` | `overlays:access-read` |
| Set access | `setOverlayAccess(overlayId, userId, role)` | `PUT /v1/overlays/{id}/access/{userId}` | `overlays:access-grant` |
| Remove access | `removeOverlayAccess(overlayId, userId)` | `DELETE /v1/overlays/{id}/access/{userId}` | `overlays:access-revoke` |
| List candidates | `overlayAccessCandidates(overlayId)` | `GET /v1/overlays/{id}/access/candidates` | `overlays:access-read` |

All access control endpoints require `feature:overlay_access` to be enabled.

## Shared Links

Temporary shared overlay links allow time-limited access to a specific overlay without requiring account membership. Links use the `lm_share_` token type (7th authentication type).

### Token Format

- Prefix: `lm_share_` (9 characters)
- Body: 32 random bytes, hex-encoded (64 characters)
- Total length: 73 characters
- Storage: SHA-256 hash in database

### Allowed Durations

Links can be created with one of five fixed durations:

| Duration | Seconds |
|----------|---------|
| 1 hour | 3600 |
| 3 hours | 10800 |
| 6 hours | 21600 |
| 12 hours | 43200 |
| 24 hours | 86400 |

### Endpoints

| Operation | GraphQL | REST | Permission |
|-----------|---------|------|------------|
| List | `overlaySharedLinks(overlayId)` | `GET /v1/overlays/{id}/shared-links` | `overlays:edit` + editor |
| Create | `createOverlaySharedLink(overlayId, durationSecs)` | `POST /v1/overlays/{id}/shared-links` | `overlays:edit` + editor |
| Extend | `extendOverlaySharedLink(linkId, durationSecs)` | `PATCH /v1/overlay-shared-links/{id}` | `overlays:edit` + editor |
| Revoke | `revokeOverlaySharedLink(linkId)` | `DELETE /v1/overlay-shared-links/{id}` | `overlays:edit` + editor |

All shared link endpoints require `feature:overlay_sharing` to be enabled.

### WebSocket Access

Shared links authenticate via the `?token=lm_share_...` query parameter on WebSocket connections. The token grants subscription to the overlay's WebSocket channel (`overlay:{key}`). The server performs periodic heartbeat checks:

- **In-memory expiry:** checked every heartbeat tick (5s) - disconnects with `TOKEN_EXPIRED`
- **DB revocation:** checked every 30 seconds by the [credential re-validation](../api-reference/websocket.md#credential-re-validation) - disconnects with `TOKEN_REVOKED`

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/overlays.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/overlays.rs` | REST handlers (`/v1/overlays`, `/v1/overlay-shared-links`) |
| `apps/api/src/routes/overlay_folders.rs` | REST handlers for `/v1/overlay-folders` |
| `apps/api/src/db/overlays.rs` | Database operations, key generation, access-token issuance |
| `apps/api/src/db/overlay_shared_links.rs` | Shared-link rows and `ALLOWED_DURATIONS` |
| `crates/lo-auth/src/overlay_token.rs` | `lm_overlay_*` generation and prefix validation |
| `crates/lo-auth/src/shared_token.rs` | `lm_share_*` generation and prefix validation |
| `crates/lo-websocket/src/session.rs` | Heartbeat credential re-validation (`TOKEN_REVOKED` / `TOKEN_EXPIRED` / `AUTH_UNAVAILABLE`) |
| `apps/api/src/db/credential_revalidation.rs` | Per-token-kind database re-check behind the heartbeat |
| `apps/web/src/app/(overlay)/overlay/[key]/` | Browser-source renderer |

---

## Features / Automations

Source: https://docs.lumio.vision/features/automations

# Automations

## Overview

The Automations module provides a visual workflow automation engine with a node-based editor. Users create automations composed of trigger nodes, condition nodes, and action nodes connected by edges. Automations can be triggered by platform events (e.g., a new follower triggers a chat message) or manually. The module includes an execution engine that walks the node graph, evaluates conditions, executes actions via a dispatcher, and supports template variables. A manual run reports its outcome inline as `ExecutionResultGql` (`automationId`, `completed`, `steps`, `failedSteps`, `stepResults`); runs are not persisted to an execution-history table.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/automations.rs`) -- Full CRUD for automations, nodes, and edges. Manual execution mutation that builds and runs the execution graph.
- **REST** (`apps/api/src/routes/automations.rs`) -- parity endpoints under `/v1/automations`.
- **Database** (`apps/api/src/db/automations.rs`) -- PostgreSQL operations for automations, automation_nodes, and automation_edges tables. Supports bulk replace for nodes and edges.
- **Execution Engine** (`crates/lo-automation/src/`) -- `ActionExecutor` walks the execution graph from a trigger node, evaluates conditions, and dispatches actions. `TemplateContext` provides variable interpolation. `NodeType` enum defines available node types (triggers, actions, logic).
- **Dispatcher** (`apps/api/src/dispatch.rs`) -- `RedisActionDispatcher` sends action payloads via Redis pub/sub for real-time execution.

### Frontend

- Node-based visual editor with a drag-and-drop canvas for creating and arranging nodes.
- Edge connections define the execution flow between nodes.
- **Test run** button in the editor header (`/dashboard/automations/{id}/editor`), shown to members with `automations:execute`; the editor itself sits behind `feature:automation`. Unsaved edits are saved first, because the server always runs the saved graph — if the save fails, the run does not start.
- The run goes through the web proxy `POST /api/automations/{id}/execute` (the `executeAutomation` mutation) and its result appears in a panel under the header:
  - **Green** only when at least one step ran and none failed. Any failed step, or a walk that did not complete, shows the run as failed with "*n* of *m* steps failed"; a run that executed no step (nothing connected to the trigger) is neutral, not green.
  - Every executed step is listed in order with its node, status (succeeded / skipped / failed), duration and — for a failed step — the server's error, e.g. *No consumer for action control_obs*. Selecting a step opens that node's settings.
  - On the canvas each executed node gets an outline in its step's colour (red = failed, green = succeeded, grey = skipped). A node that ran more than once (loop) shows its worst outcome. The outline is display-only and never marks the automation as changed.
  - A request-level error (for example *No trigger node found in automation*) is shown in the same panel. Dismissing the panel clears the outlines.

## API

### GraphQL Queries

Every automation query and mutation additionally requires the
`feature:automation` feature flag on the account. When the flag is off the
operation fails on both protocols before any permission check runs.

| Query | Permission | Description |
|-------|-----------|-------------|
| `automations` | `feature:automation` + `automations:read` | List all automations for the account |
| `automation(id: UUID!)` | `feature:automation` + `automations:read` | Get a single automation with all its nodes and edges |
| `automationWebhookUrl(installId: UUID!, automationId: UUID!)` | `feature:automation` | Webhook URL + secret for an extension trigger node (see [Webhook triggers](#webhook-triggers)) |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `createAutomation(input: CreateAutomationInput!)` | `automations:create` | Create a new automation with name and description. Returns `AutomationGql!`. |
| `updateAutomation(input: UpdateAutomationInput!)` | `automations:edit` | Update automation name, description, or enabled state. Returns `AutomationGql!`. |
| `deleteAutomation(id: UUID!)` | `automations:delete` | Delete an automation and all its nodes/edges. Returns `AutomationDeleteResult!`. |
| `saveAutomationNodes(automationId: UUID!, nodes: [AutomationNodeInput!]!)` | `automations:edit` | Bulk replace all nodes for an automation. Returns `[AutomationNodeGql!]!`. |
| `saveAutomationEdges(automationId: UUID!, edges: [AutomationEdgeInput!]!)` | `automations:edit` | Bulk replace all edges for an automation. Returns `[AutomationEdgeGql!]!`. |
| `executeAutomation(id: UUID!)` | `automations:execute` | Manually execute an automation. Finds the manual_trigger node (or first trigger), builds the execution graph, and runs it. Returns `ExecutionResultGql!` with `completed`, `steps`, `failedSteps` and per-step `stepResults` (`nodeId`, `nodeType`, `status` = `success`/`skipped`/`error`, `error`, `durationMs`). |

### Built-in node types

`nodeType` on a saved node is one of the `NodeType` variants in
`crates/lo-automation/src/types.rs`:

| Group | Node types |
|-------|------------|
| **Trigger** | `command_trigger`, `keyword_trigger`, `event_trigger`, `timer_trigger`, `manual_trigger`, `webhook_trigger`, `extension_trigger` |
| **Action** | `chat_message`, `discord_post`, `obs_control`, `streamer_bot`, `spotify_control`, `overlay_alert`, `webhook_call`, `moderation`, `set_variable`, `get_variable`, `extension_action` |
| **Logic** | `condition`, `delay`, `random`, `loop`, `extension_logic` |

The three `extension_*` variants are the dispatch points for [extension nodes](#extension-nodes).

### Input Types

**AutomationNodeInput:**
| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID` | Node ID (client-generated) |
| `nodeType` | `String` | Node type (trigger, condition, action) |
| `positionX` | `f64` | X position in the editor canvas |
| `positionY` | `f64` | Y position in the editor canvas |
| `config` | `JSON` | Node-specific configuration (default: `{}`) |

**AutomationEdgeInput:**
| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID` | Edge ID (client-generated) |
| `sourceNodeId` | `UUID` | Source node ID |
| `targetNodeId` | `UUID` | Target node ID |
| `sourceHandle` | `String` | Source handle name (default: `"output"`) |
| `targetHandle` | `String` | Target handle name (default: `"input"`) |

### REST Endpoints

Mirror the GraphQL surface. All paths live under `/v1/automations`.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/automations` | `automations:read` | List automations |
| `POST` | `/v1/automations` | `automations:create` | Create an automation |
| `GET` | `/v1/automations/{id}` | `automations:read` | Get an automation (with nodes and edges) |
| `PATCH` | `/v1/automations/{id}` | `automations:edit` | Update name/description/enabled |
| `DELETE` | `/v1/automations/{id}` | `automations:delete` | Delete automation + nodes + edges |
| `PUT` | `/v1/automations/{id}/nodes` | `automations:edit` | Bulk replace node list |
| `PUT` | `/v1/automations/{id}/edges` | `automations:edit` | Bulk replace edge list |
| `POST` | `/v1/automations/{id}/execute` | `automations:execute` | Run the automation manually. Returns `completed`, `steps`, `failed_steps` and per-step `step_results` (same fields as GraphQL, snake_case) |

Request bodies are snake_case copies of the GraphQL `CreateAutomationInput` / `UpdateAutomationInput` / `AutomationNodeInput` / `AutomationEdgeInput`.

### WebSocket

| Channel | Gate | Feature flag |
|---------|------|--------------|
| `automations:{account_id}` | `automations:read` on the account in the channel key | `feature:automation` |

An account without `feature:automation` is rejected at subscribe time, so the
stream cannot be reached by crafting the channel name. The gate lives in
`channel_gate_for` / `channel_feature_for` (`crates/lo-websocket/src/gate.rs`).

## Permissions

| Permission | Description |
|-----------|-------------|
| `automations:read` | View automations and their configuration |
| `automations:create` | Create new automations |
| `automations:edit` | Edit automation metadata, nodes, edges |
| `automations:delete` | Delete automations |
| `automations:execute` | Manually trigger and start/stop automations |

There is no `automations:history` permission: no execution-history surface exists —
`executeAutomation` returns its results inline and they are not persisted. The former
`automations:history` account permission was **removed** in ZAF-1094 (it gated nothing).

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `automations` | PostgreSQL | id, account_id, name, description, enabled, created_at, updated_at |
| `automation_nodes` | PostgreSQL | id, automation_id (FK), node_type, position_x, position_y, config (JSONB), created_at |
| `automation_edges` | PostgreSQL | id, automation_id (FK), source_node_id, target_node_id, source_handle, target_handle, created_at |

## Data Flow

An automation runs in one of two ways:

- **Manually**: `POST /v1/automations/{id}/execute` (REST) or `executeAutomation` (GraphQL). Manual execution starts at the `manual_trigger` node, or at the first trigger node when there is none, and returns the result inline. It works whatever the trigger switch says.
- **From a trigger**: chat, keyword, command, event and timer triggers fire only when the operator has set `[automation] triggers_enabled = true` (`LUMIO__AUTOMATION__TRIGGERS_ENABLED`). The switch is **off** in every shipped config. With it off, trigger nodes are saved but never evaluated. See [Installation → Automation triggers](../getting-started/installation.md#automation-triggers).

1. User creates an automation and adds nodes (triggers, conditions, actions) via the visual editor.
2. Nodes are connected with edges that define execution flow.
3. Nodes and edges are saved via bulk-replace mutations (`saveAutomationNodes`, `saveAutomationEdges`).
4. When the automation runs:
   - The execution graph is built from nodes and edges.
   - The executor starts at the trigger node and walks the graph.
   - Conditions are evaluated; actions are dispatched via `RedisActionDispatcher` (see [Action delivery](#action-delivery)).
   - Each step is recorded with its status for the execution result.
5. A manual run returns whether the walk completed, how many steps ran, how many failed, and each step's status and error. A triggered run publishes `{automation_id, trigger_node_id, completed, steps_count, error}` to `lumio:automations:{account_id}`.

### Trigger path

Twitch announcements follow the ordinary chat-message path and can match
keyword and command chat triggers; there is no announcement-specific exclusion.

With `triggers_enabled = true`, every API replica runs the automation trigger supervisor (`apps/api/src/workers/automation_triggers.rs`). Only the replica that holds the Redis lease `lumio:automation:triggers:leader` runs workers, so a trigger fires once, not once per replica. The lease lives for 30 s and is renewed every 10 s. A replica that loses it stops its automation workers, and another replica takes over within one lease lifetime.

Every 10 s the leader starts or stops per-account workers to match the database. Accounts whose plan lacks `feature:automation` get no workers.

| Worker | Runs for | Fires |
|--------|----------|-------|
| Trigger worker (`workers/automation.rs`) | Each account with an enabled automation | Subscribes to `lumio:chat:{account_id}` and `lumio:events:{account_id}`. A chat message fires `keyword_trigger` and `!command` `command_trigger` nodes, and a stream event fires `event_trigger` nodes. A bot command with `response_type = automation` is published on the same chat channel as `{"type": "command", "automation_id", …}`, and runs that automation from its `command_trigger` node |
| Timer worker (`workers/automation_timer.rs`) | Each account with an enabled `timer_trigger` | Checks every second and fires each timer once per `interval_seconds`. A newly seen timer waits one full interval before its first fire, also after a restart or a leader change |

Each account reloads its enabled automations at most every 5 s, so an edit takes effect within 5 s.

A Twitch Shared Chat partner message or event never fires a trigger. These are messages written in another channel's room and delivered into this one. They are still displayed. The Twitch bot marks such a bot command `is_shared_chat`. The bot does not publish it, and the trigger worker skips it too.

Each triggered execution runs in its own task, so a long Delay node never holds up the next trigger:

| Limit | Value | When exceeded |
|-------|-------|---------------|
| Executions per account at once | `max_concurrent_executions` (default 8), trigger and timer runs together | The trigger is dropped and logged, not queued |
| Wall-clock time per execution | `execution_timeout_secs` (default 3900 s, above the 1-hour Delay cap) | The run is stopped and publishes `completed: false` with `Execution timed out after … seconds` |
| Worker shutdown or lost lease | — | Running executions of that worker stop at once |

### Action delivery

A step is `success` only when a consumer received the action. Bot actions are published to `lumio:bot:action:{platform}:{account_id}` as a `{ "type": …, "data": … }` envelope (`lo_cache::bot_action::BotActionCommand`); the API and every bot share that type and its type-name constants. A step fails with an `error` status when:

- no Lumio service consumes the action (`No consumer for action …`), or
- the Redis `PUBLISH` reached no subscriber, for example because the bot is not running (`No subscriber received action …`).

| Action node | Delivered to | Today |
|-------------|--------------|-------|
| `chat_message` | Twitch, Kick or YouTube bot (`chat_message`; platform defaults to `twitch`) | Delivered. Any other platform fails with *no consumer* |
| `discord_post` | Discord bot (`post_message`) | Delivered |
| `overlay_alert` | API event relay → WebSocket `automations:{account_id}` | Delivered |
| `webhook_call` | The configured URL over HTTP (see [Webhook call targets](#webhook-call-targets)) | Fails with `webhook_failed` or `webhook_http_error` |
| `set_variable` / `get_variable` | Redis keys (`lumio:var:{account_id}:{name}`, 30-day TTL refreshed on every write) | Delivered |
| `extension_action` / `extension_logic` | Automation Worker over HTTP | Fails when the worker is unconfigured or the handler errors |
| `moderation` | — | Fails with *no consumer*: no bot executes moderation yet (the Twitch bot refuses it until the Helix moderation path ships) |
| `obs_control` | — | Fails with *no consumer* |
| `streamer_bot` | — | Fails with *no consumer* |
| `spotify_control` | — | Fails with *no consumer* |

### Webhook call targets

The `webhook_call` node sends its request from the Lumio API, so every target passes a target filter before a connection opens (`apps/api/src/webhook_target.rs`). The same filter runs for manual, event- and timer-triggered executions.

| Rule | Detail |
|------|--------|
| Scheme | `https` or `http` only. Plain `http` stays allowed for self-hosted receivers without TLS; prefer `https`, because headers and body travel unencrypted otherwise |
| Address | The host is resolved once. The target is refused when **any** address is not public: loopback (`127.0.0.0/8`, `::1`, `localhost`), private (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`), link-local (`169.254.0.0/16`, `fe80::/10`), CGNAT (`100.64.0.0/10`), unspecified, multicast, broadcast and reserved ranges, and IPv6 forms that wrap one of these (IPv4-mapped, NAT64, 6to4) |
| Pinning | The request connects only to the addresses that were checked; the client does no DNS lookup of its own, so a changed DNS answer cannot redirect it |
| Redirects | Never followed. A `3xx` answer is a non-2xx answer |
| Proxy | System proxy settings are ignored for these requests |
| Timeouts | 10 s to connect, 60 s in total |

Substituted template values in the URL, headers and body are encoded for their position (`lo_automation::template::Sink`): percent-encoding after the URL's literal authority, control characters in header values replaced by spaces, and JSON-string escaping or form encoding of the body by its `Content-Type` (a body template starting with `{` or `[` counts as JSON when no `Content-Type` is set). Discord post messages escape markdown in substituted values. The full table is in [Automation Templates → Output Encoding](../user-guide/automation-templates.md#output-encoding).

A failed webhook step reports only one of two fixed errors, on GraphQL `executeAutomation` and REST `POST /v1/automations/{id}/execute` alike:

| Error | Meaning |
|-------|---------|
| `webhook_failed` | The request was not delivered: the target was refused by the filter, the URL is invalid, the host did not resolve, or the connection, TLS handshake or timeout failed |
| `webhook_http_error` | The target answered with a status outside `2xx` |

A refused target and an unreachable one return the same `webhook_failed`. The result never contains the URL, a status code or transport error text; the API logs the detail server-side (without the URL). A target refused during a manual run also writes an [`account:webhook_target_blocked`](./audit-log.md) audit event; event- and timer-triggered runs only log it, because they would repeat it on every trigger.

## Graph rules and limits

### Save-time validation

`saveAutomationNodes` / `PUT /v1/automations/{id}/nodes` and `saveAutomationEdges` / `PUT /v1/automations/{id}/edges` validate the graph before anything is written. Both protocols run the same check (`lo_automation::validate_graph`, called from `apps/api/src/services/automation_graph.rs`) and reject with the same `400 BAD_REQUEST` and message (`Graph error: …`).

| Rule | Checked on |
|------|------------|
| Node ids are unique | nodes |
| `random` nodes have `min <= max` | nodes |
| `timer_trigger` nodes have `interval_seconds` of at least 60 (`timer trigger …: interval_seconds must be at least 60`) | nodes |
| `set_variable` names are at most 128 bytes, and one automation writes at most 100 distinct names | nodes |
| `extension_*` nodes reference an install of **this** account, for the extension named in `extension_meta` (`Extension install not found for this account` otherwise) | nodes |
| No self-loop (an edge from a node to itself) | edges |
| No duplicate edge (same source, target and source handle) | edges |
| No edge to or from an unknown node | edges |
| No directed cycle through a trigger node | edges |

Cycles between non-trigger nodes are allowed; the run-time budget bounds them. A Loop node repeats its subtree through its `count`, not through a back-edge.

### Execution limits

The executor (`crates/lo-automation/src/executor.rs`) enforces these limits on every run, whatever is stored:

| Limit | Value | When exceeded |
|-------|-------|---------------|
| Node entries per run (`MAX_STEPS`) | 1,000, trigger nodes reached mid-walk included | The walk stops: the last step fails with `Limit exceeded: automation work budget exhausted …` and `completed` is `false` |
| Recursion depth (`MAX_DEPTH`) | 100 | Same as above |
| Trigger node entries | Once per run; a path back into a trigger ends there | — |
| Loop iterations (`MAX_LOOP_ITERATIONS`) | 100 per Loop node | The count is clamped |
| Delay (`MAX_DELAY_MS`) | 1 hour per Delay node | The delay is clamped |
| Rendered template (`MAX_TEMPLATE_OUTPUT_BYTES`) | 16 KiB per template (chat message, Discord/overlay message, webhook URL, header or body, condition operand, variable value) | The step fails with `Limit exceeded: rendered template exceeds 16384 bytes`. Chat bots still truncate to the platform's own message limit |
| Variable value (`MAX_VARIABLE_VALUE_BYTES`) | 4 KiB | The step fails; nothing is stored |
| Variables per run (`MAX_VARIABLES_PER_AUTOMATION`) | 100, extension node output included | The step fails |
| Stored variable lifetime (`VARIABLE_TTL_SECS`) | 30 days, refreshed on every write | The Redis key expires |

A `random` node stored with `min > max` (saved before validation existed) uses the swapped range instead of failing. A `timer_trigger` stored with an interval below 60 s fires every 60 s.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/automations.rs` | GraphQL queries and mutations |
| `apps/api/src/db/automations.rs` | Database CRUD for automations, nodes, edges |
| `crates/lo-automation/src/` | Execution engine and limits (`executor.rs`), save-time graph validation (`validate.rs`), template context, node types (`types.rs`) |
| `apps/api/src/services/automation_graph.rs` | Save-time validation shared by GraphQL and REST (graph rules + extension install ownership) |
| `apps/api/src/routes/automations.rs` | REST endpoints |
| `apps/api/src/dispatch.rs` | RedisActionDispatcher for action execution (action → consumer inventory) |
| `crates/lo-cache/src/bot_action.rs` | Shared bot action envelope and type-name constants |
| `apps/api/src/workers/automation.rs` | `build_execution_graph` helper |

## Extension Nodes

Third-party developers can create custom automation nodes via the Extension Platform. The Automation Builder does not list installed extension nodes in its toolbar yet, so a new extension node cannot be added from the dashboard. An automation that already contains an extension node (for example one saved over the API) shows it on the canvas; selecting it shows a note that extension nodes cannot be configured in the builder yet.

### Node types

| Type | Description |
|------|-------------|
| **Trigger** | Starts an automation from an external event (webhook or polling) |
| **Action** | Performs work during automation execution |
| **Logic** | Branches the flow based on a condition |

Extension nodes execute in V8 isolates inside the Automation Worker service. Each node has a 2-5 second timeout depending on type, enforced inside the worker (see the developer docs' *Runtime limits*).

An extension node names its install in `config.extension_meta.install_id`. The install must belong to the account that owns the automation: the save paths reject any other install, and the Automation Worker resolves the install by `(install_id, account_id, extension_id)` at run time, where `account_id` comes from the automation row. A mismatch fails the step with `Install not found`. Installs of a suspended extension are dropped from the worker's registry on its next sync (at most about 30 seconds).

### Installation

Extension automation nodes are installed from the Extension Store like any other extension. Uninstalling removes the node from the toolbar and disables any automations that use it (with a warning notification).

### Feature flag

Extension automation nodes require the `feature:automation_node_extensions` feature flag. This flag gates:
- Installation of `automation_node` extensions in the store
- The "Extensions" section of the Automation Builder toolbar (the toolbar renders it only when the host passes installed nodes, which the dashboard does not do yet)

### Webhook triggers

Extension trigger nodes can receive external webhooks. When an automation with a webhook trigger is enabled:
1. A webhook URL and secret are generated
2. The user configures the external service with this URL and the `X-Webhook-Secret` header
3. Incoming webhooks are validated and forwarded to the Automation Worker
4. If the handler returns `fired: true`, the automation runs

### Key files

| Path | Description |
|------|-------------|
| `apps/automation-worker/` | Automation Worker HTTP service (V8 handler executor) |
| `crates/lo-automation-worker/` | Automation Worker library crate |
| `crates/lo-automation/src/executor.rs` | Automation Engine with extension node dispatch |

---

## Features / Spotify / Music

Source: https://docs.lumio.vision/features/spotify

# Spotify / Music

## Overview

The Spotify module integrates with the Spotify Web API to provide "Now Playing" overlays and a full dashboard music player. It supports playback control (play, pause, next, previous, seek, volume, shuffle, repeat), queue management, playlist browsing and playback, device selection and transfer, and track search. Spotify credentials are stored encrypted per-account. Access tokens are kept fresh by the centralized [Token Refresh Worker](./token-refresh.md) - request handlers read a ready-to-use token via `oauth::get_fresh_connection_token` and never refresh inline. All playback actions are logged as events in TimescaleDB and broadcast via Redis pub/sub for real-time overlay updates. The Now-Playing worker polls adaptively: every 5 seconds while a track is playing and every 30 seconds when paused, idle, or after an error.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/spotify.rs`) -- Queries for combined Spotify state and track search. Mutations for playback control, queue management, playlist playback, and device transfer.
- **Services** -- GraphQL and REST parse their input and call the same services. `services::spotify_control::run_dashboard_control` runs a playback or queue control (play, pause, next / skip_to, previous, seek, volume, shuffle, repeat, queue add), adds the current track where it is known, and records the `spotify:*` event attributed to the user (`triggered_by`, `username`). The extension action dispatcher uses the same control and event payloads. `services::spotify_playlists` creates, renames, deletes (unfollows) and edits playlist tracks and records the `spotify:playlist_*` event. The `spotify:volume` check stays in each protocol's parser and runs before the volume value is read.
- **Crate** (`crates/lo-spotify-api/src/`) -- `SpotifyClient` wraps the Spotify Web API with methods for now_playing, queue, devices, playlists, search, play, pause, next, previous, seek, volume, shuffle, repeat, add_to_queue, transfer_playback, play_playlist. Its `SpotifyClient::refresh_token()` is `#[deprecated]` and reserved for the initial OAuth code exchange, which has no DB row to read yet - internal callers must use `oauth::get_fresh_connection_token` instead, so refreshes cannot race the Token Refresh Worker.
- **Worker** (`apps/api/src/workers/spotify.rs`) -- Polls the Now-Playing endpoint at `PLAYING_POLL_INTERVAL_SECS` (5 s) / `IDLE_POLL_INTERVAL_SECS` (30 s), honours a `Retry-After` on rate limits, and backs off to the idle interval after 5 consecutive errors.
- **Credentials** -- Stored in PostgreSQL via `db::spotify::get_spotify_credentials()`. Client ID, client secret, access token, and refresh token are all encrypted at rest using `crypto::encrypt/decrypt`. Connection is managed through the Connections module (Spotify as a platform).
- **Event Logging** -- Every playback action emits an event (e.g., `spotify:play`, `spotify:pause`, `spotify:skip`) to TimescaleDB and broadcasts it via Redis pub/sub asynchronously.

### Worker lifecycle

The Now-Playing worker (`apps/api/src/workers/spotify.rs`) is **not** always running -- it is started and stopped by the [Channel Status](./channel-status.md) relay to match stream activity:

- **Runs** while any of the account's channels is online **or** a manual connect is active (a 30-minute Redis TTL -- see Channel Status). This is intentional: the worker only polls Spotify when someone is actually streaming or has opted in for a listening session.
- **Stops** at stream end and when the 30-minute manual-connect window expires. A 60-second sweep tears down any worker whose account is neither online nor in a manual connect.
- **Comes back without an API restart.** When a channel next goes online, or a manual connect starts, the relay re-evaluates and starts the worker again. The config (which connection to poll) is **resolved from the live `channel_connections` row on demand** -- there is no boot-time snapshot -- so a Spotify connection linked, re-authorized, or disconnected-and-reconnected *after* the API booted is picked up with its **current** `connection_id`, and an account with no Spotify connection simply does not start one. If the connection row is deleted while the worker runs, it exits cleanly on its next poll.

### Event emission: worker vs. control path

Two independent producers write Spotify events, and they are **not** symmetric:

- **`spotify:track`** is emitted **only by the worker**, when it detects a track change on a poll. It is deduplicated per *playback occasion* (track id + the instant playback started, `timestamp - progress_ms`), so the same title restarted (repeat-one, replay, skip-back) gets its own line while two dense polls of one continuous play collapse to a single row.
- **`spotify:skip` / `spotify:play` / `spotify:pause` / `spotify:previous` / `spotify:seek` / `spotify:volume` / `spotify:shuffle` / `spotify:repeat`** are emitted by the **playback-control mutation** (GraphQL `spotifyPlayback` / REST `POST /v1/spotify/playback`), independently of whether the worker is running.
- A **skip / previous** control event deliberately carries **no track fields**: Spotify's now-playing endpoint keeps returning the *previous* track for about a second after the change, so naming a track there would name the one just skipped away from. The new title is named by the following worker-emitted `spotify:track` instead.
- **A shuffle / repeat change made *inside the Spotify app itself* emits no event.** The worker only ever emits `spotify:track`; every control event (`spotify:shuffle`, `spotify:repeat`, `spotify:volume`, …) is produced by the playback-control mutation, so toggling shuffle or cycling repeat in the native Spotify client — rather than through Lumio — leaves no line in the feed. This is expected behaviour, not a gap.

### Control-event `raw` fields

Each control event stores the value it changed in its `raw` blob, so surfaces can show *what* was set, not just *that* something was set. The dashboard events feed and the inline chat event line both read these (via the shared `resolveEventDetails` resolver):

| Event type | `raw` field(s) | Shown as |
|------------|----------------|----------|
| `spotify:shuffle` | `enabled` (bool) | "On" / "Off" — the value is a plain boolean; Smart Shuffle is a read-only *player* state and never a control-event value |
| `spotify:repeat` | `mode` (`"off"` \| `"context"` \| `"track"`) | "Off" / "All" / "One" |
| `spotify:volume` | `oldVolume`, `newVolume` (percent) | `40% → 75%` |

An event that lacks a well-formed value (a legacy row written before these fields, or a foreign payload) renders without the extra segment rather than guessing a default.

### Error handling

`spotify_error_to_api` (`apps/api/src/routes/spotify.rs`) maps Spotify errors to the shared `ApiError` taxonomy for REST and GraphQL. Both protocols return the same code and client-facing message. Upstream `401` becomes `UNAUTHORIZED`; an upstream `429` becomes `RATE_LIMIT_EXCEEDED` with the message `Spotify rate limit reached. Try again shortly.` and Spotify's wait in seconds (at least 1). REST returns HTTP 429, `Retry-After`, and `details.retry_after_secs`; GraphQL returns `extensions.code` and `extensions.retryAfterSecs`. This mapping applies to Spotify reads and mutations that call the Spotify Web API. A `404` from `/me/player/*` becomes `NOT_FOUND` ("no active device"); other failures become `INTERNAL_SERVER_ERROR` with detail scrubbed on the wire.

Because a scrubbed 5xx carries no cause to the browser, the cause is recorded server-side instead, in three places:

- `error_from_response` logs the upstream status, path, `Retry-After` and (truncated) body for every non-2xx Spotify response.
- `parse_json` logs the endpoint, the serde error and the offending payload when a 2xx body does not match the expected shape — `reqwest`'s own `.json()` reports only "error decoding response body".
- `to_graphql_error` logs the full `ApiError` on 5xx, mirroring what the REST `error_response()` already did.

### Spotify Web API endpoints and Development Mode

Spotify connections use the customer's own Spotify app (`app_credentials`), which runs in Spotify's **Development Mode**. Since Spotify's [February 2026 Web API changes](https://developer.spotify.com/documentation/web-api/tutorials/february-2026-migration-guide) (enforced for existing Development Mode apps from 2026-03-09), `SpotifyClient` uses only the current endpoints:

| `SpotifyClient` method | Spotify endpoint |
|------------------------|------------------|
| `create_playlist` | `POST /me/playlists` |
| `get_playlist` | `GET /playlists/{id}?fields=…,items(total),…` |
| `delete_playlist` | `DELETE /me/library?uris=spotify:playlist:{id}` |
| `add_to_playlist` | `POST /playlists/{id}/items` (body `{uris}`) |
| `get_playlist_tracks` | `GET /playlists/{id}/items` (reads `items[].item`, falls back to the deprecated `track`) |
| `remove_from_playlist` | `DELETE /playlists/{id}/items` (body `{items: [{uri}]}`) |
| `search` | `GET /search` with `limit` at most 10 |

The removed endpoints (`POST /users/{id}/playlists`, `DELETE /playlists/{id}/followers`, `/playlists/{id}/tracks`) return errors for Development Mode apps. The playlist count is read from `items.total`, with the deprecated `tracks.total` as fallback. Development Mode tracks no longer carry `external_ids`, so playlist tracks usually have no ISRC (see [Copyright Manager](../developer-guide/copyright-detection.md)).

Spotify puts a literal `null` in its `items` arrays for entries the caller may not see (a market-unavailable search hit, a removed playlist track). All item collections are therefore deserialized as `Vec<Option<T>>` and flattened, so one such entry skips a row instead of failing the whole response.

### Frontend

- Dashboard and popout music player with now playing display, playback controls, queue view, playlist browser, and device selector. On a Spotify 429, a warning banner counts down to the next read; the player keeps its last known state, pauses polling, and refreshes once when the wait ends. See the [Music guide](/user-guide/music#spotify-rate-limit).
- Overlay widget displays current track info, album art, and progress bar.
- Next.js API proxy routes call GraphQL internally.

## API

### GraphQL Queries

Every Spotify query and mutation in `apps/api/src/graphql/spotify.rs` is gated by
`FeatureGuard::new("feature:music").and(PermissionGuard::new(<permission>))`; the
REST twins call `auth.require_permission(…)` + `require_feature(…, "feature:music", …)`.
The three manual-connect operations live in `channel_status.rs` / `routes/channel_status.rs`
and carry the **permission only** - no `feature:music` gate on either protocol.

| Query | Feature | Permission | Description |
|-------|---------|-----------|-------------|
| `spotifyState` | `feature:music` | `spotify:read` | Combined state: now playing, queue, devices, playlists (fetched in parallel via `tokio::join!`) |
| `spotifySearch(query, limit?)` | `feature:music` | `spotify:read` | Search Spotify tracks (default and maximum limit: 10; larger values are clamped) |
| `spotifyManualStatus` | - | `spotify:read` | Manual-connect status (`active`, `remainingSeconds`) |

### GraphQL Mutations

| Mutation | Feature | Permission | Description |
|----------|---------|-----------|-------------|
| `spotifyPlayback(input: SpotifyPlaybackInput!)` | `feature:music` | `spotify:playback` (+ `spotify:volume` for the `volume` action) | Control playback. Actions: `play` (optional track URI), `pause`, `next`, `previous`, `seek` (position in ms), `volume` (0-100), `shuffle` (bool), `repeat` (off/context/track). The `volume` branch performs an inline `require_permission(SPOTIFY_VOLUME)` check, matching REST. |
| `spotifyQueue(uri: String!)` | `feature:music` | `spotify:queue` | Add a track to the Spotify queue |
| `spotifyTransferPlayback(deviceId: String!)` | `feature:music` | `spotify:device` | Transfer playback to a different device |
| `spotifyPlayPlaylist(input: SpotifyPlayPlaylistInput!)` | `feature:music` | `spotify:playlist` | Start playing a playlist. Input fields: `uri` plus optional `deviceId`, `name`, `coverUrl`, `trackCount`, `playlistUrl`. When `deviceId` is provided it is forwarded to Spotify as `?device_id=` so the target device is activated in the same call (avoids a transfer+play race where Spotify returns "No active Spotify device"). |
| `spotifyCreatePlaylist(name: String!, public: Boolean)` | `feature:music` | `spotify:playlist` | Create a new Spotify playlist |
| `spotifyRenamePlaylist(id, name)` | `feature:music` | `spotify:playlist` | Rename a Spotify playlist |
| `spotifyDeletePlaylist(id)` | `feature:music` | `spotify:playlist` | Delete (unfollow) a Spotify playlist: removes `spotify:playlist:{id}` from the user's Spotify library |
| `spotifyAddToPlaylist(playlistId, trackUris: [String!]!)` | `feature:music` | `spotify:playlist` | Add tracks to a Spotify playlist |
| `spotifyRemoveFromPlaylist(playlistId, trackUri)` | `feature:music` | `spotify:playlist` | Remove a track from a Spotify playlist |
| `startSpotifyManual` | - | `spotify:worker` | Start manual Spotify connect (30 min TTL). Returns `SpotifyManualStatus`. |
| `stopSpotifyManual` | - | `spotify:worker` | Stop manual Spotify connect. Returns `Boolean`. |

### REST Endpoints

All paths live under `/v1/spotify`. Bodies are snake_case.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/spotify/state` | `spotify:read` | Combined now-playing / queue / devices / playlists state |
| `POST` | `/v1/spotify/playback` | `spotify:playback` | Playback control: `play`, `pause`, `next`, `previous`, `skip_to`, `seek`, `volume`, `shuffle`, `repeat`. The `volume` action additionally requires `spotify:volume` |
| `GET` | `/v1/spotify/queue` | `spotify:read` | Current Spotify queue |
| `POST` | `/v1/spotify/queue` | `spotify:queue` | Add a track URI to the queue |
| `GET` | `/v1/spotify/devices` | `spotify:read` | List available playback devices |
| `POST` | `/v1/spotify/devices` | `spotify:device` | Transfer playback to a device |
| `GET` | `/v1/spotify/playlists` | `spotify:read` | List user playlists |
| `POST` | `/v1/spotify/playlists` | `spotify:playlist` | Playlist action, selected by `action`: `play`, `create`, `rename`, `delete`, `add_track`, `remove_track` |
| `GET` | `/v1/spotify/search` | `spotify:read` | Search Spotify tracks (`query`, optional `limit`; default and maximum 10) |
| `GET` | `/v1/spotify/manual-connect` | `spotify:read` | Manual-connect status (+ remaining seconds) |
| `POST` | `/v1/spotify/manual-connect` | `spotify:worker` | Start manual Spotify polling (30 min TTL) |
| `DELETE` | `/v1/spotify/manual-connect` | `spotify:worker` | Stop manual Spotify polling |

The five playlist-**management** mutations (`spotifyCreatePlaylist`,
`spotifyRenamePlaylist`, `spotifyDeletePlaylist`, `spotifyAddToPlaylist`,
`spotifyRemoveFromPlaylist`) map to the `create`, `rename`, `delete`,
`add_track` and `remove_track` actions of `POST /v1/spotify/playlists`.
Both protocols call the same `SpotifyClient` method with the same permission
(`spotify:playlist`) and the same `feature:music` gate.

Shuffle writes are boolean (`shuffle: true` / `false` in GraphQL playback input,
or the REST playback body's snake_case equivalent). The state read from Spotify
can still be `off`, `on`, or `smart`: Smart Shuffle is reported by Spotify's
player state, but Spotify does not expose a public Web API endpoint that lets
Lumio enable it.

### WebSocket

| Channel | Gate | Feature |
|---------|------|---------|
| `spotify:{account_id}` | `spotify:read` | none at the WebSocket layer |

`channel_gate_for("spotify")` maps the channel to `ChannelGate::Permission("spotify:read")`
and `channel_feature_for` returns `None` for it, so the plan check happens on the
REST/GraphQL paths rather than at subscribe time. WebSocket clients can only
subscribe, unsubscribe, and ping; they cannot publish on any channel. Playback
state is published server-side by the Spotify worker.

### Event Types Generated

`spotify:track` is produced by the **worker** on a detected track change; every
other row below is produced by the **control mutation** (see *Event emission*
above). `skip`/`previous` control events carry no track fields.

| Event Type | Trigger |
|-----------|---------|
| `spotify:track` | Worker-detected track change (worker-only; not a control action) |
| `spotify:play` | Play action |
| `spotify:pause` | Pause action |
| `spotify:skip` | Next or skip_to action |
| `spotify:previous` | Previous action |
| `spotify:seek` | Seek action |
| `spotify:volume` | Volume change (includes old/new volume) |
| `spotify:shuffle` | Shuffle toggle |
| `spotify:repeat` | Repeat mode change |
| `spotify:queue_add` | Track added to queue |
| `spotify:device` | Playback transferred to different device |
| `spotify:playlist` | Playlist started playing |

## Permissions

| Permission | Description |
|-----------|-------------|
| `spotify:read` | Read now playing state, queue, devices, playlists, search tracks |
| `spotify:playback` | Control playback (play, pause, next, previous, seek, shuffle, repeat) |
| `spotify:volume` | Change playback volume (gates the volume slider in the dashboard and popout player) |
| `spotify:queue` | Add tracks to the queue |
| `spotify:playlist` | Manage and play playlists |
| `spotify:device` | Transfer playback to another device |
| `spotify:worker` | Start/stop the manual Spotify polling worker |

## Database

Spotify uses the Connections module tables for credential/token storage:

| Table | Database | Description |
|-------|----------|-------------|
| `app_credentials` | PostgreSQL | Encrypted client_id and client_secret per platform per account |
| `channel_connections` | PostgreSQL | Encrypted access_token, refresh_token, expires_at, platform_channel_id, scopes |

Events generated by Spotify actions are stored in:

| Table | Database | Description |
|-------|----------|-------------|
| `platform_events` | TimescaleDB | Spotify events (spotify:play, spotify:skip, etc.) with enriched raw JSON containing track info and triggering user |

## Data Flow

1. User connects Spotify via the Connections module (OAuth flow).
2. `build_client_from_ctx()` loads the account's Spotify credentials and calls `oauth::get_fresh_connection_token` for a decrypted, already-fresh access token. It performs no refresh of its own.
3. User performs a playback action (e.g., skip) via the dashboard.
4. The `SpotifyClient` method is called against the Spotify Web API.
5. The control event is enriched with the triggering user and, for non-track-changing actions, current track data. A `skip`/`previous` omits track data on purpose -- the new title is reported by the worker's next `spotify:track` (see *Event emission*).
6. An event is asynchronously inserted into TimescaleDB and broadcast via Redis pub/sub.
7. Overlay "Now Playing" widget receives the event via WebSocket and updates the display.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/spotify.rs` | GraphQL queries and playback/playlist mutations |
| `apps/api/src/graphql/channel_status.rs` | `spotifyManualStatus`, `startSpotifyManual`, `stopSpotifyManual` |
| `apps/api/src/routes/spotify.rs` | REST handlers under `/v1/spotify` |
| `apps/api/src/services/spotify_control.rs` | Shared playback/queue controls and `spotify:*` event recording |
| `apps/api/src/services/spotify_playlists.rs` | Shared playlist create/rename/delete/track edits |
| `apps/api/src/routes/channel_status.rs` | REST handlers for `/v1/spotify/manual-connect` |
| `apps/api/src/workers/spotify.rs` | Adaptive Now-Playing polling worker |
| `crates/lo-spotify-api/src/` | Spotify Web API client |
| `apps/api/src/db/spotify.rs` | Credential retrieval helpers |
| `apps/api/src/crypto.rs` | Token encryption/decryption |
| `apps/api/src/oauth.rs` | Token refresh persistence |

---

## Features / Members & Invites

Source: https://docs.lumio.vision/features/members

# Members & Invites

## Overview

The Members & Invites module provides team management for Lumio accounts. Account owners and administrators can invite users to their account, assign roles to members, and manage the team roster. The invite system supports invite links with configurable expiry and maximum uses, role assignment at invite time, and user search across the platform. Members can be part of multiple accounts, enabling account switching for multi-account users.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/members.rs`) -- Queries for listing members, listing invites, public invite lookup by code, and searching users. Mutations for updating member roles, removing members, creating/deleting invites, and accepting invites.
- **REST** (`apps/api/src/routes/members.rs`) -- The same operations under `/v1/accounts/{id}/members` and `/v1/invites`.
- **Database** (`apps/api/src/db/members.rs`) -- PostgreSQL operations for memberships, invites, user search, and platform connections lookup.
- **Permission Cache** -- The GraphQL `updateMemberRole` and `removeMember` mutations and the REST role-change and remove-member endpoints invalidate the Redis permission cache via `lo_api::middleware::auth::invalidate_permission_cache()`, so a role change (grant or revocation) takes effect immediately instead of lingering until the cache TTL expires.
- **WebSocket** -- Members and invites have no WebSocket channel; `channel_gate_for` in `crates/lo-websocket/src/gate.rs` defines no `members`/`invites` channel type. Roster changes are picked up on the next query.

### Frontend

- Team management in the **Members** area of the settings window at `/dashboard/settings/channel/members`, with member list and role badges (`apps/web/src/components/settings/sections/channel/members/`). The settings section route checks `members:read` before loading it.
- 4-step invite wizard (`invite-dialog.tsx`), in order: **Method** → **Role** → **Options** → **Result**. The method step offers three cards: *Invite Link* (generate a shareable link), *Invite Token* (generate a code to share manually), and *Invite Person* (search by username, email, or platform and target a specific user). The result step shows the generated link/code to copy.
- Account switcher (`apps/web/src/components/account-switcher.tsx`) for users with multiple account memberships. After a switch the tab leaves an account-bound detail route for its static parent and reloads anywhere else; switching to the personal profile opens `/dashboard`. Every place that changes `active_account_id` posts on the `lumio-account` `BroadcastChannel`, and the other dashboard tabs apply the same rule (`useAccountSwitchSync`). The channel selector in the settings window applies the rule too and keeps the window open on the same area: it reloads in place, or opens the static parent with the same `#settings/…` hash. The account-bound routes are the `ACCOUNT_BOUND_DETAIL_ROUTES` constant in `apps/web/src/lib/account-switch.ts`; a unit test fails when a new dynamic dashboard route is missing from it or from `ACCOUNT_NEUTRAL_DYNAMIC_ROUTES`. Classify a new route by its resolver's `account_id` filter, not by its name.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `members: [Member!]!` | `members:read` | List all members of the current account (includes user info, role details, and linked platforms) |
| `invites: [Invite!]!` | `members:read` | List all invites for the current account |
| `inviteByCode(code: String!): InviteDetail!` | Public (no auth) | Public invite details (account name, inviter, role, `isExpired` / `isFull`) for the accept page |
| `searchUsers(query: String!, limit: Int! = 10): [UserSearchResult!]!` | `members:create` | Search users by name, email, or platform username. Minimum 3 characters (shorter queries error). Excludes existing account members. `limit` clamps to 1–10. Returns user info with platform connections. |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `updateMemberRole(input: UpdateMemberRoleInput!): MemberMutationResult!` | `members:edit` | Change a member's role. Cannot change the account owner's role or assign the owner system role. Invalidates the Redis permission cache. |
| `removeMember(membershipId: UUID!): MemberMutationResult!` | `members:delete` | Remove a member from the account. Cannot remove the account owner. Deletes popout tokens assigned to that member in this account and invalidates the Redis permission cache. |
| `createInvite(input: CreateInviteInput!): Invite!` | `members:create` | Create an invite with role assignment, optional email/user targeting, max uses (default 1), and expiry (default 168 hours / 7 days). Cannot create invites with the owner role. |
| `deleteInvite(inviteId: UUID!): MemberMutationResult!` | `members:delete` | Delete an invite |
| `acceptInvite(code: String!): AcceptInviteResult!` | `AuthGuard` + **first-party session** (logged-in user or own API key; popout/overlay/widget/extension tokens rejected with `FORBIDDEN`, ZAF-1740 A6) | Accept an invite by code. A targeted invite (`invitedUserId` set) can only be accepted by that user (`FORBIDDEN` "This invite was issued to a different user" otherwise). Validates expiry, max uses, and duplicate membership. Creates a new membership. |

### REST Endpoints

All paths live under `/v1`. Bodies are snake_case and mirror the GraphQL inputs.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/accounts/{id}/members` | `members:read` | List members of an account |
| `PATCH` | `/v1/accounts/{id}/members/{membership_id}/role` | `members:edit` | Change a member's role. Returns `204 No Content`. Invalidates the Redis permission cache. |
| `DELETE` | `/v1/accounts/{id}/members/{membership_id}` | `members:delete` | Remove a member and delete popout tokens assigned to that member in this account. Returns `204 No Content`. Invalidates the Redis permission cache. |
| `POST` | `/v1/invites` | `members:create` | Create an invite (role + optional email/user + expiry) |
| `GET` | `/v1/invites` | `members:read` | List account invites |
| `GET` | `/v1/invites/{code}/info` | Public (no auth) | Invite lookup used by the accept page - the REST mirror of `inviteByCode` |
| `DELETE` | `/v1/invites/{id}` | `members:delete` | Revoke an invite |
| `POST` | `/v1/invites/{code}/accept` | First-party session (popout/overlay/widget/extension tokens get `403`) | Accept an invite as the authenticated user; a targeted invite only by its target (`403`) |

### Input Types

**CreateInviteInput** (GraphQL camelCase; the REST body uses the snake_case equivalents):

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `roleId` | `UUID!` | (required) | Role to assign to the invited user |
| `email` | `String` | `null` | Target email address; when set, an `AccountInvite` email is sent fire-and-forget |
| `invitedUserId` | `UUID` | `null` | Target user ID (from user search); when set, an in-dashboard `invite` notification is created |
| `maxUses` | `Int` | `1` | Maximum number of times the invite can be used |
| `expiresInHours` | `Int` | `168` (7 days) | Expiry duration in hours |

**UpdateMemberRoleInput:** `membershipId: UUID!`, `roleId: UUID!`.

## Permissions

| Permission | Description |
|-----------|-------------|
| `members:read` | View member list and invites |
| `members:create` | Create invites, search users |
| `members:edit` | Change member roles |
| `members:delete` | Remove members, revoke invites |

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `account_memberships` | PostgreSQL | Links users to accounts. Columns: `id`, `user_id`, `account_id`, `role_id` (nullable FK to `account_roles`), `created_at`. `UNIQUE(user_id, account_id)`. Queries alias `created_at` as `joined_at`, which is the name the API exposes. |
| `account_invites` | PostgreSQL | Invite records. Columns: `id`, `account_id`, `invited_by`, `invited_user_id`, `email`, `invite_code` (unique), `role_id`, `accepted_by`, `max_uses`, `use_count`, `expires_at`, `accepted_at`, `created_at` |
| `account_roles` | PostgreSQL | Roles that memberships and invites reference |
| `users` | PostgreSQL | User profiles (`display_name`, `email`, `avatar_url`) |
| `login_connections` | PostgreSQL | Platform connections shown on members and user-search results (`provider`, `username`, `display_name`) |

## Data Flow

1. An administrator creates an invite via the 4-step wizard, choosing a method, a role, and options.
2. An invite record is created with a unique `invite_code`.
3. Delivery depends on the input: an `email` triggers the `AccountInvite` transactional email; an `invitedUserId` creates an in-dashboard `invite` notification (plus the same email when the user has an address on record); a plain link or token is copied from the result step and shared manually.
4. The target user opens the link, which calls `acceptInvite(code)` (or `POST /v1/invites/{code}/accept`).
5. The system validates the invite: a targeted invite (`invited_user_id` set, *Invite Person*) may only be accepted by that user - anyone else who obtains the code is refused with `FORBIDDEN`, identically on REST and GraphQL (ZAF-1740 C3); then not expired, `use_count` below `max_uses`, and no existing membership for that user/account pair.
6. A new `account_memberships` row is created, linking the user to the account with the invite's role.
7. The invite `use_count` is incremented and `accepted_at` is set.

**Email and link invites are bearer links.** An invite that only carries an `email`, and every *Invite Link* / *Invite Token*, can be accepted by whoever holds the code. The `email` is a delivery address, not a binding: Lumio has no verified-email trust anchor, so matching the accepting account's email would add no real guarantee. Use *Invite Person* when the invite must reach exactly one account.

An invited user can also resolve the invite straight from the notification bell: the `invite` notification carries `accept_invite` / `decline_invite` actions. See [Notifications](./notifications.md#invite).

### Role Change Flow

1. A caller with `members:edit` invokes `updateMemberRole` with the membership ID and new role ID.
2. The system validates: the membership belongs to the active account, the target is not the account owner, the role exists, belongs to the same account, and is not the `owner` system role.
3. The role is updated in the database.
4. Both the GraphQL mutation and the REST endpoint invalidate the Redis permission cache for the affected user/account pair, so the change takes effect on the next request instead of after the cache TTL.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/members.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/members.rs` | REST handlers for members and invites |
| `apps/api/src/db/members.rs` | Database operations for memberships, invites, and user search |
| `apps/api/src/db/roles.rs` | Role lookup for validation |
| `apps/api/src/services/invite_notifications.rs` | In-dashboard invite notification + email side channel |
| `apps/web/src/components/settings/sections/channel/members/` | Members area and invite wizard; the settings section gate checks `members:read` |

---

## Features / YouTube Member Badges

Source: https://docs.lumio.vision/features/memberships

# YouTube Member Badges

## Overview

Lumio renders **YouTube custom-member-tier badges** in the multichat - the
artwork that shows up next to a member's name (e.g. `Member (6 months)` /
`Diamantclub (3 months)`) along with a localized tooltip showing the tier
name plus the membership duration.

YouTube's official Data API v3 does **not** expose the badge image URLs (only
the level `displayName`), and our gRPC live-chat stream carries only
`isChatSponsor` boolean flags. The image URLs live on YouTube's internal
**InnerTube** endpoint that powers the YouTube web frontend itself. Lumio
harvests them from chat poll responses and feeds them into a per-account cache.

## Architecture

```
   InnerTube chat poll
        │
        │  Chat events + badge observations
        ▼
   YouTube chat worker  ─── reads/writes ───▶  MembershipBadgeCache (LRU + Redis)
        │
        │  enriched badges JSON
        ▼
   platform_chat_messages.badges  + WebSocket broadcast
```

The YouTube chat worker (`apps/api/src/workers/youtube.rs`) owns both live
chat ingestion and badge observation for each active broadcast. On every
member message it looks up the member in the cache (LRU first, then Redis) and
merges `image_url`, `tier_name`, `duration_value`, `duration_unit`, and
`info`(=member_months) into the `subscriber` entry of
`platform_chat_messages.badges`. Other entries (broadcaster / moderator /
verified) are not touched. The same InnerTube poll response carries
`authorBadges[].liveChatAuthorBadgeRenderer` observations; the worker upserts
those observations into the `MembershipBadgeCache` and maintains the inventory
map keyed by raw tooltip for the read-endpoint. On cache miss it fires a
rate-limited refresh trigger.

The cache lives **only in Redis** (no DB schema). Inline-enrichment writes
the resolved fields into the `badges` JSON column at INSERT time, so chat
history scrollback renders correctly without additional cache lookups -
identical to how Twitch subscriber badges are handled today.

## Cache Schema

| Key | Shape | TTL |
|-----|-------|-----|
| `lumio:yt:member:{account_id}:{member_channel_id}` | JSON `CachedMember` (tooltip, tier_name, duration, badge_url, display_name, avatar_url, last_seen_at) | 14 d sliding |
| `lumio:yt:tier_badges:{account_id}` | JSON map keyed by raw tooltip → `TierBadgeEntry` (tier_name, badge_url, duration, sort_order, first_seen_at, last_seen_at) | 14 d sliding |
| `lumio:yt:continuation:{account_id}:{live_chat_id}` | next-poll continuation token | 1 h |
| `lumio:yt:innertube_key` | InnerTube API key scraped from `youtube.com` | 24 h |
| `lumio:yt:innertube_version` | InnerTube client version scraped from `youtube.com` | 24 h |

Cleanup is TTL-driven; no cleanup worker.

## Tooltip Parsing

InnerTube is requested with `hl=en` so tooltips arrive in English and the
parser is locale-deterministic. Format observed in production:

| Tooltip | `tier_name` | `duration_value` | `duration_unit` |
|---|---|---|---|
| `Member (1 month)` | `Member` | `1` | `month` |
| `Member (6 months)` | `Member` | `6` | `months` |
| `Member (2 years)` | `Member` | `2` | `years` |
| `Diamantclub (3 months)` | `Diamantclub` | `3` | `months` |
| `New member` | `New member` | _null_ | _null_ |
| `Tier (Gold) (3 months)` | `Tier (Gold)` | `3` | `months` |

Frontend localizes via `next-intl` - a German viewer sees
`Member · 6 Monate` while an English viewer sees `Member · 6 months` for the
same persisted record.

## Polling

Badge observations arrive in the same InnerTube chat poll response as chat
events. The response includes a `timeoutMs` server hint (~10 000 ms in
practice); the worker honors that hint with a 1 s minimum and 3 s default when
the hint is absent.

When the worker sees a member it hasn't cached yet, that member simply renders
without custom badge artwork until the next poll carrying their `authorBadges`
upserts it into the cache. There is no separate observer worker and no
on-demand refresh queue - the `lumio:yt:refresh_pending` set and its per-member
`refresh_lock` debounce were removed once badge harvesting moved inline into the
chat worker.

## Schema-Drift Resilience

Every InnerTube response goes through `serde(default)` + `Option<…>`
deserialization, so missing or renamed fields decay to defaults rather than
hard-erroring. If a chat response lacks badge observations, the chat message is
still processed and rendered with whatever is already in the cache. Top-level
InnerTube response failures count against the normal chat transport failure
cascade; after 3 failures within 60 seconds, the worker falls through to the
configured gRPC or REST fallback.

## API Surface

### REST

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/v1/youtube/memberships/tiers` | List observed tier badges for the authenticated user's account. Requires an authenticated, account-scoped identity; the handler applies no `resource:action` guard and no feature guard of its own. |
| `DELETE` | `/v1/admin/privacy/youtube/member/{member_channel_id}?account_id=…&instruction_reference=…&initiated_by=…` | Erase a member channel on one channel's instruction (GDPR Art. 17): Lumio's member cache across every account, and the member's chat data in `account_id` only. All three query parameters are required; `initiated_by` is `channel` (the channel initiated the erasure and may withdraw it later) or `subject` (the person asked for it; never withdrawable). Requires the admin permission `admin:privacy-erase`, checked against the caller's admin roles. |

### GraphQL

| Operation | Type | Guard |
|---|---|---|
| `youtubeMembershipTiers` | Query | `FeatureGuard("feature:multichat")` **and** `PermissionGuard("chat:read")` |
| `eraseYoutubeMemberData(input: EraseYoutubeMemberDataInput!)` (`memberChannelId`, `accountId`, `instructionReference`, `initiatedBy`) | Mutation | admin permission `admin:privacy-erase` |

Response **payloads** are structurally identical - same fields, same
semantics, different case (snake_case vs. camelCase per Lumio convention).
`GET /v1/youtube/memberships/tiers` returns `{ "tiers": [ … ] }`;
`eraseYoutubeMemberData` and its REST twin both return `erased_key_count` /
`erasedKeyCount` and `erasure` - the same object as the result of the chat
erasure (GraphQL type `ChatSubjectErasureResult`: `account_id`, `case_id`, the per-table
deleted counts, `scrubbed_history_session_count`, `deleted_account_bot_count`,
`removed_held_queue_entry_count`,
`suppressed`). Both share the validation and the error texts
(`member_channel_id required`, `account_id is required`,
`instruction_reference is required`, `instruction_reference must be at most
200 characters`, `initiated_by is required`, `initiated_by must be one of:
channel, subject`; 404 `Account not found`). The tier query is the one place
where the two protocols differ on entry conditions: GraphQL enforces
`feature:multichat` + `chat:read`, REST enforces only account-scoped
authentication.

### WebSocket

There is no membership-specific WebSocket channel. Enriched badges reach the
frontend inline on chat messages over the account chat channel
(`chat:{account_id}`, gated on `chat:read` + `feature:multichat`), because the
worker merges the resolved badge fields into
`platform_chat_messages.badges` at INSERT time.

## InnerTube - What It Is, Why We Use It

InnerTube is YouTube's internal/private API consumed by every official YouTube
client (web, iOS, Android, TV). It carries the badge image URLs that the Data
API does not expose. Auth uses a public WEB-client API key embedded in
`youtube.com`'s JavaScript bundle - no OAuth.

Lumio's exposure is bounded:

- One bootstrap GET per broadcast (live-chat embed page) extracts the initial
  continuation token.
- One POST per polling cycle, paced by YouTube's `timeoutMs` server hint.
- The hot path (chat-message rendering, history reads) never hits InnerTube - it only reads from the Redis cache populated by the YouTube worker.

## Configuration

Settings live in the API config under `[youtube.innertube_observer]` (see
`apps/api/config/default.toml`). Each setting also accepts an
`LUMIO__YOUTUBE__INNERTUBE_OBSERVER__*` ENV override.

The InnerTube API key and client version are resolved at runtime in the order
**override (if set) → Redis cache → fresh `youtube.com` scrape → cold-boot
constant**, cached in Redis (24 h TTL) and refreshed every 6 h so Google's periodic
rotations are picked up without a restart. In addition to that timed refresh, a chat
poll that comes back **`400`/`403`** (the signal that Google rotated the key/version
out from under us) triggers an **immediate one-shot re-resolve**: the Redis cache is
bypassed, a fresh value is scraped from `youtube.com` and written back to Redis (so
parallel workers benefit), and the poll is retried **exactly once** with the fresh
credentials. If the fresh scrape matches the failing value the retry is skipped - there
is never a hot loop against `youtube.com`. A `403` caused by `quotaExceeded` is a quota
problem, not a credential one, so it is excluded from this path. The two `*_override`
settings below are an **emergency pin only** - leave them empty so auto-rotation stays
in charge. If an override *is* set, the API logs a single `WARN` the first time the
credential is resolved (`innertube: rotation disabled by pin (…) - unset to resume
auto-rotation`; the API key value is redacted) so a forgotten pin never silently
disables rotation. The two `*_cold_boot` settings configure the **Stage-4** last-resort
value used only after override, cache, and scrape all miss; because they are consulted
last they can never pin the credential. `default.toml` ships them **set** to the current
cold-boot values so a fresh deployment starts from a known-good credential; a cleared or
absent field falls back to the compiled default.

| Setting | Default | Purpose |
|---|---|---|
| `api_key_override` | _(empty)_ | Emergency pin for the InnerTube API key; set only if auto-detection fails after a Google rotation |
| `client_version_override` | _(empty)_ | Emergency pin for the InnerTube client version; set only if auto-detection fails |
| `api_key_cold_boot` | _(current key, shipped)_ | Stage-4 cold-boot API key; used only after override/cache/scrape all miss. Absent/empty → compiled `DEFAULT_INNERTUBE_API_KEY`. Never a pin |
| `client_version_cold_boot` | `2.20260731.00.00` | Stage-4 cold-boot client version; used only after override/cache/scrape all miss. Absent/empty → compiled `DEFAULT_CLIENT_VERSION`. Never a pin |
| `cache_ttl_seconds` | 1 209 600 | Member + tier-badge entry TTL (14 d) |
| `refresh_interval_secs` | 21 600 | Shared InnerTube credential refresher interval (6 h) |
| `cold_boot_alert_webhook_url` | _(empty)_ | Discord webhook for the Stage-4 cold-boot fall-through alert. Unset by default - a fall-through is still WARN-logged. Reuse the existing InnerTube health channel; do not create a second one |
| `cold_boot_alert_after_failures` | 1 | Alert only after this many consecutive refresh cycles observe a cold-boot fall-through. Edge-triggered - one alert per incident; a healthy cycle resets the streak. `0` is treated as `1` |

InnerTube proxy routing is configured one level up, under `[youtube]` (not
`innertube_observer`): `innertube_proxy_urls` (a host list the API fails over
between on transport error, non-2xx, or a `LOGIN_REQUIRED` body),
`innertube_proxy_url` (a back-compat single-host alias folded into that list),
and the shared `innertube_proxy_token`. Leave them unset for local development
and the API calls YouTube directly. Both a URL without a token and a token
without a URL log a warning and disable the proxy. See
[InnerTube Proxy](../developer-guide/innertube-proxy.md).

## Privacy & GDPR

Member-data (channel ID, display name, avatar URL, observed tier) lives only
in Redis with a 14-day sliding TTL. Lawful basis: legitimate interest under
Art. 6(1)(f) for providing the multichat to streamers - no profiling, no
cross-account tracking, no third-party sharing.

Subject rights:

- **Art. 17 (Erasure)** - the
  `DELETE /v1/admin/privacy/youtube/member/{id}` endpoint runs on one
  channel's instruction (`account_id`, `instruction_reference` and
  `initiated_by`). It clears every
  `lumio:yt:member:*:{id}` Redis entry across all accounts - Lumio's own
  YouTube API client cache, not channel data (plus any residual
  `lumio:yt:refresh_lock:*:{id}` debounce keys - no longer written and
  self-expiring in 60 s, but still swept defensively). It does **not** touch the
  [emote catalog](../developer-guide/emote-catalog.md): an emote shortcode plus
  its public CDN URL is cross-channel branding reference data, not personal data
  of the erased member, so it falls outside Art. 17 (founder ruling, 2026-08-19 -
  ZAF-580). The catalog is also shared - an emote the subject hosts is stored
  under other broadcasters' chats - so deleting it would blank those channels'
  history rather than erase the member's data. The endpoint writes exactly one
  system-scoped audit log row (`event_type = "youtube_member_erasure"`) naming
  the target account and the instruction reference, never the member's channel
  id.
- **Channel data** - historical messages carry the member's display name,
  avatar URL, and the enriched badge/emote JSONB at write time. Channel data
  belongs to the channel (founder ruling ZAF-2626), so the member-erasure
  endpoint deletes the member's data (`platform = 'youtube', user_id =
  memberChannelId`) in the instructing account only, exactly as the generic
  `POST /v1/admin/privacy/chat/erase` endpoint (GraphQL `eraseChatSubjectData`)
  does: chat messages, profile, moderator notes, AutoMod and moderation-log
  rows, bot-list entry and stream-history entries, and it records the member
  in that account's suppression list. Other channels keep their data; their
  erasure needs their own instruction. The counts are reported in `erasure`
  (`deletedMessageCount` and the rest) - see
  [Chat › Erasure](./chat.md#erasure-gdpr-art-17).

## Key Files

| File | Purpose |
|---|---|
| `crates/lo-youtube-api/src/innertube/{mod,types,scraper,parser}.rs` | InnerTube schema + scraper + tooltip parser |
| `crates/lo-youtube-api/src/innertube/browse.rs` | Proxy host pool and multi-host failover for InnerTube requests |
| `crates/lo-chat/src/youtube_badges.rs` | `MembershipBadgeCache` (LRU + Redis) + `enrich_youtube_member_badge()` |
| `apps/api/src/workers/youtube.rs` | InnerTube chat ingestion, badge observations, and inline enrichment |
| `apps/api/src/services/innertube_credentials.rs` | InnerTube API key + client version resolution |
| `apps/api/src/workers/innertube_credentials.rs` | Shared 6 h credential refresher |
| `apps/api/src/services/youtube_memberships.rs` | Read + erasure service |
| `apps/api/src/routes/youtube_memberships.rs` | REST endpoints |
| `apps/api/src/graphql/youtube_memberships.rs` | GraphQL query + mutation |
| `apps/web/src/components/chat-badges.tsx` | Localized tooltip render |

---

## Features / Roles & Permissions

Source: https://docs.lumio.vision/features/roles

# Roles & Permissions

## Overview

The Roles & Permissions module implements a granular Role-Based Access Control (RBAC) system. Every account starts with 3 default roles (Owner, Administrator, Moderator), and custom roles can be created. The registry defines **133 account-scope permissions across 31 categories**, plus **105 admin-scope permissions across 38 categories** and **10 user-scope permissions**, all using a `resource:action` naming convention (e.g., `chat:read`, `overlays:edit`). Permissions are enforced at the GraphQL layer via `PermissionGuard` and at the REST layer via `Auth::require_permission()`. Permission checks are cached in Redis for performance.

CRUD authority is always granular - `create` / `edit` / `delete`, never a lumped `resource:write`. (`chat:write` is the one `write` action in the registry, and it is a verb - "send a chat message" - not a CRUD grant.) Roles also cannot carry wildcards; see [Wildcards](#wildcards).

## Architecture

### Backend

- **RBAC Registry** (`crates/lo-auth/src/rbac.rs`) -- All permission constants organized into three modules: `global` (admin-scope), `account` (per-account), and `user` (user-scope, cross-account - the Ideas Hub set). Default role definitions with their permission sets. Plan-based limits. This is a single file, not a directory.
- **Permission Guards** -- `lo_graphql::PermissionGuard` for GraphQL resolvers, `Auth::require_permission()` for REST endpoints; both resolve against the active account. `AdminPermissionGuard` / `require_admin_permission()` and `require_user_permission()` cover the other two scopes.
- **Permission Cache** -- Permissions are cached in Redis per user/account pair. The cache is invalidated on member role change and member removal via `lo_api::middleware::auth::invalidate_permission_cache()`.
- **Database** -- Roles live in `account_roles`, their permissions in the `account_role_permissions` join table. Default roles are created on account creation.
- **WebSocket** -- Roles have no channel of their own, but account permissions gate the WebSocket channels: `channel_gate_for` in `crates/lo-websocket/src/gate.rs` maps `events` → `events:read`, `chat` → `chat:read`, `spotify` → `spotify:read`, `automations` → `automations:read`, `history` → `history:read`; `ext-storage` takes `extension-store:read` in the account that owns the install; `ext-install-logs` takes `bot-modules:read` or `automations:read` according to the install's extension category.

### Default Roles

Defined as `ROLE_OWNER` / `ROLE_ADMIN` / `ROLE_MODERATOR` in `rbac.rs`.

| Role | Slug | Color | System | Sort | Description |
|------|------|-------|--------|------|-------------|
| **Owner** | `owner` | `#f59e0b` | Yes | 0 | Full account access - every account permission, listed explicitly. Cannot be deleted or assigned to another member. |
| **Administrator** | `administrator` | `#ef4444` | No | 1 | Full access except account deletion and plan changes (enforced via the `owner_id` check, not by permissions). |
| **Moderator** | `moderator` | `#22c55e` | No | 2 | Chat moderation and event monitoring. |

In the admin app, **Add Member** requires an account-owned role and offers the account's roles through `adminAccountRoles` / `GET /v1/admin/accounts/{id}/roles` (`accounts:read`). The picker hides the Owner/system role and leaves the role unselected until the operator chooses one; adding the member requires `accounts:edit`.

## API

### GraphQL Queries

| Query | Returns | Permission |
|-------|---------|------------|
| `roles` | `[Role!]!` | `roles:read` |
| `role(id: UUID!)` | `RoleDetail` | `roles:read` |
| `availablePermissions` | `[AccountPermission!]!` | `roles:read` |
| `myPermissions` | `[String!]!` | `AuthGuard` |

`Role` carries `permissionCount` and `memberCount` for the list view; `RoleDetail` carries the full `permissions: [String!]!` array. `AccountPermission` is `{ key, label, category }` - the role-editor catalog.

`myPermissions` returns the permissions of the **current auth context**: fresh account-role permissions from the database for a JWT user, and exactly the token's own scope for a scoped API key or popout token (never a `["*"]` sentinel). Its REST twin is `GET /v1/tokens/me`.

### GraphQL Mutations

| Mutation | Args | Returns | Permission |
|----------|------|---------|------------|
| `createRole` | `input: CreateRoleInput!` | `RoleDetail!` | `roles:edit` |
| `updateRole` | `input: UpdateRoleInput!` | `RoleDetail!` | `roles:edit` |
| `deleteRole` | `id: UUID!` | `RoleMutationResult!` | `roles:delete` |

`CreateRoleInput` is `{ name!, description, color, permissions! }`; `UpdateRoleInput` is `{ id!, name, description, color, permissions }`. Neither accepts `sortOrder` - sort order is assigned by the system.

Role creation derives the `slug` from the name (lowercased, spaces replaced with `-`) and assigns a random pastel `color` when none is supplied.

### REST Endpoints

All paths live under `/v1/roles`. Bodies are snake_case and mirror the GraphQL inputs.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/roles` | `roles:read` | List roles for the account |
| `GET` | `/v1/roles/{id}` | `roles:read` | Get a single role with its permissions |
| `POST` | `/v1/roles` | `roles:edit` | Create a role (`name`, `description`, `color`, `permissions`) |
| `PATCH` | `/v1/roles/{id}` | `roles:edit` | Update role name, description, color, or permissions |
| `DELETE` | `/v1/roles/{id}` | `roles:delete` | Delete a role (system roles cannot be deleted) |
| `GET` | `/v1/roles/permissions` | `roles:read` | Catalog of available account permissions (`key`, `label`, `category`) |

### Wildcards

`createRole` and `updateRole` validate **every** submitted permission string against the account registry (`lo_auth::rbac::account::get_all_account_permissions()`), identically on GraphQL and REST, rejecting anything unknown with `Invalid permission: <key>`. The registry contains no `:*` keys, so a wildcard can never be persisted into an account role. Wildcard grants (`resource:*`, `*:*`) exist only on config-provisioned System keys. System-key-only grants such as `bots:internal` are not in the account registry either, so they are rejected here as unknown permissions.

## Permissions

### Admin-Scope Permissions

105 permissions, exhaustively enumerated by `all_admin_permissions()` in `rbac.rs` (pinned by `all_admin_permissions_returns_expected_count`); the category is derived from the segment before the `:`. `admin:access` is only the dashboard-entry gate for the admin app - every element inside is additionally gated on its own `resource:action`. `audit:ingest` is a system-key-only grant in effect; the ingest endpoint requires a System auth context and does not accept a human admin role grant.

| Category | Permissions |
|----------|-------------|
| `admin` | `admin:access`, `admin:privacy-erase`, `admin:privacy-objection-create`, `admin:privacy-objection-delete`, `admin:privacy-erase-withdraw` |
| `users` | `users:read`, `users:edit`, `users:delete` |
| `accounts` | `accounts:read`, `accounts:edit`, `accounts:delete`, `accounts:overrides-read`, `accounts:overrides-edit` |
| `billing` | `billing:read`, `billing:edit` |
| `support` | `support:read`, `support:edit`, `support:verify` |
| `features` | `features:read`, `features:edit` |
| `plans` | `plans:read`, `plans:create`, `plans:edit`, `plans:delete` |
| `subscriptions` | `subscriptions:read`, `subscriptions:edit` |
| `coupons` | `coupons:read`, `coupons:create`, `coupons:edit`, `coupons:delete` |
| `audit` | `audit:read`, `audit:ingest` |
| `audit-log` | `audit-log:read` |
| `csp-reports` | `csp-reports:read` |
| `devtools` | `devtools:read` |
| `platforms` | `platforms:read`, `platforms:edit` |
| `providers` | `providers:read`, `providers:edit` |
| `feature-flags` | `feature-flags:read`, `feature-flags:edit` |
| `se-tokens` | `se-tokens:read`, `se-tokens:delete` |
| `bot-commands` | `bot-commands:read`, `bot-commands:create`, `bot-commands:edit`, `bot-commands:delete` |
| `bot-control` | `bot-control:read`, `bot-control:edit` |
| `bot-connections` | `bot-connections:read`, `bot-connections:create`, `bot-connections:delete` |
| `developer-limits` | `developer-limits:read`, `developer-limits:edit` |
| `developer-verification` | `developer-verification:read`, `developer-verification:edit` |
| `developer-funds` | `developer-funds:release-deletion`, `developer-funds:settle` |
| `discord-guilds` | `discord-guilds:read`, `discord-guilds:delete` |
| `extension-review` | `extension-review:read`, `extension-review:edit` |
| `extension-purchases` | `extension-purchases:read` |
| `contract-declarations` | `contract-declarations:read`, `contract-declarations:edit` |
| `oauth-clients` | `oauth-clients:read`, `oauth-clients:create`, `oauth-clients:edit`, `oauth-clients:delete` |
| `system-keys` | `system-keys:read`, `system-keys:create`, `system-keys:delete` |
| `account-apikeys` | `account-apikeys:read`, `account-apikeys:edit`, `account-apikeys:delete`, `account-apikeys:rotate` |
| `system-connections` | `system-connections:read`, `system-connections:edit`, `system-connections:delete` |
| `admin-roles` | `admin-roles:read`, `admin-roles:create`, `admin-roles:edit`, `admin-roles:delete` |
| `copyright` | `copyright:read`, `copyright:edit`, `copyright:delete`, `copyright:moderate` |
| `obs` | `obs:read`, `obs:edit` |
| `bot-modules` | `bot-modules:read`, `bot-modules:edit` |
| `user-roles` | `user-roles:read`, `user-roles:create`, `user-roles:edit`, `user-roles:delete` |
| `ideas` | `ideas:moderate_read`, `ideas:moderate_status`, `ideas:moderate_edit`, `ideas:moderate_delete`, `ideas:moderate_comment` |
| `crawler` | `crawler:scope-read`, `crawler:scope-edit`, `crawler:watchlist-read`, `crawler:watchlist-create`, `crawler:watchlist-delete` |

Several action strings, including `bot-commands:read`, `copyright:read`, `obs:read`, and `se-tokens:read`, are declared in **both** the `global` and `account` modules. The same string can therefore exist at system and account scope; handlers use the appropriate guard for the resource.

### Account Permissions

133 permissions in 31 categories, sourced from `account::get_all_account_permission_infos()` (pinned by `account_permission_infos_has_expected_count`) - the single source of truth behind the role-editor picker (`GET /v1/roles/permissions` / `availablePermissions`) *and* the create/update validation registry.

| Category | Permissions |
|----------|-------------|
| **Events** | `events:read`, `events:create`, `events:userinfo` |
| **Overlays** | `overlays:read`, `overlays:create`, `overlays:edit`, `overlays:delete`, `overlays:access-read`, `overlays:access-grant`, `overlays:access-revoke` |
| **Spotify** | `spotify:read`, `spotify:playback`, `spotify:volume`, `spotify:queue`, `spotify:playlist`, `spotify:device`, `spotify:worker` |
| **Chat** | `chat:read`, `chat:write`, `chat:userinfo`, `chat:delete`, `chat:ban`, `chat:timeout`, `chat:notes`, `chat:raid`, `chat:refresh_user`, `chat:poll`, `chat:prediction`, `chat:automod-read`, `chat:automod-allow`, `chat:automod-deny`, `chat:pin`, `chat-bots:read`, `chat-bots:edit` |
| **Connections** | `connections:read`, `connections:create`, `connections:edit`, `connections:delete` |
| **Settings** | `settings:read`, `settings:edit` |
| **Account** | `account:read`, `account:edit`, `account:delete` |
| **Plan** | `plan:read`, `plan:edit` |
| **Members** | `members:read`, `members:create`, `members:edit`, `members:delete` |
| **Roles** | `roles:read`, `roles:edit`, `roles:delete` |
| **Login Assignments** | `login-assignments:read`, `login-assignments:create`, `login-assignments:delete` |
| **Uploads** | `uploads:read`, `uploads:create`, `uploads:delete` |
| **Rewards** | `rewards:read`, `rewards:create`, `rewards:edit`, `rewards:delete` |
| **Tokens** | `tokens:read`, `tokens:create`, `tokens:edit`, `tokens:delete` |
| **API Keys** | `apikeys:read`, `apikeys:create`, `apikeys:edit`, `apikeys:delete` |
| **Automations** | `automations:read`, `automations:create`, `automations:edit`, `automations:delete`, `automations:execute` |
| **OBS** | `obs:read`, `obs:edit`, `obs:delete` |
| **Copyright** | `copyright:read`, `copyright:edit`, `copyright:delete`, `copyright:vote`, `copyright:report`, `copyright:recommend` |
| **Bot Modules** | `bot-modules:read`, `bot-modules:edit` |
| **Bot Commands** | `bot-commands:read`, `bot-commands:create`, `bot-commands:edit`, `bot-commands:delete` |
| **Bot Connections** | `bot-connections:read`, `bot-connections:create`, `bot-connections:delete` |
| **StreamElements** | `se-tokens:read`, `se-tokens:create`, `se-tokens:delete` |
| **Extension Developer** | `extension-dev:read`, `extension-dev:create`, `extension-dev:edit`, `extension-dev:delete`, `extension-dev:publish`, `extension-dev:analytics`, `extension-dev:payouts` |
| **Extension Store** | `extension-store:read`, `extension-store:install`, `extension-store:uninstall`, `extension-store:configure`, `extension-store:review` |
| **Extension Data** | `extension-data:read`, `extension-data:edit` |
| **Widgets** | `widgets:read`, `widgets:create`, `widgets:edit`, `widgets:delete`, `widgets:access-read`, `widgets:access-grant`, `widgets:access-revoke` |
| **Sounds** | `sounds:read`, `sounds:create`, `sounds:edit`, `sounds:delete`, `sounds:play` |
| **Stream History** | `history:read`, `history:share`, `history:export`, `history:delete`, `history:revenue-read`, `history:revenue-edit`, `history:keywords-edit` |
| **Setting Presets** | `presets:share` |
| **Public Stats** | `public-stats:read`, `public-stats:edit` |
| **Audit Log** | `audit-log:read` |

Adding an account permission means adding it to `get_all_account_permission_infos()` **and** seeding it for the `owner` role in a migration; the registry and both pickers then follow automatically.

### User-Scope Permissions

10 permissions in `rbac::user`, granted through global user roles rather than account roles. They cover the Ideas Hub: `ideas:read`, `ideas:create`, `ideas:edit`, `ideas:delete`, `ideas:vote`, `ideas:comment_read`, `ideas:comment_create`, `ideas:comment_edit`, `ideas:comment_delete`, `ideas:comment_vote`. See [Ideas Hub › Permissions](./ideas-hub.md#permissions).

## Plan-Based Limits

Plan limits live in the canonical `plans` table (seeded rows; `apps/api/src/db/plans.rs`), not a hard-coded Rust table (ZAF-1092). These are defaults; the numeric limits below can be overridden per account via the `account_limits` table, except `max_commands`, which reads the plan row directly (no per-account override). `0` = unlimited.

| Limit | Free | Pro |
|-------|------|-----|
| Max overlays | 1 | 5 |
| Max storage | 100 MB | 1 GB |
| Max upload size | 10 MB | 50 MB |
| Max integrations | 2 | 10 |
| Channel data retention (chat, events, chatter profiles, moderation) | 365 days | 1095 days |
| Max bot commands | 25 | 200 |

An Enterprise tier once existed, but its plan row was removed (migration `20260415000009_drop_enterprise_plan`) and its accounts were moved to Pro; nothing resolves to it at runtime.

Capability toggles such as custom bot, OBS remote, and Copyright Manager are **feature flags plus `plan_features` rows**, not plan-limit columns - the boolean columns that once held them were dropped from `account_limits` when feature flags took over. See [Billing](./billing.md).

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `account_roles` | PostgreSQL | `id`, `account_id`, `name`, `slug`, `description`, `is_default`, `is_system`, `color`, `sort_order`, `created_at`, `updated_at`. `UNIQUE(account_id, name)` and `UNIQUE(account_id, slug)`. |
| `account_role_permissions` | PostgreSQL | `(role_id, permission)` join table - one row per granted permission, `ON DELETE CASCADE` |
| `account_memberships` | PostgreSQL | Links users to accounts with a nullable `role_id` FK to `account_roles` |
| `admin_roles` / `admin_role_permissions` | PostgreSQL | Admin-scope roles and their grants |
| `user_roles` / `user_role_permissions` | PostgreSQL | User-scope roles and their grants |

## Data Flow

1. On account creation, the default roles (Owner, Administrator, Moderator) are inserted into `account_roles` with their predefined permission sets written to `account_role_permissions`.
2. The account owner is assigned the Owner role automatically.
3. When a user makes an API request, the auth middleware resolves their permissions:
   - Check Redis cache for the user/account pair.
   - If not cached, query the user's role and its permissions from PostgreSQL.
   - Cache the result in Redis.
4. GraphQL resolvers check permissions via `PermissionGuard::new("resource:action")`.
5. REST endpoints check permissions via `auth.require_permission("resource:action")`.
6. When a member's role is changed or a member is removed, the Redis cache is invalidated for that user/account pair.

Frontend gating mirrors the backend: `<Gate permission="resource:action">` hides controls in both the dashboard and the admin app, but it is a UX layer - the backend guard is the authority.

## Key Files

| Path | Description |
|------|-------------|
| `crates/lo-auth/src/rbac.rs` | Permission registry (`global` / `account` / `user`), default roles |
| `crates/lo-graphql/src/guard.rs` | `PermissionGuard`, `AdminPermissionGuard`, `AuthGuard`, `SystemGuard::new(grant)` (System key **and** a named grant — never type-only) |
| `crates/lo-api/src/extractors.rs` | `Auth` extractor with `require_permission()` |
| `crates/lo-api/src/middleware/auth.rs` | Permission cache and `invalidate_permission_cache()` |
| `crates/lo-websocket/src/gate.rs` | Permission gates for WebSocket channels |
| `apps/api/src/graphql/roles.rs` | GraphQL role queries and mutations |
| `apps/api/src/routes/roles.rs` | REST role endpoints |

---

## Features / Connections

Source: https://docs.lumio.vision/features/connections

# Connections

Channel and bot authorization in the dashboard begins with a dialog that explains the requested permissions. A successful or failed return appears as a toast. Channel reconnection verifies the same platform account, and bot connection refuses the main account. Login connections are managed separately under [Security → Sign-in](/user-guide/account-security); adding or removing one requires a fresh step-up, while reconnecting the same account is exempt.

## Overview

The Connections module manages platform OAuth connections for Lumio accounts. It handles **app credentials** when a platform needs the account's own OAuth app, **channel connections** that store the channel access/refresh tokens, and **credential modes** that tell the dashboard whether a new connection uses Lumio's global OAuth app for that `(platform, kind)` pair or account-owned credentials. The module supports CSRF protection via Redis-stored state handles, automatic token refresh, and encrypted credential storage. All secrets are encrypted at rest using AES-256 derived from a master key.

The dashboard presents these as the [Connections group](/user-guide/connections) of the settings window, on its channel side (`#settings/channel/connections/<area>`, short link `/dashboard/settings/channel/connections/<area>`). Its areas are Overview, Twitch, YouTube, Kick, Spotify, Discord and Services. A platform area contains its channel, rights, chat bot (except Spotify) and OAuth app. Discord server connections live in the Discord area; OBS, StreamElements and Shopify live in Services. Each area and section is shown only when its feature, provider and read permission are available; each area loads through its own settings section route, which applies the same gate. The group root `/dashboard/settings/channel/connections` directs query strings such as `?reconnect=spotify` and OAuth results to the named area, or to Overview when none is named. `/dashboard/settings/channel/connections/shopify` (also with `?connected=shopify` or `?platform=shopify`) opens Services at its Shopify section; the same path with `#link=<handle>` is the Shopify link-confirm screen (see [Shopify › Web routes](./shopify.md#web-routes-and-dashboard)). Bookmarks to the former Connections hub redirect permanently (308) to the matching short link and keep the query.

> **Foreign channels are not connections:**
> Public stats for **non-connected** channels are gathered without any OAuth
> connection by the [Public Stats Crawler](../developer-guide/public-stats-crawler.md)
> (anonymous Twitch IRC read + app-token Helix polling). A connection is only ever
> created for a channel a Lumio account explicitly links here.

## Channel status and followers

`channelStatus` / `GET /v1/channel-status` reports each platform's live, offline or scheduled status under `connections:read`. The Spotify manual-status operation remains under `spotify:read`. The dashboard uses the channel's URL-safe login or slug for Twitch and Kick links; a scheduled YouTube broadcast links to its watch page.

`channelSchedule(from, to)` / `GET /v1/channels/schedule` (also `connections:read`) lists the planned broadcasts of the connected channels: YouTube scheduled broadcasts, the Twitch schedule (Helix `GET /schedule`) and the Kick calendar (undocumented, see below). See [Channel Status → Stream plan](./channel-status.md#stream-plan).

`channelConnections { followerCount }` reads the channel's follower count when the field is selected. REST `GET /v1/connections/channel?include=follower_count` fills `follower_count`; without that include it is `null`. Twitch uses Helix follower totals, YouTube uses an approximately rounded subscriber count (three significant digits), and Kick accepts the string-valued v2 follower count. Spotify has no follower count. Results are cached for 10 minutes (failed lookups for 2 minutes), with stored public channel metrics as a fallback; an unavailable count remains `null`. A connection needing reconnect does not trigger a platform lookup. Unknown REST `include` values return 400.

`channelConnections { paidSubscriberCount }` (REST `?include=paid_subscriber_count` → `paid_subscriber_count`) reads the channel's current paid subscribers. It needs `history:read` on top of `connections:read`; without it the field is `null`, never an error.

| Platform | Source | Notes |
|----------|--------|-------|
| Twitch | Helix `GET /subscriptions?broadcaster_id=…&first=1` → `total`, with the channel connection's token | Gifted subs included. Needs `channel:read:subscriptions`; an older grant without it gives `null` until the owner reconnects (the connection notice already lists the missing scope). Twitch does not document whether the broadcaster's own channel sub counts, so nothing is subtracted. |
| Kick | Official `GET /public/v1/channels?broadcaster_user_id=…` → `active_subscribers_count`, with the channel connection's token | The kick.com v2 website JSON has no subscriber count (only `followers_count`). Kick also reports `active_gifted_subscribers_count` separately; Lumio shows `active_subscribers_count` unchanged. |
| YouTube | — (always `null`) | Memberships are not readable: Data API `members.list` is restricted to approved partners and InnerTube has no member count. YouTube "subscribers" are followers and appear in `followerCount`. |
| Spotify | — (always `null`) | |

The number is never estimated from events and has no public-metrics fallback. Results are cached in Redis like the follower count (10 minutes, unavailable for 2 minutes); tokens refresh through `get_fresh_connection_token`, and a connection needing reconnect is not asked. Reading the number emits no audit event.

## Login Connection Assignments

Login connections (Twitch, YouTube, etc.) are managed at the user level. Each user can have multiple login connections per platform. When a user is a member of multiple Lumio accounts, they can assign which login connection to use on each account.

This allows scenarios like:
- A creator with separate streaming channels assigns different Twitch accounts to different Lumio accounts
- A moderator assigns their personal Twitch login to the accounts they moderate on

Assignments are managed from the Profile page (user-centric view) or the Account Management page (account-centric view).

### Which account an assignment targets

`assignLoginConnection` / `removeLoginAssignment` (and their REST twins) take an
optional `account_id` and fall back to the caller's **active** account when it is
omitted. Because Profile is a user-centric surface, it always sends the account
the user picked - both from the **Add connection** modal, where the pick is
carried through the ID App's OAuth round-trip as `assign_account_id`, and from
the per-connection **Assign** modal. The account switcher does not decide where a
login lands.

A supplied `account_id` must be an account the caller genuinely belongs to. When
the caller acts on their **own** login connection, any account in their
membership list is accepted - the same list the picker offers, so the UI and the
gate cannot drift. When acting on **another user's** connection (`user_id`
supplied, gated on `login-assignments:create` / `:delete`), the target is pinned
to the active account, because those permissions are resolved for the active
account's roles. Anything else - an account the caller holds no membership in -
is rejected with `You do not have access to the target account`.

### Database

Assignments are stored in the `account_login_assignments` table, which maps a login connection to a specific account for a specific user:

| Column | Type | Description |
|--------|------|-------------|
| `account_id` | `UUID` (FK) | Account the connection is assigned to |
| `user_id` | `UUID` (FK) | Owner of the login connection |
| `login_connection_id` | `UUID` (FK) | The login connection being assigned |
| `provider` | `TEXT` | Platform provider (e.g. `twitch`, `google`) |

### Permissions

| Permission | Description |
|-----------|-------------|
| `login-assignments:read` | View login connection assignments for all users on the account. Own assignments are always visible without this permission. |
| `login-assignments:create` | Assign a login connection on behalf of another user. Own assignments are always allowed. |
| `login-assignments:delete` | Remove a login assignment on behalf of another user. Own assignments are always removable. |

### API

| Protocol | Operation | Permission |
|----------|-----------|------------|
| REST | `GET /v1/accounts/login-assignments` | `login-assignments:read` (own always visible) |
| REST | `POST /v1/accounts/login-assignments` | `login-assignments:create` (own always allowed) |
| REST | `DELETE /v1/accounts/login-assignments/{provider}` | `login-assignments:delete` (own always allowed) |
| REST | `GET /v1/users/me/login-connections` | Authenticated |
| REST | `DELETE /v1/login-connections/{id}` | Session (own connection) + step-up in the last 10 minutes |
| GraphQL | `disconnectLoginConnection(loginConnectionId: UUID!)` | Session (own connection) + step-up in the last 10 minutes |

Login assignments are also broadcast on the WebSocket channel
`login-assignments:{key}`, which is gated `Public` - it carries no credential
material, only the fact that an assignment changed, so a connected dashboard
can refetch.

Login connections do not decide a channel's name or picture; that comes from a channel connection or the channel's own details (see [Channel name and picture](#channel-name-and-picture)).

## Channel name and picture

A Twitch, YouTube or Kick channel connection can be the channel's name and picture source (Spotify cannot). The name is the connection's `channel_name`; the picture is `channel_connections.channel_avatar_url` - the Twitch `profile_image_url`, the YouTube channel thumbnail or the Kick profile picture. It is filled on connect, on reconnect and by the boot-time sync `sync_channel_identities`. Only URLs on hosts already allowed by the web CSP are kept (`static-cdn.jtvnw.net`, `yt3.ggpht.com`, `lh3.googleusercontent.com`, `files.kick.com`); otherwise the column stays empty and the initial is shown. While a connection is the source, `accounts.name` mirrors its channel name.

Disconnecting the connection that is the source - `disconnectChannel` / `DELETE /v1/connections/channel/{platform}`, or the admin `adminDeleteAccountChannelConnection` / `DELETE /v1/admin/accounts/{id}/connections/{platform}` - switches the channel to its own details with the connection's last channel name and the initial. The owner gets an in-app notification (type `channel_identity_source_removed`, link `/dashboard/settings/channel/general`). The source is chosen in the channel settings; the endpoints are described in [Accounts › Channel name and picture](./accounts.md#channel-name-and-picture).

## What a disconnect stops and deletes

Every path that removes a channel connection - `disconnectChannel` / `DELETE /v1/connections/channel/{platform}`, the admin `adminDeleteAccountChannelConnection` / `DELETE /v1/admin/accounts/{id}/connections/{platform}`, and the cascade of `deleteAppCredentials` / `DELETE /v1/connections/credentials/{platform}` - goes through one service (`services::account_identity`), so the protocols behave the same:

1. The platform's worker (Twitch EventSub, YouTube polling, Kick, Spotify) stops on the replica that handled the request, and the other API replicas are told over Redis (`lumio:account_workers`). Every replica also stops, once a minute and when it (re)subscribes, any platform worker whose connection no longer exists, in case a message was lost. The account's other platforms keep running.
2. The connection row and its encrypted tokens are deleted. Disconnecting YouTube also deletes the associated revenue data (the revenue tables reference the connection with `ON DELETE CASCADE`) and revokes Lumio's Google grant; the YouTube API Services Developer Policies require this. The disconnect dialog states this before confirmation.

Nothing else is deleted. The channel's data belongs to the channel: the chatter profiles, moderator notes, moderation log, AutoMod history log, chat messages, platform events and stream history the account holds for that platform stay. A Twitch disconnect also leaves the AutoMod queue (held messages in Redis, `lumio:automod:held:{account_id}`) in place, and it expires on its own within 30 minutes. The kept rows follow the plan retention window: the retention sweeps work per account and do not depend on a live connection, so they keep running after a disconnect. They are deleted at the latest when the channel is dissolved or the account is deleted. A reconnect of the same platform sees them again.

## Reconnect Flags

All three connection tables (`channel_connections`, `login_connections`, and `bot_connections`) have a `reconnect_required` boolean column (default `false`).

When `reconnect_required` is set to `true` on a connection:

- The **Token Refresh Worker** skips the connection entirely during its refresh cycle (it no longer retries a dead grant every hour).
- All token retrieval functions (`get_fresh_connection_token`, `get_fresh_bot_token`, `get_fresh_oauth_token`) return a `RowNotFound` error for the flagged connection, causing platform workers that depend on it to stop gracefully.
- Users see a red entry in the dashboard's [connection notices](#connection-notices) with a direct reconnect button.
- The `reconnect_required` field is exposed on the connection APIs (GraphQL `ChannelConnection.reconnectRequired`, REST `reconnect_required` on `/v1/connections/channel`), so the dashboard shows a **"Reconnect required"** state rather than treating a lapsed 1-hour access token as an error.
- The **connection-status overview** that feature surfaces read (Music control, Events, Multichat - including their popouts) also carries the health signal: `ConnectionStatus` (GraphQL `connectionStatuses`, REST `GET /v1/connections/status`) exposes `reconnectRequired` and `expiresAt`, and its `isConnected` is **health-aware** - a flagged connection reports `isConnected: false` so a dead channel never renders a healthy-looking control that then silently fails. To tell "no connection" from "flagged connection", read `reconnectRequired` (a connection exists iff `isConnected || reconnectRequired`). Popout tokens carrying `connections:read` can read this overview; the first-party-only `flaggedConnections` query is unaffected.

### Login-grant health

The Multichat **sends** with the acting user's personal **login grant** (twitch→twitch, youtube→google, kick→kick), not the account's channel connection, so `connectionStatuses` (GraphQL) / `GET /v1/connections/status` (REST) additionally expose that grant's health per platform, **separately** from the channel signal:

- `loginConnected` (`login_connected`) - `true` when the user's login grant for this platform (via `account_login_assignments`) exists and is healthy.
- `loginReconnectRequired` (`login_reconnect_required`) - `true` when that login grant exists but is flagged `reconnect_required`; the send will fail until the user reconnects it.

- `loginMissingScopes` (`login_missing_scopes`) - the scopes Lumio's login asks for that the stored login grant lacks (for example `moderator:manage:automod`, which Twitch AutoMod Allow/Deny needs). Empty when nothing is missing, when the stored scopes are unknown (an empty array on older grants) or when there is no grant. OpenID identity scopes (`openid`, `email`, `profile`) are never reported. The backend's login-scope lists (`TWITCH_LOGIN_SCOPES`, `GOOGLE_LOGIN_SCOPES`, `KICK_LOGIN_SCOPES` in `apps/api/src/platforms.rs`) mirror `apps/id/src/lib/providers.ts`; `apps/api/tests/login_scopes_drift.rs` fails when they differ.

`loginConnected` and `loginReconnectRequired` are `false` when there is no login grant, no user context (fail-closed - an unknown grant is never reported connected), or the platform is not sent-to via a login grant (e.g. Spotify). The channel signals (`isConnected` / `reconnectRequired`) are **unchanged** - the login fields are additive, so a dead login grant never mutates the channel's connected state. This is the data source the Multichat reads to warn *before* the first send attempt, and it rides the same popout-readable overview (no new guard).

### Missing scopes

A connection can be healthy and still lack required scopes that Lumio requests today — for example a Kick connection without `kicks:read`, `channel:rewards:read` or `ads:read`. Each channel connection carries **`missing_scopes`** (GraphQL `ChannelConnection.missingScopes`, REST `missing_scopes` on `GET /v1/connections/channel`, same `connections:read` guard as `scopes`): the base scopes the grant lacks, `[]` when nothing is missing. A connection whose granted scopes were never recorded (legacy rows) reports `[]`, not a false "reconnect".

In the web app a non-empty `missing_scopes` shows as an amber **New permissions available** hint on the connection card and as an amber entry in the [connection notices](#connection-notices) of the dashboard, Events and Chat (only for members holding `connections:create`, and not for a connection already flagged `reconnect_required`). The hint names the features the missing scopes unlock (Kick: KICKs, channel points and ads) and falls back to a generic sentence for a scope it has no label for. Its **Grant {platform} permission** button is the normal connect flow.

Reconnecting through the normal connect flow requests the full current scope list on the same connection. Google can let you decline an optional scope. For Kick, the worker then subscribes to the events that were missing. Details: [Channel Connections & OAuth Scopes](../developer-guide/channel-connections-oauth-scopes.md#missing-scopes).

The channel connection's required and optional OAuth scopes are available to members with `connections:read` through GraphQL `channelOAuthScopes(platform)` or REST `GET /v1/connections/oauth-scopes/{platform}`. Both require `feature:connections`; the connect flow requests both lists. Kick ad-break estimates need the required scope `ads:read`. If Kick refuses an ad-break status request with 403, Lumio removes `ads:read` from the stored grant and shows the reconnect prompt.

YouTube also requests `yt-analytics-monetary.readonly` on every channel connect, but it is **optional** on Google's consent screen. Declining it never fills `missing_scopes` and never produces a standing connection-card or AlertDeck warning. Only the [Stream History revenue area](/features/stream-history#revenue-and-currency) explains a missing grant. An existing connection without the scope gets one dismissible announcement on the history list. The own-app guide on the YouTube tab marks the Analytics scope optional and shows its full Google name. The YouTube connect dialog explains that members with **View revenue** (`history:revenue-read`) can see the YouTube amounts; there is no separate sharing switch. See [YouTube Analytics API setup](/getting-started/oauth-setup#youtube-analytics-api).

### Where the reconnect state is shown

The dashboard makes the reconnect-required state visible everywhere a dead connection would otherwise fail silently - for **all** platforms (Twitch, YouTube, Kick, Spotify) and for login connections alike:

- **Account → Profile · Login connections** - a flagged login shows a **"Reconnect required"** badge (instead of the default green *Connected* badge), an inline error on the affected connection card with a highlighted **Reconnect** button, and a page-level reconnect banner. A healthy login is unchanged.
- **Music control** (dashboard **and** popout) - a flagged Spotify grant puts the player into an **unavailable** state: it stays visible but dimmed, with the last known track (or the empty state) and every control disabled. The notice and its repair action are a [connection notice](#connection-notices) above it, so Spotify is reported once. This is unrelated to the transient *"Connection lost - reconnecting…"* WebSocket notice.
- **Events** (dashboard **and** popout) - the per-platform stats row (viewers / likes / views) shows a **reconnect-required error pill** for a flagged **chat** platform (Twitch, YouTube, Kick), and keeps showing it even while that channel is offline (a dead OAuth grant is exactly when nothing is online). The pill is the platform logo plus a red warning triangle, with the platform name and the expiry in its tooltip. A dead non-chat grant (Spotify) is **not** shown here - it belongs to the Music surface above, because this header speaks only to chat.
- **Multichat** (dashboard **and** popout) - the flagged platform keeps its tab and shows a red **warning triangle** in place of the live counts, with a short tooltip naming the platform. This is distinct from, and not merged with, the WebSocket `connectionLost` state.

Both markers are deliberately icon-only: they *mark* a platform as degraded, while the wording and the repair action live in the connection notices. Hiding a notice never removes a marker.

### Connection notices

Every reconnect, permission and setup notice of the web app lives in **one container**, the *connection notices* (an `AlertDeck` from `@lumio/ui`). It shows **one entry at a time**; with more than one entry a pager **‹ 2 / 5 ›** sits top right next to the **✕**, and the entry's button(s) sit underneath, right-aligned. Title and description are never shortened - long text wraps, and the container's height follows the entry that is shown.

| Entry | Severity | Shown when |
|-------|----------|-----------|
| *Platform* login expired | red | the acting user's personal login grant is flagged (`loginReconnectRequired`, or a flagged login connection in the dashboard) |
| *Platform* sign-in needs a new permission | amber | the acting user's known `loginMissingScopes` includes a scope used by an account permission they hold; unknown stored scopes (an empty list) show no entry |
| No login assigned to this channel | amber | none of your login connections is assigned to the active account (dashboard and Chat) |
| Connect a streaming platform | amber | your only login is Discord - one secondary button per streaming platform, none highlighted |
| *Platform* channel disconnected | red | a channel connection is flagged `reconnect_required` |
| *Platform* bot disconnected | red | a bot connection is flagged (dashboard) |
| *Platform* needs new permissions | amber | the connection's `missing_scopes` is non-empty and it is not flagged |

**Order:** your own (user) problems always come first, then the channel's: user red → user amber → channel red → channel amber. Within a group the platforms follow the tab order (Twitch, YouTube, Kick, then others). The first entry is shown first; when an entry is repaired the container stays on the entry that took its place instead of jumping elsewhere.

**Paging:** the **‹ ›** buttons, the **←/→** keys while the container has focus (switches instantly, without animation) and, in popouts on touch screens, a horizontal swipe. Nothing rotates on its own. With reduced motion only a short cross-fade remains.

**Hiding:** every entry can be hidden with **✕** until the page is reloaded (remembered per entry and account for the browser tab). If the cause still exists after a reload, the entry is back.

**Where it appears:**

- **Dashboard and every non-fullscreen page** - a card at the top of the page: flagged login / channel / bot connections, missing scopes of every platform (Spotify included), the login assignment and onboarding. The **Upgrade** banner stays separate.
- **Chat and Events** (dashboard and popout) - directly under the topbar, in the normal layout: chat platforms only. A bottom-stuck chat stays at its newest message while the container appears, grows, switches or disappears; a reader who scrolled up keeps their line.
- **Chat popout with the header hidden** - only what concerns **sending** (an expired login or channel on a platform you can send on) appears compactly **above the input**; with header and input both hidden (a pure browser source) nothing is shown.
- **Music popout** - Spotify only, read-only: a link to Connections in a new tab, never the OAuth start.

The **sign-in needs a new permission** entry belongs to the acting user. It appears in Chat under the header, above the chat input, and in the dashboard shell, with **Sign in with {platform} again**; it never appears in a popout. For Twitch AutoMod, `moderator:manage:automod` is relevant only to viewers with `chat:automod-allow` or `chat:automod-deny`; the entry says they need to sign in with Twitch again to allow or deny AutoMod messages. The other mapped pairs are `moderator:manage:banned_users` → `chat:ban`/`chat:timeout`, `moderator:manage:chat_messages` → `chat:delete`, and `user:write:chat` or `chat:edit` → `chat:write`. An unmapped login scope uses a general explanation. A disconnected login shows its existing **sign-in disconnected** entry instead of a second scope entry.

**Who sees what (unchanged guards, no new API):**

- Channel and bot entries with a repair button need `connections:create` - the permission `authorizeChannel` itself is guarded on, so the button never 403s. In Chat, a member without it (a Moderator) still sees the channel entry for a platform they can **send** on, with a link to Connections instead. In the dashboard such members see channel and bot entries as text only.
- Login entries in Chat need `chat:write` and appear only for platforms you can send on.
- A **delegated popout** (shared token window) shows entries without buttons, and never the login assignment or onboarding - those belong to the viewer's own login, not to the account. All of a popout's requests carry the popout session, never the dashboard cookie.
- A repair button names its platform - **Reconnect Twitch**, **Reconnect bot on Twitch**, **Grant Kick permission** - and shows the platform's logo on a neutral button. It starts the platform's OAuth flow in place; from a popout window it opens in a new tab. When authorize refuses (the platform is not on the plan, an `Account`-source platform has no or undecryptable `app_credentials` - code `CREDENTIAL_DECRYPTION_FAILED` -, a self-hosted install lacks a global OAuth app, or the permission was revoked since the page loaded), an error toast says so; the button never resets silently.

The feature-surface indicators read the popout-token-readable `connectionStatuses` overview, so the state is visible in browser-source popouts without loosening the first-party `flaggedConnections` guard, which only the dashboard reads.

### Automatic detection

The Token Refresh Worker classifies every failed refresh as **terminal** or **transient**:

- **Terminal** - the provider rejected the grant itself: an OAuth2 error of `invalid_grant` / `unauthorized_client`, or HTTP **400 / 401** (a `refresh_token` grant only 400/401s when the refresh token or client authorization is no longer valid). The worker sets `reconnect_required = true` on the affected row (channel / bot / login).
- **Transient** - a retryable failure (provider 5xx, 429 rate-limit, timeout, network error, or an internal encrypt/persist hiccup). The worker leaves the flag untouched and retries on the existing 1-hour backoff.

The worker also treats two conditions the refresh HTTP call never even reaches as terminal - previously both were skipped silently, leaving the dead grant invisible until the first failed send:

- **Undecryptable stored token** - ciphertext that no longer authenticates under the encryption key (a key mismatch / corruption, `aead::Error`), *not* an expired token. It can never be refreshed, so the row is flagged.
- **Expired login grant with no refresh token** - e.g. a Google grant that only returned a refresh token on the first consent. Once its access token has expired it can never be renewed, so a dedicated worker pass flags it.

A token can also be dead while its stored expiry still looks fine - revoked by the user on the platform, or minted by a different OAuth app than the one this environment pins (for example a database copied from another environment). The Token Refresh Worker never renews such a token, because it only refreshes tokens close to their expiry. The **Twitch EventSub** and **Kick subscription** workers therefore handle a provider **HTTP 401** themselves:

1. The first 401 on a (re)connect stops the run before any further call - Twitch subscription creation stops at the first 401 instead of failing once per event type.
2. The worker forces **one** refresh of the channel token through the same single-flight lock and pinned credentials as the Token Refresh Worker. If another flight already renewed the token, the stored token is used without a second refresh.
3. If the refresh is rejected, or the provider answers 401 again with the new token, the row is flagged `reconnect_required` and the worker stops until the channel is reconnected. A refresh that fails for a retryable reason (network, provider 5xx, missing global app credentials) only backs off and never flags the connection.

The Multichat **send path** acquires the sender's login token through the same terminal-aware chokepoint: an undecryptable, already-flagged, or expired-without-refresh grant is flagged `reconnect_required`, fires the same audit + email, and returns a typed `login_reconnect_required` result instead of a raw error string (see [Chat](./chat.md#sending-result-shape-and-reconnect-signalling)).

On the terminal `false → true` transition (and only then, so it fires once) the worker:

- **Emits an audit event** - `account:connection_reconnect_required` (channel/bot, account scope) or `user:login_reconnect_required` (login, user scope), with `platform`, `connection_type` and `reason` in the metadata (`token_refresh_terminal` from the Token Refresh Worker or a login refresh, `provider_rejected_token` from a platform worker after a 401).
- **Sends a reconnect email** (`lo_email` `NoticeKind::ReconnectLogin`, `ReconnectChannel`, or `ReconnectBot`, according to the connection) to the account owner.

The flag is automatically cleared when the user reconnects through any of the standard flows:
- Login callback (re-authentication clears the flag on the login connection)
- Channel OAuth upsert (reconnecting the channel clears the flag)
- Bot OAuth upsert (reconnecting the bot clears the flag)

Admins can also set or clear the flag manually via the admin panel for any connection type. This is useful for forcing a user to re-authorize after a token leak, scope change, or platform-side revocation.

### Google / YouTube: the 7-day "Testing" rule

The most common "my connection keeps expiring every few days" support case is **not** a bug in our refresh path. Channel connections use **per-account BYO Google credentials** (the customer's own Google Cloud OAuth client), so Google-side settings decide token lifetime. If the customer's OAuth consent screen is **External** with publishing status **"Testing"**, Google issues **refresh tokens that expire after 7 days** (the exception is name/email/profile-only scopes; we request `youtube.readonly` + `youtube.force-ssl`, so the rule always applies). When that refresh token dies, our worker classifies it as terminal `invalid_grant`, flags `reconnect_required`, and emails the owner.

**Fix (customer-side):** set the OAuth client to **"In production"** (verification may be required for `youtube.force-ssl`), then **reconnect once**. Before debugging the refresh path for a Google/YouTube complaint, check the OAuth client's **publishing status** first.

### Admin API

| Method | Path | Description |
|--------|------|-------------|
| `PUT` | `/v1/admin/channel-connections/{id}/reconnect-flag` | Set/clear reconnect flag on a channel connection |
| `PUT` | `/v1/admin/bot-connections/{id}/reconnect-flag` | Set/clear reconnect flag on a bot connection |
| `PUT` | `/v1/admin/login-connections/{id}/reconnect-flag` | Set/clear reconnect flag on a login connection |

Request body: `{ "reconnect_required": true }` or `{ "reconnect_required": false }`.

## Unified OAuth callback (one shared redirect URI)

Lumio routes the three non-login OAuth flows through **one shared** web-host
redirect URI per platform by design — fewer registrations, one callback path, one
handle format. This is a deliberate choice, not a provider constraint: Kick
accepts up to 10 redirect URIs per OAuth app (verified in the Kick developer
dashboard, 2026-09-23; Kick's public documentation does not state the limit). The
three non-login flows — channel connection, account bot, and admin global bot —
therefore share **one** web-host redirect URI per platform instead of each
registering their own `.../callback`:

```
{web.public_url}/api/connections/oauth/{platform}/callback
```

Which flow a callback belongs to is **not** in the URL. It lives in a
server-side **state handle** minted at the `authorize` step:
`OAuthStateHandle { kind ∈ {channel, bot, global_bot, integration}, account_id, platform, return_to, actor_user_id, shop_host }`,
stored in Redis under an unguessable single-use nonce with a 10-minute TTL. The
nonce is what travels through the provider as the `state` parameter.

The browser callback (Next.js) forwards `code` + `state` to the unified exchange
`POST /v1/connections/oauth/{platform}/exchange`, which:

1. **Redeems** the handle (single-use: deleted on read).
2. **Binds a channel / account-bot handle to the initiator session** (see below)
   before anything is written.
3. **Validates `return_to`** fail-closed against the `[web.public_url, admin.public_url]`
   allowlist by comparing URL **origin** (scheme + host + port) - a free
   `return_to` would be an open redirect.
4. **Dispatches on `kind`** into the shared channel / account-bot / global-bot
   completion logic (the same functions the legacy per-flow exchanges call), and
5. Returns the absolute, marker-appended redirect URL (`data.redirect_url`) for
   the browser to follow (`?connected=` for channel/bot, `?bot_connected=` for the
   admin global bot).

For account-facing channel flows, the API mints the short link `/dashboard/settings/channel/connections/{platform}` as the handle's `return_to` (GraphQL and REST share one helper), never an address with `#settings/…`, because an OAuth return drops the fragment. The exchange refuses a `return_to` that carries a fragment. Account bot flows return to the same platform area with `kind=bot`, so the area handles the bot result independently of the channel result. Discord returns to the Discord area. Existing returns that name the former Connections hub reach the same area through its 308 redirect. The group root routes `connected`, `reconnect` and `platform` query strings to the matching area while preserving their query parameters; the window shows the result toast. The former dashboard bot and credentials paths redirect to the group root.

**Initiator-session binding (channel and account bot).** Starting a connect is
session-only: the `authorize` step accepts only an interactive sign-in session
(not an `lm_usr_` API key) and records that user as the handle's
`actor_user_id`. The exchange then completes a `channel` / `bot` handle only when
the caller presents the **same user's** session - the web callback forwards the
browser's session bearer - and that user still has access to the handle's
account plus `connections:create` / `bot-connections:create`. No session, another
user's session, an API key, or a handle without a recorded actor is refused
(`401` / `403`) before the PKCE verifier is consumed or any connection row is
written; the single-use handle is spent either way.

**Admin global bot is exempt.** The global bot starts in the admin app, returns
through the web host, and `return_to` sends the browser back into the admin
providers UI. The browser session on the web host is never an admin session, so
a `global_bot` handle completes without one. That stays safe because only the
admin-only authorize step (platform-operator `bot-connections:create`) can mint
such a handle.

**Fail-safe / prod-gated.** The unified flow only activates for a `system`-sourced
connect, which requires global OAuth keys. Without them (local, dev, staging,
operator-managed installs) every connect degrades to `account` and keeps using the **legacy
per-flow exchanges** (`POST /v1/connections/channel/{platform}/exchange`,
`POST /v1/bot-connections/{platform}/exchange`), which remain as aliases for
account/BYO setups. Their state keys (`oauth:state:` / `lumio:bot_oauth_state:`)
store the same structured handle as the unified flow, including the initiating
user, and the alias exchanges run the same initiator-session binding
(`check_exchange_binding`: same user's interactive session, account access,
`connections:create` / `bot-connections:create`) before PKCE and the token
exchange (ZAF-1922). A state written before that binding existed carries no
initiator and is refused as expired - the connect is restarted. The browser
returns through the web app's callback route, which calls the session-bound
exchange; the API's server-side `GET /v1/connections/channel/{platform}/callback`
completes nothing and only redirects to
`{web}/dashboard/settings/channel/connections/{platform}?error=…&platform=…`, which redirects to the platform's area in the settings window, so the user restarts the connect there.

### Reconnecting with a different account

A channel reconnect must come back with the platform account that is already
connected. When the platform reports a different account, the exchange changes
nothing and refuses with `WRONG_PLATFORM_ACCOUNT` (`409`); to switch the channel,
disconnect first. The refusal names the account the user was signed in with —
its login, else its display name, never a token or platform ID — so the
dashboard toast can name both the account that was used and the one that is
needed:

- **Legacy exchange** (`POST /v1/connections/channel/{platform}/exchange`):
  `409` with `details.signed_in_as`. The web callback route copies it onto the
  dashboard URL.
- **Unified exchange** (`POST /v1/connections/oauth/{platform}/exchange`): `200`
  with a `redirect_url` that carries
  `error=…&code=WRONG_PLATFORM_ACCOUNT&platform=…&signed_in_as=…`, so the browser
  lands on the handle's `return_to` like any other outcome.
- **GraphQL** has no exchange; the shared error mapper exposes the same value as
  the `signedInAs` extension.

`signed_in_as` is missing when the platform did not report a name.

### When the provider rejects the token exchange

If the provider answers the code→token exchange with a **4xx** (an expired or
replayed `code` → `invalid_grant`, a wrong `client_secret` → `invalid_client`, or
a `redirect_uri` / PKCE mismatch — RFC 6749 §5.2), the exchange fails with a
dedicated, client-facing error instead of a scrubbed `INTERNAL_SERVER_ERROR`
(ZAF-1506):

- **HTTP `422`, code `TOKEN_EXCHANGE_FAILED`**, message
  `"<Provider> rejected the token exchange: <oauth_error>"` (e.g.
  `Kick rejected the token exchange: invalid_grant`). The message names **only**
  the provider's OAuth error code — never a token, the `client_secret`, or the raw
  upstream body. Same code and message on GraphQL and REST.
- The API logs one structured line (`platform`, `token_url`, `redirect_uri`, an
  8-char `client_id` prefix, HTTP status, and the parsed `error` /
  `error_description`) so an operator can tell an unregistered `redirect_uri` from
  a wrong secret without a body dump.
- A provider **5xx** or a transport failure is a transient upstream fault, not a
  client-actionable rejection, and stays a scrubbed `500 INTERNAL_SERVER_ERROR`.

For **Kick**, the most common cause is a missing redirect URI: when no dedicated
Kick **Channel** app is configured, a Kick channel connect falls back to the
**login** app's keys (`kick_client_id` / `kick_client_secret`, ZAF-1493), so that
login app must also register the unified channel callback
(`{web.public_url}/api/connections/oauth/kick/callback`) in one of its ten
redirect-URI slots — otherwise Kick rejects the exchange with `invalid_grant` /
`redirect_uri` mismatch (see the redirect-URI tables in
[OAuth setup](../getting-started/oauth-setup.md)).

## Credential modes

The backend exposes the effective platform policy through `platformCredentialModes` and `GET /v1/connections/credential-modes`. The dashboard reads this surface instead of hardcoding which platforms need a customer OAuth app.

| Platform | Channel mode | Dashboard effect |
|----------|--------------|------------------|
| Twitch | `system` by default | Connect can use Lumio's global app when keys are configured; otherwise it falls back to account credentials. |
| Kick | `system` by default | Connect can use Lumio's global app when keys are configured; otherwise it falls back to account credentials. |
| YouTube | `account` | The account supplies its own Google Cloud OAuth app. |
| Spotify | `account` | The account supplies its own Spotify app. |

Each mode row includes `systemConfigured`. `mode: "system"` with `system_configured: false` means the installation is configured to use Lumio-managed credentials, but the required dedicated global keys for that `(platform, kind)` pair are not present, so new connects may degrade to the account-credential path. The fallback is intentional: a local or operator-managed install with no global keys behaves like the historical BYO flow.

`systemConfigured` is kind-specific. Channel rows report the channel app pair (Twitch may count its login-key fallback); Bot rows report only the dedicated bot app pair. A bot connect can still run through the channel fallback when bot keys are missing, but the Bot row remains `systemConfigured: false` so the dashboard does not claim a dedicated bot app exists.

Each platform tab contains an **App** section. YouTube and Spotify require an account-owned app; Twitch and Kick normally use Lumio's system app, with an account-app fallback when the required global keys are absent. A saved account credential can still be managed on its platform tab. The own-app guides show five steps for Spotify and six for YouTube; Twitch and Kick fallback setup uses three steps. The guides read callback and required/optional scope values from `channelOAuthScopes`, rather than a separate frontend scope list.

A credential with `decryptable: false` appears as needing attention in the Overview and its platform's App section. Its stored client ID cannot be read under the current `token_encryption_key`; the owner must re-enter the credentials through the guide. The affected account-pinned connection cannot authorize or refresh with that credential.

When operators change `[platform_credentials]`, existing channel connections are not rewritten. The row's `credential_source` remains pinned because a refresh token minted by OAuth app A cannot be refreshed with OAuth app B. Users reconnect when they want a connection to move to the newly selected source.

## Kick: undocumented kick.com endpoints

Kick's official API (`api.kick.com/public/v1`) has no emote list, no badge
artwork, no follower count, no level badge, no chat-room id and no stream schedule. For those, Lumio reads
**undocumented** kick.com website endpoints. None of them receives a token (an
OAuth token never goes to an undocumented host), all use a 5-second timeout, and
all are **fail-open**: a Cloudflare challenge, a timeout or a format change only
removes that one piece of data — chat, events, role badges and history never
depend on them.

| Endpoint | Used for | Cached | Degrades to |
|----------|----------|--------|-------------|
| `https://kick.com/emotes/{slug}` | Emote menu: channel set, Kick `Global`, Kick `Emojis` ([Emotes](./emotes.md#kick-native-sets)) | emote-set cache (6 h) + `chat_emotes` catalog | last catalog state |
| `https://kick.com/api/v2/channels/{slug}` → `subscriber_badges` | Sub-badge images per month tier ([Chat badges → Kick](./chat.md#kick)) | Redis, 6 h per channel | built-in sub icon |
| `https://kick.com/api/v2/channels/{slug}/users/{user_slug}` → `badges_v2` | The chatter's selected global badges: level, founder … | Redis, 4 h per user | no global badge |
| `https://kick.com/api/v2/channels/{slug}` → `followers_count` | Follower count in the user card ([ProfileService](./profile-service.md)) | ProfileService profile cache | no follower count |
| `https://web.kick.com/api/v1/channels/{channel_id}/calendar/events?from_utc=&to_utc=` → `data.events[]` | The channel's stream plan — the "Schedule" tab on kick.com ([Channel Status → Stream plan](./channel-status.md#stream-plan)). `channel_id` is the kick.com channel id from `kick.com/api/v2/channels/{slug}` → `id` | Redis, 10 min per channel (failure: 2 min) | empty plan for that channel |
| `https://kick.com/api/v2/channels/{slug}` → `chatroom.id` | Chat room on Kick's Pusher chat socket, for deletes and unbans made on kick.com ([Kick Chat-Moderation Listener](../developer-guide/kick-chat-listener.md)) | Redis, 7 d per channel | channel skipped; kick.com deletes/unbans not picked up |

The channel `slug` comes from `channel_connections.channel_login` (the Kick slug;
set on connect, back-filled from the chat webhook's `broadcaster.channel_slug`
when missing).

The chat-moderation listener also reads Kick's unofficial **Pusher chat
WebSocket** (not a kick.com HTTP endpoint): it is the only source for messages
deleted and users unbanned on kick.com. It is best effort in the same sense —
see [Chat → Kick: which kick.com action arrives how](./chat.md#kick-which-kickcom-action-arrives-how).

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/connections.rs`) -- Queries for listing credentials, channel connections, and connection status. Mutations for saving/deleting credentials, initiating OAuth authorization, and disconnecting channels.
- **REST** (`apps/api/src/routes/connections.rs`) -- REST endpoints for credential CRUD, channel connection listing, OAuth authorization initiation, OAuth callback handling, and code exchange. REST routes provide the full OAuth flow with redirect handling.
- **Crypto** (`apps/api/src/crypto.rs`) -- AES-256 encryption/decryption for client_id, client_secret, access_token, and refresh_token. Key derived from `config.auth.token_encryption_key`.
- **Platforms** (`apps/api/src/platforms.rs`) -- Platform registry with OAuth configuration (authorize URL, token URL, scopes, extra params) per platform. `SUPPORTED_PLATFORMS` constant and `is_valid_platform()` validation.

#### Twitch IRC-tags listener (connected channels only)

Two Twitch chat-metadata signals are exposed **only over IRC** and are absent
from EventSub, so a dedicated worker
(`apps/api/src/workers/twitch_irc_tags.rs`) supplements the EventSub worker for
**connected** channels:

- **First-time chatter** - the `first-msg=1` tag on a chat `PRIVMSG`. Emitted as
  a `twitch:first_message` event.
- **Watch streak** - a `USERNOTICE` with `msg-id=viewermilestone`,
  `msg-param-category=watch-streak`, `msg-param-value=<count>`. Emitted as a
  `twitch:watch_streak` event carrying `streak_count`, the viewer's `badges`
  (chat-message `ChatBadge` shape, always present, `[]` when none), name `color`
  and - best effort - `avatar_url` (see the
  [payload](./events.md#twitch-watch-streak-payload)).

The worker opens a **single anonymous (`justinfan`) read-only** IRC connection —
no per-channel OAuth token, no credential surface - and JOINs only the channels
that have an active Twitch `channel_connections` row (join on connect, part on
removal via a 60s roster reload). The JOIN and the tag-router lookup key on
`channel_connections.channel_login` (the lowercase Twitch login), **not** on
`channel_name` (the display name). Twitch display names can be localized
(`こさむん`), and `JOIN #こさむん` is never honoured — so a display-name JOIN left
the bot silently absent from localized channels while EventSub kept them looking
healthy. Consumers fall back to `channel_name` only for legacy rows the boot
backfill has not yet filled. It is **scoped to connected channels only** and
is entirely separate from the global-scope
[Public Stats Crawler](../developer-guide/public-stats-crawler.md), which it does
not touch. Both signals flow through the normal `lo-events` insert + broadcast
pipeline, so they appear on the same GraphQL / REST / WebSocket surfaces as every
other `twitch:*` event (see [Events](./events.md#event-types)). This is a
deliberately reversible IRC dependency: if Twitch later exposes these via
EventSub, the source is swapped and the listener dropped.

The listener never resolves badge images or profiles on its own. Badge
`image_url`s come from the per-account badge cache that each Twitch EventSub
worker builds (`HelixClient::build_badge_cache`) and publishes into shared state;
until that worker has built one, images stay `null`. The avatar comes from the
ProfileService cache (Redis, then `platform_users`) without credentials, so it
never calls Helix from here, and it is bounded by a short timeout. Both fail
open and never hold back or drop an event.

### Frontend

- Connection settings page with cards per platform showing connection status.
- App credential form for entering client_id/client_secret.
- "Connect" button initiates OAuth flow, redirects to platform, callback saves tokens.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `appCredentials` | `connections:read` | List app credentials for the account. Secrets are masked; only last 4 chars of client_id shown as `clientIdHint`. Each row also carries a non-null `decryptable` flag - `false` when the stored `client_id` can no longer be decrypted under the current `token_encryption_key` (a broken row that must be re-entered), so the UI can distinguish "broken" from a legitimate `****` hint. |
| `channelConnections` | `connections:read` | List channel connections for the account. Tokens are never exposed. Shows platform, channel ID, `channelName` (display name, may be localized), `channelLogin` (the URL-safe login/handle — use this to build a profile URL), scopes, expiry, and `reconnectRequired`. |
| `connectionStatuses` | `connections:read` | Connection status overview for all supported platforms. Fields: `hasCredentials`, `isConnected` (health-aware - `false` when the connection is flagged `reconnectRequired`), `reconnectRequired`, `channelName`, `expiresAt`, `enabled`. Readable with a popout token that carries `connections:read`. |
| `platformCredentialModes` | `connections:read` | Credential mode per `(platform, kind)` - the backend truth the frontend reads instead of hardcoding which platforms Lumio operates globally. One `PlatformCredentialMode` per `(platform, kind)` that has an OAuth mode: `platform`, `kind` (`CHANNEL` \| `BOT`), `mode` (`SYSTEM` \| `ACCOUNT`), and `systemConfigured`. `systemConfigured` is **not** derivable from `mode` - it says whether global keys are actually configured, distinguishing "Lumio manages this" from "should, but is not set up". |
| `enabledProviders(connectionType)` | Public (no auth) | List enabled provider slugs for a given connection type (`login`, `channel`, or `bot`) |
| `enabledPlatforms` | Public (no auth) | List platform slugs enabled for channel connections |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `saveAppCredentials(input: SaveCredentialsInput)` | `connections:create` | Save (upsert) app credentials for a platform. Encrypts client_id and client_secret before storage. |
| `deleteAppCredentials(platform)` | `connections:delete` | Delete app credentials, **source-aware** cascade. An `account`-pinned connection depends on the credentials (its token refresh reads `app_credentials`), so it is torn down together with them - leaving it alive would lock the customer out of an unrefreshable connection. A `system`-pinned connection uses the global Lumio app and does **not** depend on the account credentials, so it **survives**: only the (stray) credentials are removed. Runs in one transaction so the connection and its credentials never diverge. When the connection is torn down, its platform worker stops, exactly as for `disconnectChannel`; the platform's chatter data stays. Use `disconnectChannel` to drop only the connection and keep the credentials. |
| `authorizeChannel(platform)` | `connections:create` | Start OAuth authorization flow. Generates a state parameter (stored in Redis with 10-min TTL), builds the authorization URL with scopes, and returns the redirect URL. For an `account`/BYO platform whose stored `app_credentials` can no longer be decrypted, it refuses with the stable code `CREDENTIAL_DECRYPTION_FAILED` and an actionable message (re-enter the credentials) - identical message and code on the REST twin. |
| `disconnectChannel(platform)` | `connections:delete` | Disconnect a channel connection (keeps app credentials). Stops the platform worker on every API replica; the platform's chatter data stays (see [What a disconnect stops and deletes](#what-a-disconnect-stops-and-deletes)). If it is the channel's name/picture source, the channel switches to its own details |

### REST Endpoints

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/connections/credentials` | `connections:read` | List all app credentials |
| `PUT` | `/v1/connections/credentials/{platform}` | `connections:create` | Save app credentials |
| `DELETE` | `/v1/connections/credentials/{platform}` | `connections:delete` | Delete app credentials (source-aware, twin of `deleteAppCredentials`). Stops the platform worker only when an `account`-pinned connection is actually disconnected (the chatter data stays); a surviving `system`-pinned connection keeps running. |
| `GET` | `/v1/connections/channel` | `connections:read` | List all channel connections |
| `GET` | `/v1/connections/status` | `connections:read` | Per-platform connection status overview (REST counterpart of `connectionStatuses`; health-aware `is_connected` + `reconnect_required` + `expires_at`) |
| `GET` | `/v1/connections/credential-modes` | `connections:read` | Credential mode per `(platform, kind)` (REST twin of `platformCredentialModes`). Each item: `platform`, `kind` (`"channel"` \| `"bot"`), `mode` (`"system"` \| `"account"`), `system_configured`. Same `connections:read` + `feature:connections` guard as the GraphQL query. |
| `DELETE` | `/v1/connections/channel/{platform}` | `connections:delete` | Disconnect a channel (twin of `disconnectChannel`, same worker stop; the chatter data stays). If it is the channel's name/picture source, the channel switches to its own details |
| `GET` | `/v1/connections/channel/{platform}/authorize` | `connections:create` | Initiate OAuth flow (redirect URL). A **system**-sourced connect mints a structured state handle and targets the unified callback; an **account**/BYO connect keeps the legacy per-flow callback. Refuses with `422` and code `CREDENTIAL_DECRYPTION_FAILED` when the account's stored `app_credentials` can no longer be decrypted (twin of `authorizeChannel`). |
| `GET` | `/v1/connections/channel/{platform}/callback` | -- | Retired server-side callback: completes nothing, redirects the browser to the platform's Connections tab with an error so the user can restart the connect |
| `POST` | `/v1/connections/channel/{platform}/exchange` | Session of the initiating user + `connections:create` | Exchange OAuth code for tokens (legacy per-flow, account/BYO alias). Bound to the initiator's interactive session like the unified exchange, checked before PKCE and the token exchange (ZAF-1922) |
| `POST` | `/v1/connections/oauth/{platform}/exchange` | -- | **Unified** OAuth code exchange behind the single web-host callback. Redeems the structured state handle, validates `return_to` fail-closed against `[web, admin]`, dispatches on `kind` (`channel` / `bot` / `global_bot`) into the shared completion logic, and returns the absolute browser redirect URL (`data.redirect_url`). `channel` / `bot` handles complete only for the session of the user who ran the authorize step (re-checking account access + `connections:create` / `bot-connections:create`; `401` without a session, `403` otherwise, before anything is written); `global_bot` handles need no session. Answers `422` / `TOKEN_EXCHANGE_FAILED` when the provider rejects the exchange (`invalid_grant`, `invalid_client`, `redirect_uri`/PKCE mismatch), naming the provider's OAuth error code; a provider 5xx stays a scrubbed `500`. |
| `GET` / `PUT` / `DELETE` / `POST` | `/v1/connections/shopify`, `/shopify/link/inspect`, `/shopify/link/confirm`, `/shopify/settings`, `/shopify/events/{event_id}/hide-name` | `connections:*`; the hide needs `events:edit` | The Shopify store connection; see [Shopify](./shopify.md#api) |

## Permissions

| Permission | Description |
|-----------|-------------|
| `connections:read` | View credentials (masked) and channel connections. Enforced on `appCredentials`, `channelConnections`, `connectionStatuses`, and the matching REST reads. |
| `connections:create` | Save app credentials, initiate OAuth flows. Enforced on `saveAppCredentials`, `authorizeChannel`, and the matching REST writes. |
| `connections:edit` | Gates the connection-settings controls in the dashboard (`<Gate permission="connections:edit">`) and the Shopify settings (`updateShopifySettings`, `PUT /v1/connections/shopify/settings`). Channel credential writes go through `connections:create` and removals through `connections:delete`. |
| `connections:delete` | Delete credentials, disconnect channels. Enforced on `deleteAppCredentials`, `disconnectChannel`, and the matching REST deletes. |

## Feature Gating

The channel-connections management surface is gated on the `feature:connections`
flag, in addition to the `connections:*` permissions. Every credential/channel
query and mutation (`appCredentials`, `channelConnections`, `connectionStatuses`,
`saveAppCredentials`, `deleteAppCredentials`, `authorizeChannel`,
`disconnectChannel` on GraphQL; the `/v1/connections/credentials`,
`/v1/connections/channel`, `/v1/channel-info` reads/writes, the `authorize` step
and the authenticated OAuth `exchange` on REST) enforces it on both protocols —
GraphQL via `FeatureGuard::new("feature:connections")` chained before the
permission guard, REST via `require_feature(..., "feature:connections", ...)`.
With the flag disabled the API rejects the call directly (`Feature
'feature:connections' is not available`, HTTP `403`); the webapp route gate is
UX only. The public `enabledProviders` / `enabledPlatforms` queries (used by
unauthenticated pricing pages) and the deprecated unauthenticated OAuth redirect
callback are intentionally **not** feature-gated. Per-platform availability is
additionally gated by the `platform:{platform}:channel` sub-flags on the
credential-save and authorize steps.

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `app_credentials` | PostgreSQL | id, account_id, platform, client_id (encrypted), client_secret (encrypted), created_at, updated_at. Unique on (account_id, platform). |
| `channel_connections` | PostgreSQL | id, account_id, platform, platform_channel_id, channel_name, channel_avatar_url (platform profile picture, CSP-allowed hosts only), access_token (encrypted), refresh_token (encrypted), scopes (text array), credential_source (`account`/`system`), reconnect_required (bool, default false), expires_at, created_at, updated_at. Unique on (account_id, platform). |

## Data Flow

### OAuth Connection Flow

1. User clicks **Connect**, or first saves app credentials when the platform's current channel mode is `account`.
2. `authorizeChannel(platform)` resolves the source for `(platform, channel)`.
3. For `system`, the API reads the global Lumio OAuth app from config and mints a structured state handle for the unified callback. For `account`, it decrypts the account's `app_credentials` and mints the legacy account state.
4. Server builds the OAuth authorization URL with the platform's authorize endpoint, scopes, redirect URI, and state.
5. Client redirects to the platform's authorization page.
6. User authorizes on the platform. The web callback receives `code` and `state`.
7. The callback exchange validates/redeems state, exchanges the code for tokens with the same OAuth app source, and fetches channel details.
8. Access token, refresh token, granted scopes, channel details, and `credential_source` are encrypted/stored in `channel_connections`.
9. Platform workers start or continue for the connected platform.

### Security

- **Encryption at rest**: All client_id, client_secret, access_token, and refresh_token values are encrypted using AES-256 with a key derived from `config.auth.token_encryption_key`. This key is **mandatory** on any non-`development` deployment: the API **refuses to boot** in `staging`/`production` when it is empty, a shipped placeholder (`CHANGE_ME` / `change-me-in-production`), or shorter than 16 characters - there is no silent fallback to a constant key (an empty value would derive the public constant `SHA-256("")`, readable by anyone with this repository). See [Mandatory auth secrets](../getting-started/installation.md#mandatory-auth-secrets).
- **CSRF protection**: OAuth state is stored in Redis with 10-minute TTL; unified system flows use single-use structured state handles.
- **Secret masking**: Client secrets and tokens are never exposed in API responses. Only a 4-character hint of the client_id is shown.
- **Spotify localhost workaround**: For development, Spotify requires `127.0.0.1` instead of `localhost` in redirect URIs.
- **Spotify Development Mode allowlist**: A BYO Spotify app that Spotify has not approved stays in Development Mode and can only be authorized by accounts the customer allows manually. The credentials setup wizard tells the customer to open **User Management** in their Spotify app and add the email address of the account they will connect; without it, Spotify still completes the token exchange but answers the first API call (`GET /v1/me`) with `403` "User not registered in the Developer Dashboard". The code exchange treats that answer as a refusal: it saves **no** connection and writes no audit event, and returns `FORBIDDEN` with a message containing "not registered", for which the dashboard names the User Management step (step 3) of the setup guide. Other failures of that profile lookup (network, `5xx`) do not block a Spotify connect; the connection is saved without a profile name.
- **Audit trail**: adding a channel connection emits an `account:connection_added` audit event whose metadata records the `credential_source` (`"system"`/`"account"`) - so the log shows which OAuth app minted the token. Never a secret. Identical on both protocols (the add path is REST-side; the GraphQL disconnect twin emits `account:connection_removed`).

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/connections.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/connections.rs` | REST endpoints including OAuth callback/exchange |
| `apps/api/src/crypto.rs` | AES-256 encryption/decryption utilities |
| `apps/api/src/platforms.rs` | Platform OAuth configuration registry |
| `apps/api/src/db/connections.rs` | Database operations for credentials and connections |

---

## Features / OBS Integration

Source: https://docs.lumio.vision/features/obs

# OBS Integration

## Overview

Lumio integrates with OBS Studio for remote control (scenes, stream/recording start-stop, status monitoring). Three distinct paths exist, and they do **not** share a transport:

| Path | Who connects to obs-websocket | State |
|------|-------------------------------|-------|
| `/dashboard/obs` and `/popout/obs` | the API server's per-account OBS worker (ZAF-1122); the pages call the `/api/obs-remote/*` proxy routes, which resolve the GraphQL `obsRemoteStatus` query + `obs*` mutations (never REST directly) | Re-enabled: renders the connection badge, scene grid and stream/recording toggles, all gated on `available` - falls back to an honest "coming soon" state when no worker is publishing a snapshot. A command to a disconnected worker returns `409 Conflict` "OBS remote control is not connected". The worker transport is wired in ZAF-1122 |
| Overlay pages (`/overlay/[key]`) | the **browser**, from inside OBS, using `ObsWebSocketClient` from `@lumio/obs` | Working. Credentials arrive in the WebSocket bootstrap payload; `obs:action` events pushed by automations are executed locally |
| `testObsConnection` / `POST /v1/integrations/obs/test` | the **API server**, using `lo_obs_remote::ObsRemoteClient` | Working, but only a connect-and-disconnect probe with a 10-second timeout |

| Piece | Flag | What it is |
|-------|------|------------|
| OBS Remote feature umbrella | `feature:obs_remote` | Gates every OBS query, mutation and REST route, plus the pages `/dashboard/obs` and `/popout/obs`. This is the master switch for the whole feature. |
| WebSocket transport | `integration:obs_websocket` | The stored obs-websocket connection details (port + password + optional remote host). Configured by the streamer in the **Services** area of the settings window's Connections group (`/dashboard/settings/channel/connections/services`). Also gates whether overlay bootstrap payloads carry OBS credentials. |
| Browser Source overlay capability | `widget:obs_browser_source` | Reserved flag for overlay widgets that would consume the `window.obsstudio` JS API through `useObsBrowserSource()`. Seeded and toggleable, but no code path reads it today. Classified under `widget:*` because it is an overlay-side capability. |

Gating semantics per flag:

- **`feature:obs_remote` off** → `/dashboard/obs` (via `FeatureRouteGate` on its `layout.tsx`) and `/popout/obs` (via an SSR feature check) render `<FeatureDisabledPage>`, and every OBS query, mutation and REST route rejects the request.
- **`integration:obs_websocket` off** → write endpoints for the WebSocket integration (`PUT /v1/integrations/obs`, `DELETE /v1/integrations/obs`, GraphQL `saveObsConfig`, `deleteObsConfig`) reject the request, and overlay bootstrap payloads omit the `obs` credentials block. Read endpoints still return existing config for visibility. The user can't add/save/delete the WebSocket connection in the Services area.
- **`widget:obs_browser_source` off** → no observable effect. No widget renderer, settings panel or editor-picker entry consumes this flag, and `ObsBrowserSourceProvider` mounts unconditionally at the overlay root (it gates internally on `window.obsstudio` availability). A future overlay widget that reacts to OBS state should check `useFeature("widget:obs_browser_source")` itself.

Admins toggle all three flags on `/admin/feature-flags`. Per-plan or per-account overrides work the same as any other feature flag - see the [admin feature-flags doc](../admin/feature-flags.md).

## The stored obs-websocket connection

`integration:obs_websocket` covers the connection details Lumio stores for an account. Lumio does not hold a long-lived socket to OBS on the server; it stores the credentials and hands them to whichever surface needs them.

- **Requires:** the user installs OBS, enables the built-in obs-websocket server (Tools → obs-websocket Settings), notes the port and optional password.
- **User configuration:** **Settings → Connections → Services** → **OBS** → **Set up** (or **Edit**). Fields: `port` (default 4455), `password` (optional), `remote_enabled` toggle, `remote_host` (only when remote_enabled is true).
- **Password encryption:** AES-256-GCM via `crypto::encrypt_versioned()` (writes are `v2.`-tagged; see [OAuth credentials architecture](../developer-guide/oauth-credentials-architecture.md#encryption)) with a key derived from `auth.token_encryption_key`. Stored in the JSONB config column of `integration_configs`.
- **Save semantics:** `PUT /v1/integrations/obs` / `saveObsConfig` writes the whole config object as an upsert. Submitting an empty or omitted `password` **clears** the stored password rather than leaving the previous one in place.
- **Remote-host validation:** `remote_host` must be a public IP address or a dotted DNS name. Both OBS write surfaces (`PUT /v1/integrations/obs`, `saveObsConfig`) refuse with the same `400` message: an IP literal in loopback, private, link-local, CGNAT, multicast, reserved or documentation space (IPv4 and IPv6, including ULA `fc00::/7`, `fe80::/10` and IPv4-mapped/NAT64 forms) (`OBS host must not be a private, loopback or link-local address`); `localhost` or a name ending in `.localhost`, `.local`, `.internal`, `.lan`, `.home.arpa`, `.intranet` or `.corp` (`OBS host must not be a local/internal address`); anything else that is not a dotted hostname, such as a single-label name, a numeric IPv4 shorthand (`127.1`, `2130706433`) or a value carrying `/`, `:`, `@`, `?` or `#` (`OBS host must be a public IP address or DNS name`); and `remote_enabled: true` without a host (`OBS host is required when remote control is enabled`). This is an SSRF guard. The generic `updateIntegration` refuses any OBS `config` write with `BAD_REQUEST` (`The OBS config can only be changed in the OBS settings`), so these surfaces are the only write path.
- **Connect-time check:** the OBS Remote worker and both test-connection surfaces check the stored host again before connecting, so a row written before the guard existed is skipped, not followed. They resolve the name, refuse it if **any** resolved address is non-public (`OBS host resolves to a private, loopback or link-local address`), and connect to the checked IP rather than the name, so a DNS answer that changes between check and connect cannot redirect the socket. The worker resolves again on every reconnect.
- **Transport:** TCP WebSocket to `ws://{resolved-ip}:{port}`. There is no `localhost` default: a remote-enabled row without a host is skipped by the worker, and a test connection without a host fails with `OBS host is required when remote control is enabled`. Remote mode requires a publicly reachable host (and port-forwarding in the user's router).

## Browser Source overlay capability

`widget:obs_browser_source` is the reserved flag for overlay widgets that integrate with the `window.obsstudio` JS API. OBS injects this API into any page loaded as a Browser Source inside OBS. The provider and hook described below exist and are mounted; no widget consumes them yet, and nothing reads the flag.

### ObsBrowserSourceProvider

The `ObsBrowserSourceProvider` is mounted unconditionally at the overlay root (`OverlayClient` for the live overlay, `OverlayPreview` for editor preview). It:

1. Detects `window.obsstudio` presence at mount time (SSR-safe: no-op on the server).
2. Fetches initial state in parallel: plugin version, control level, stream/recording/replay-buffer/virtualcam status, current scene, scene list, transition list, current transition.
3. Subscribes to every event in the `OBSEventType` union except `obsReplaybufferSaved` (which needs no state change) - scene and scene-list changes, transition and transition-list changes, the four streaming and six recording transitions, the four replay-buffer transitions, virtualcam start/stop, source visibility/active changes, and `obsExit` (which resets the provider to a disconnected state).
4. Runs status polling every 2 000 ms as a drift-correction backup.
5. Cleans up all listeners and polling on unmount.

When OBS is not detected, the Provider supplies no-op defaults - all methods are safe to call unconditionally.

### useObsBrowserSource()

Consumer widgets import `useObsBrowserSource` from `@/contexts/obs-browser-source-context` to read live OBS state:

```ts
import { useObsBrowserSource } from "@/contexts/obs-browser-source-context";

function MyWidget() {
  const { available, currentScene, status, setScene } = useObsBrowserSource();
  // ...
}
```

Available fields:

| Field | Type | Description |
|-------|------|-------------|
| `available` | `boolean` | True when `window.obsstudio` was detected |
| `pluginVersion` | `string \| null` | obs-browser plugin version |
| `controlLevel` | `OBSControlLevel` | Current control permissions (NONE/READ_OBS/READ_USER/BASIC/ADVANCED/ALL) |
| `status` | `OBSStatus \| null` | `streaming` / `recording` / `recordingPaused` / `replayBuffer` / `virtualcam` booleans |
| `currentScene` | `string \| null` | Active scene name |
| `currentSceneInfo` | `OBSScene \| null` | Active scene object including canvas `width` and `height` (useful when canvas dimensions are needed) |
| `scenes` | `string[]` | All scene names |
| `transitions` | `string[]` | All available transition names |
| `currentTransition` | `string \| null` | Active transition name |
| `canRead()` | `() => boolean` | controlLevel >= READ_OBS (1) |
| `canReadUser()` | `() => boolean` | controlLevel >= READ_USER (2) |
| `canControl()` | `() => boolean` | controlLevel >= BASIC (3) |
| `canModify()` | `() => boolean` | controlLevel >= ADVANCED (4) |
| `canFullControl()` | `() => boolean` | controlLevel == ALL (5) |

Control methods (`setScene`, `setTransition`, `startStreaming`, `stopStreaming`, `startRecording`, `stopRecording`, `pauseRecording`, `unpauseRecording`, `startReplayBuffer`, `stopReplayBuffer`, `saveReplayBuffer`, `startVirtualcam`, `stopVirtualcam`) are no-ops when OBS is not available. Capability helpers `canReadUser()` and `canControl()` are also available (see table above).

### Outbound event relay (not implemented)

Forwarding OBS Browser Source events *from* the overlay *to* the Lumio backend is not implemented. The call site is marked with a TODO in `apps/web/src/contexts/obs-browser-source-context.tsx`, and a matching TODO block in `apps/web/src/hooks/use-obs-websocket.ts` sketches the intended shape. The reverse direction - backend → overlay → OBS - does work; see below.

## Overlay control relay

This is the OBS control path that actually reaches OBS today, and it runs entirely through the overlay:

1. The account has an OBS integration config and at least one overlay layer of type `obs_browser_source` (or `obs`).
2. When that overlay's WebSocket session starts, `OverlayBootstrapProvider` (`apps/api/src/services/bootstrap_provider.rs`) decrypts the stored password and adds an `obs` block (`port`, `password`, `remote_enabled`, `remote_host`) to the bootstrap payload - but **only** when `integration:obs_websocket` is enabled for the account **and** the overlay is authenticated with a permanent token. Shared overlay tokens never receive credentials; a shared link may instead carry them explicitly as URL params.
3. `useObsLocalConnect` (`apps/web/src/hooks/use-obs-local-connect.ts`) opens an obs-websocket v5 connection from the browser to the local OBS instance using those credentials, and reconnects automatically if OBS restarts.
4. An automation's OBS-control action publishes to the Redis channel `lumio:obs:action:{account_id}` (`apps/api/src/dispatch.rs`), which reaches the overlay as an `obs:action` WebSocket event.
5. `handleObsRelayAction` (`apps/web/src/hooks/use-obs-websocket.ts`) dispatches it to the local client. Supported actions: `set_current_scene`, `set_current_transition`, `set_muted`, `set_volume`, `set_filter_enabled`, `start_stream`, `stop_stream`, `start_recording`, `stop_recording`. An unknown action is logged and ignored.

### Key files

| Path | Description |
|------|-------------|
| `apps/web/src/contexts/obs-browser-source-context.tsx` | Provider + context + `useObsBrowserSource` hook |
| `apps/web/src/app/(overlay)/overlay/[key]/overlay-client.tsx` | Mounts `ObsBrowserSourceProvider`, calls `useObsLocalConnect`, routes `obs:action` events |
| `apps/web/src/components/overlay/overlay-preview.tsx` | Mounts `ObsBrowserSourceProvider` for the editor preview |
| `apps/web/src/hooks/use-obs-local-connect.ts` | Browser-side obs-websocket connection from bootstrap credentials |
| `shared/obs/src/client.ts` | `ObsBrowserSource` class (typed `window.obsstudio` wrapper) |
| `shared/obs/src/types.ts` | `OBSStatus`, `OBSScene`, `OBSTransition`, `OBSEventType`, `OBSControlLevel` |

There is no `ObsBrowserSourceWidget` renderer and no `ObsBrowserSourceSettings` panel - the overlay editor has no picker entry for this capability, so an `obs_browser_source` layer cannot currently be created from the editor UI even though the bootstrap provider recognises the layer type.

## Admin configuration

### Toggle transports globally

`/admin/feature-flags` - flip any of:
- `feature:obs_remote` - kills the entire OBS remote feature for all accounts
- `integration:obs_websocket` - kills the stored WebSocket connection globally (users can't add or edit the OBS integration, and overlays stop receiving credentials)
- `widget:obs_browser_source` - reserved; toggling it has no runtime effect today

### Per-plan / per-account overrides

- Plan overrides: use the plan's feature-settings in `/admin/plans/{slug}` to disable any of the three flags for specific tiers.
- Account overrides: use `/admin/accounts/{id}/features` to set a per-account override.

See the [admin feature-flags doc](../admin/feature-flags.md) for the resolution chain.

## User configuration

### Dashboard UI

- **`/dashboard/obs`** - the OBS Remote page. Gated on `feature:obs_remote` via `FeatureRouteGate` on its `layout.tsx`. Renders a connection badge, a scene grid, and stream/recording toggle buttons, all driven by `GET /api/obs-remote/status` and `POST /api/obs-remote/{scene,stream,recording}`. It contains **no** port/password form - connection details are edited in the **Services** area of the settings window's Connections group (`/dashboard/settings/channel/connections/services`).
- **`/popout/obs`** - compact version of the same page, designed to be opened as a docked browser window next to OBS (e.g. via OBS's "Custom Browser Docks" or a standalone browser window). Same `feature:obs_remote` gate, same REST routes, polling status every 5 s. NOT designed to be loaded as a Browser Source inside OBS.
- **Settings → Connections → Services** (`/dashboard/settings/channel/connections/services`) - the OBS section with **Test**, **Edit** and **Remove**. The edit dialog is where the user configures port / password / remote toggle / remote host; it needs `obs:edit` and the plan feature.

Both pages render the interactive control UI - connection badge, scene grid and stream/recording toggles, all driven by `GET /api/obs-remote/status` (a Next.js proxy route that resolves the GraphQL `obsRemoteStatus` query) - whenever the status reports `available: true`, and the dashboard additionally shows the live `ingest` stats (bitrate, FPS, dropped/total frames). The UI gates every "live" element on `available`, so it degrades gracefully: when no OBS worker is publishing a snapshot for the account (`available: false`), both pages fall back to an honest "remote control coming soon" state, and a control click on a disconnected worker returns `409 Conflict` ("OBS remote control is not connected") rather than a fake success. The scene/stream/recording controls are additionally disabled while `connected` is false. The server-side worker transport that publishes those live snapshots and executes the commands is wired in ZAF-1122.

When `/popout/obs` is opened with a popout token (`?token=lm_pop_…`), the token is exchanged once for a short-lived popout **session** cookie (see [Tokens](../user-guide/tokens.md)). The page then gates on `accountFeatures` instead of `me`, and the popout-aware fetch tags requests so the proxy forwards the session cookie and self-heals a lapsed session. The session resolves to the same popout-token authorization context, so retrieving the decrypted OBS WebSocket password (`GET /v1/integrations/obs/credentials`, popout-token-only) keeps working - a dashboard login still cannot read it. Saved OBS-dock URLs carrying the old `?token=` continue to work unchanged.

Both pages fail **open** on an unreachable API during the SSR feature check: when the feature query throws, the page renders rather than showing the disabled screen.

### What the user sees when a flag is off

- `feature:obs_remote` off → both `/dashboard/obs` and `/popout/obs` show the generic `FeatureDisabledPage` with reason (`global_off` / `plan_locked` / `account_override`).
- `integration:obs_websocket` off → "OBS WebSocket" entry disappears from the Integrations Add modal; attempts to save/delete config via direct API call return `Feature 'integration:obs_websocket' is not available`. Existing saved config is still readable. Overlay bootstrap payloads stop carrying OBS credentials.
- `widget:obs_browser_source` off → no user-facing impact today (no overlay widget currently uses the `window.obsstudio` API). Reserved for future overlay-widget features that integrate with the Browser Source JS API.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/obs.rs`) - queries for config, status, remote connection status; mutations for save/delete config, test connection, and stream/recording/scene control. Write-mutations are gated by three guards chained via `FeatureGuard::new("feature:obs_remote").and(FeatureGuard::new("integration:obs_websocket")).and(PermissionGuard::new("obs:edit"))` so BOTH feature flags AND the permission must be satisfied.
- **REST** (`apps/api/src/routes/obs_integration.rs`) - mirrors the GraphQL mutations with identical guard order: `require_permission("obs:edit")` → `require_feature("feature:obs_remote")` → `require_feature("integration:obs_websocket")`. Same error messages and codes as the GraphQL side per the parity rule.

> **Note:** the server-side remote-control transport is live (ZAF-1122) and never fabricates state. The `obsRemoteStatus` query and `GET /v1/obs-remote/status` read the worker's live Redis snapshot - `available: true` with the real reading when a worker is publishing for the account, else `available: false`. The control mutations (`obsControlStream`, `obsControlRecording`, `obsSwitchScene`) and their `/v1/obs-remote/*` REST twins dispatch to the worker and only report success once it confirms execution against OBS; a missing/disconnected worker returns a `409 Conflict` "OBS remote control is not connected" (`CONFLICT`) on **both** protocols. Invalid input returns a `400` with an identical message on both surfaces (`scene_name is required`; `Invalid action: expected "start" or "stop"`).
- **OBS Remote Client** (`crates/lo-obs-remote/`) - `ObsRemoteClient` handles WebSocket connections to OBS Studio, including authentication with the encrypted password. Used by both the OBS Remote worker (live status + control) and the connection test.
- **OBS Remote worker** (`apps/api/src/workers/obs_remote.rs`) - a per-account worker that holds the OBS connection, polls ingest stats via `IngestMonitor` and emits events on threshold violations (low bitrate, high dropped frames, connection lost, recovery) with exponential-backoff reconnect. It also publishes a live `ObsRemoteStatus` snapshot to Redis (`lumio:obs:status:{account_id}`, TTL ≈ 3× poll interval) each cycle and subscribes to `lumio:obs:command:{account_id}` to execute scene/stream/recording controls, replying per-request so the handlers can confirm execution. Spawned and kept in sync by the reconcile loop (`apps/api/src/workers/obs_reconcile.rs`) for every `remote_enabled` OBS config.
- **Configuration storage** - OBS config is stored as JSONB in the `integration_configs` table with platform = `"obs"`, label = `"OBS WebSocket"`, unique on `(account_id, platform)`. The password field is encrypted using AES-256-GCM.

### Frontend

- **`/dashboard/obs`** - Scene grid plus stream/recording toggles and a connection badge, driven by the `/api/obs-remote/*` proxy routes. No port/password form.
- **`/popout/obs`** - Compact dock version of `/dashboard/obs` using the same `/api/obs-remote/*` routes through a popout-aware fetch, polling every 5 s. Designed to be opened as a docked browser window alongside OBS. NOT loaded as a Browser Source and does NOT use `window.obsstudio`.
- **Settings → Connections → Services** - the OBS section and its edit dialog hold the port / password / remote-toggle / remote-host form.
- **`/overlay/[key]`** - the only surface that actually drives OBS, via a browser-side obs-websocket connection (see [Overlay control relay](#overlay-control-relay)).

`apps/web/src/hooks/use-obs-websocket.ts` exports a `useObsWebSocket` hook that fetches credentials via the popout-token endpoints and manages a client lifecycle. No component calls it - only its `handleObsRelayAction` export is in use.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `obsConfig` | `obs:read` | Full OBS config: port, remote_enabled, remote_host, has_password flag, timestamps. Never exposes the actual password. |
| `obsStatus` | `obs:read` | Lightweight status: configured flag, port, remote settings. |
| `obsRemoteStatus` | `obs:read` + `feature:obs_remote` | Live remote connection status from the OBS worker's Redis snapshot: `available` (a worker is publishing), `connected`, stream/recording status, scene list, current scene, and `ingest` stats. Returns `available: false` with empty fields when no worker is running. |

### GraphQL Mutations

| Mutation | Guards | Description |
|----------|--------|-------------|
| `saveObsConfig(port?, password?, remoteEnabled?, remoteHost?)` | `feature:obs_remote` + `integration:obs_websocket` + `obs:edit` | Save (upsert) OBS config. Port defaults to 4455. Password is encrypted before storage. |
| `deleteObsConfig` | `feature:obs_remote` + `integration:obs_websocket` + `obs:delete` | Delete OBS integration config. |
| `testObsConnection` | `feature:obs_remote` + `obs:edit` | Test the obs-websocket connection from the API server. Requires `remote_enabled` - otherwise it errors with `Connection test is only available when remote mode is enabled`. 10-second timeout; connection failures come back as `{ success: false, error }` rather than a GraphQL error. |
| `obsControlStream(action)` | `feature:obs_remote` + `obs:edit` | Control streaming: `"start"` or `"stop"`. Dispatched to the OBS worker; returns `true` only once execution is confirmed, `400` on an invalid action, or `409 CONFLICT` "OBS remote control is not connected" when no live worker acknowledges. |
| `obsControlRecording(action)` | `feature:obs_remote` + `obs:edit` | Control recording: `"start"` or `"stop"`. Same dispatch/confirmation/error semantics as `obsControlStream`. |
| `obsSwitchScene(sceneName)` | `feature:obs_remote` + `obs:edit` | Switch the active OBS scene. Empty `sceneName` returns `400` "scene_name is required"; otherwise dispatched to the worker with the same confirmation/`409` semantics. |

### REST Endpoints

| Method | Path | Guards | Description |
|--------|------|--------|-------------|
| `GET` | `/v1/integrations/obs` | `obs:read` + `feature:obs_remote` | Get OBS config (`has_password` flag only, never the password). |
| `PUT` | `/v1/integrations/obs` | `obs:edit` + `feature:obs_remote` + `integration:obs_websocket` | Save OBS config (upsert). |
| `DELETE` | `/v1/integrations/obs` | `obs:delete` + `feature:obs_remote` + `integration:obs_websocket` | Delete OBS config. Returns `204`. |
| `GET` | `/v1/integrations/obs/credentials` | **popout-token auth only** + `feature:obs_remote` | Get decrypted OBS credentials. Carries **no** permission check - instead it rejects any auth context that is not a Popout Token with `403 This endpoint requires popout token authentication`, so a normal dashboard login can never read the password. |
| `GET` | `/v1/integrations/obs/status` | `obs:read` + `feature:obs_remote` | Get OBS configuration status (`configured`, port, remote settings). |
| `POST` | `/v1/integrations/obs/test` | `obs:edit` + `feature:obs_remote` | Test the obs-websocket connection from the API server. |
| `GET` | `/v1/obs-remote/status` | `obs:read` + `feature:obs_remote` | Live remote connection status from the worker's Redis snapshot: `available`, `connected`, `stream`, `recording`, `scenes`, `current_scene`, `ingest`. Returns `available: false` with `connected: false` and empty scenes when no worker is running. |
| `POST` | `/v1/obs-remote/scene` | `obs:edit` + `feature:obs_remote` | Switch scene. Body `{ "scene_name": "..." }`. Empty name → `400` "scene_name is required". Dispatched to the worker; `200 { "ok": true }` once confirmed, else `409 Conflict` "OBS remote control is not connected". |
| `POST` | `/v1/obs-remote/stream` | `obs:edit` + `feature:obs_remote` | Start/stop streaming. Body `{ "action": "start" \| "stop" }`. Invalid action → `400` "Invalid action: expected \"start\" or \"stop\"". Dispatched to the worker; `200 { "ok": true }` once confirmed, else `409 Conflict` "OBS remote control is not connected". |
| `POST` | `/v1/obs-remote/recording` | `obs:edit` + `feature:obs_remote` | Start/stop recording. Body `{ "action": "start" \| "stop" }`. Same validation/confirmation/`409` semantics as `/v1/obs-remote/stream`. |

REST payloads are snake_case (`remote_enabled`, `remote_host`, `has_password`, `scene_name`, `current_scene`, `created_at`).

Read endpoints are intentionally NOT gated on `integration:obs_websocket` - existing configurations remain visible in the UI even when the transport flag is switched off for an account. Only WRITE paths (create/update/delete) are blocked so admins can disable new adoption without breaking existing users' views.

All four `/v1/obs-remote/*` handlers enforce the plan feature `feature:obs_remote` (`require_feature`, fail-closed) - the same guard the GraphQL surface applies via `FeatureGuard` - before doing anything else. There is no separate `require_pro` helper (a former no-op placeholder was removed); the feature flag **is** the plan gate. See [Plan gating](#plan-gating) below.

## Permissions

| Permission | Description |
|-----------|-------------|
| `obs:read` | Read OBS configuration and status |
| `obs:edit` | Edit OBS configuration, test connection, control stream/recording/scenes |
| `obs:delete` | Delete OBS configuration |

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `integration_configs` | PostgreSQL | id, account_id, platform (`"obs"`), label (`"OBS WebSocket"`), enabled, config (JSONB), created_at, updated_at. Unique on (account_id, platform). |

### Config JSONB Structure

```json
{
  "port": 4455,
  "password": "encrypted_string_or_null",
  "remote_enabled": false,
  "remote_host": "192.168.1.100"
}
```

- `port` - OBS WebSocket port (default 4455)
- `password` - Encrypted OBS WebSocket password (null if not set)
- `remote_enabled` - Whether remote (non-localhost) connections are enabled
- `remote_host` - Remote host address (only used when remote_enabled is true)

## Data Flow

1. User configures OBS settings (port, optional password, optional remote host) in **Settings → Connections → Services** → OBS.
2. `remote_host` is validated (see **Remote-host validation** above), the password is encrypted via `crypto::encrypt_versioned()`, and the whole object is upserted into the `integration_configs` JSONB config.
3. User can test the connection: the API server resolves `remote_host` and refuses a non-public answer (returning `success: false` with the reason, without decrypting the password), then decrypts the password and attempts an obs-websocket handshake to `ws://{resolved-ip}:{port}` with a 10-second timeout, then disconnects.
4. Stream/recording/scene commands from `/dashboard/obs` or `/popout/obs` reach `/v1/obs-remote/*`, which - after the `obs:edit` + `feature:obs_remote` gates - publishes the command to the account's OBS worker over Redis (`lumio:obs:command:{account_id}`) and waits for a per-request reply. The worker executes it against the live OBS connection and confirms; the handler returns success only on confirmation, or `409 Conflict` "OBS remote control is not connected" when no live worker acknowledges within the timeout. The worker is spawned per `remote_enabled` config by the reconcile loop.
5. For overlays, the credentials travel in the WebSocket bootstrap payload and the browser connects to OBS directly; automation-issued `obs:action` events are executed there. See [Overlay control relay](#overlay-control-relay).

### Overlay-widget Browser Source integration

Overlay widgets under `/overlay/[key]` can consume `useObsBrowserSource()` to react to OBS state (e.g. auto-hide when a specific scene is active). The `ObsBrowserSourceProvider` is already mounted at the overlay root - no additional setup is needed. To gate a widget's OBS-reactive behaviour on the feature flag, check `useFeature("widget:obs_browser_source")` inside the widget component.

### Plan gating

OBS is a paid-tier feature, and the gating lives entirely in the `plan_features` matrix: `feature:obs_remote`, `integration:obs_websocket` and `widget:obs_browser_source` are all seeded **disabled for the Free plan and enabled for Pro**. Free and Pro are the only plans. Because the flags gate every OBS query, mutation and route, a Free account cannot use OBS at all - the restriction is not limited to `remote_enabled: true`.

There is no separate plan-limit column. The historical `account_limits.obs_remote_allowed` boolean was migrated into the `feature:obs_remote` account override and dropped. Enforcement is the `feature:obs_remote` guard itself - `require_feature` on every `/v1/obs-remote/*` route and `FeatureGuard` on every GraphQL field, both fail-closed. (A former no-op `require_pro` placeholder in `apps/api/src/routes/obs_remote.rs` was removed in ZAF-1090; it protected nothing.)

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/obs.rs` | GraphQL queries and mutations with three-guard chain |
| `apps/api/src/routes/obs_integration.rs` | REST endpoints with identical guard chain |
| `apps/api/src/routes/obs_remote.rs` | Remote control REST routes. Read the worker's live status snapshot and dispatch controls through `services::obs_remote`; `409` "not connected" only when no live worker acknowledges. Each still enforces `feature:obs_remote`. |
| `apps/api/src/services/obs_remote.rs` | Shared REST+GraphQL seam: `read_status_snapshot()` + `send_command()` (Redis request/reply with a bounded timeout) and the shared validation/error constants that keep both protocols parity-clean. |
| `apps/api/src/workers/obs_remote.rs` | Per-account OBS worker: poll+status loop (live Redis snapshot + ingest monitoring/auto-actions) and command loop (executes scene/stream/recording controls, replies per-request). |
| `apps/api/src/workers/obs_reconcile.rs` | Protocol-agnostic reconcile loop: spawns/restarts/stops OBS workers to match `remote_enabled` OBS integration configs; wired into API startup + graceful shutdown. |
| `apps/api/src/services/bootstrap_provider.rs` | Injects the decrypted `obs` credentials block into the overlay WebSocket bootstrap |
| `apps/api/src/dispatch.rs` | Automation OBS action → Redis `lumio:obs:action:{account_id}` |
| `crates/lo-obs-remote/` | Server-side `ObsRemoteClient`, `IngestMonitor`, `ObsRemoteStatus` |
| `crates/lo-obs/` | Rust type definitions mirroring the Browser Source API. Currently has no dependents; the browser-side implementation lives in `@lumio/obs`. |
| `shared/obs/src/client.ts` | Typed wrapper around `window.obsstudio` |
| `shared/obs/src/ws-client.ts` | `ObsWebSocketClient` - typed obs-websocket v5 client, used by the overlay |
| `shared/obs/src/types.ts` | `OBSStatus`, `OBSScene`, `OBSTransition`, `OBSEventType`, `OBSControlLevel` |
| `apps/web/src/hooks/use-obs-local-connect.ts` | Browser-side obs-websocket connection for overlays |
| `apps/web/src/hooks/use-obs-websocket.ts` | `handleObsRelayAction` relay dispatcher (plus an unused `useObsWebSocket` hook) |
| `apps/api/src/crypto.rs` | AES-256-GCM password encryption/decryption |
| `apps/web/src/contexts/obs-browser-source-context.tsx` | `ObsBrowserSourceProvider` + `useObsBrowserSource` hook |
| `apps/web/src/app/(overlay)/overlay/[key]/overlay-client.tsx` | Mounts `ObsBrowserSourceProvider`, connects to local OBS, routes `obs:action` |
| `apps/web/src/components/overlay/overlay-preview.tsx` | Mounts `ObsBrowserSourceProvider` for the editor preview |
| `apps/web/src/app/(main)/(app)/dashboard/obs/layout.tsx` | `FeatureRouteGate feature="feature:obs_remote"` on the whole segment |
| `apps/web/src/app/(main)/(app)/dashboard/obs/obs-dashboard.tsx` | OBS Remote page (scene grid + stream/recording controls) |
| `apps/web/src/app/(popout)/popout/obs/page.tsx` | Compact OBS Remote popout (SSR-gated on `feature:obs_remote`, popout-session aware). NOT a Browser Source. |
| `apps/web/src/components/settings/sections/connections/services-tab.tsx` | Services area: OBS section and its port / password / remote-host dialog, StreamElements tokens |

---

## Features / Copyright Manager

Source: https://docs.lumio.vision/features/copyright

# Copyright Manager

## Overview

Copyright Manager lets streamers check a song's current status on demand, manage account safe and blocked lists, and import tracks from Spotify playlists. Community reports and recommendations create candidates for platform-operator review. A vote or report never adds a song to a global list automatically. The account-facing module is gated by the `feature:copyright_detection` feature flag. Background copyright checking is inactive because its worker is not started.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/copyright.rs`) -- Queries for safe songs, blocked songs, playlist syncs, song status checks, and vote candidates. Mutations for adding/deleting safe/blocked songs, importing playlists, managing playlist syncs, casting votes, and admin approval/dismissal of vote candidates.
- **Database** (`apps/api/src/db/copyright.rs`) -- PostgreSQL operations for safe/blocked song lists, playlist sync records, song status checks (checks by spotify_track_id, ISRC, or title/artist fuzzy match), vote casting, and vote candidate aggregation.

### Song Identification

Each list query matches a supplied Spotify Track ID, ISRC, or case-insensitive title and artist combination. The lookup checks the safe list first, then the blocked list, then pending reports; the first matching list determines the status.

### Frontend

- Copyright Manager dashboard with safe/blocked song lists.
- Song status checker with on-demand lookup.
- Spotify playlist import wizard.
- Community voting interface.
- Admin review panel for vote candidates.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `safeSongs` | `copyright:read` | List all safe songs for the account (includes global entries) |
| `blockedSongs` | `copyright:read` | List all blocked songs for the account (includes global entries) |
| `playlistSyncs` | `copyright:read` | List playlist sync records for the account |
| `checkSong(spotifyTrackId?, isrc?, title?, artist?)` | `copyright:read` | Check copyright status of a song. Returns `SongStatusResult` (`SAFE`/`BLOCKED`/`REPORTED`/`UNKNOWN`). |
| `voteCandidates` | `copyright:read` | List tracks with at least one pending community report; tallies count pending reports only. |
| `adminReports(status?, reportType?, limit?, offset?)` | `copyright:read` - **admin scope** (`AdminPermissionGuard`) | Paginated list of **all-status** reports from the account-less global `copyright_reports` table (ZAF-734) |
| `curatedPlaylistTracks(playlistId: UUID!)` | `copyright:read` | Tracks for a curated playlist with song info |
| `publicSafeSongs(search?, limit?, offset?)` | Feature gate only | Public: paginated global safe songs |
| `publicBlockedSongs(search?, limit?, offset?)` | Feature gate only | Public: paginated global blocked songs |
| `publicReports(limit?, offset?)` | Feature gate only | Public: pending copyright reports |
| `publicSystemPlaylists` | Feature gate only | Public: system-curated playlists |
| `publicSystemPlaylist(id: UUID!)` | Feature gate only | Public: one system-curated playlist; `null` when unknown |
| `publicSong(id: UUID!)` | Feature gate only | Public: one global safe or blocked song (same fields as `GET /v1/songs/{id}`); `null` when unknown or not global |
| `publicSongSitemap(after?: UUID, first?: Int)` | Feature gate only | Public: global song ids for the sitemap, `{ items { id lastmod } hasMore }`, keyset-paged on `id` (pass the last `id` as `after`), page size default and maximum 5000. `lastmod` is the song's `created_at` or `null`. Which lists are included (safe and blocked today) is a server constant, not an argument |
| `publicSongStatus(spotifyTrackId?, isrc?, title?, artist?)` | Feature gate only | Public: global copyright status for a song |

### Public marketing surface gates

The unauthenticated `/music` section on the marketing site (`apps/web/src/app/(marketing)/music/*`) is gated by two admin-scope kill-switch flags independent of the account-level `feature:copyright_detection`:

| Flag | Gates |
|------|-------|
| `system:copyright_public_directory` | The entire `/music` surface - landing page, song/playlist browsers, detail pages, reports, and the nav links in header + footer. When off, every page under `/music/*` returns 404 and the nav links disappear. |
| `system:copyright_public_quick_check` | Only the inline paste-a-URL quick-check widget on `/music`. The rest of the directory stays live when this is off. |

Both flags resolve globally (no account context) via the GraphQL `publicFeatureEnabled(key)` resolver, called from `apps/web/src/lib/public-feature.ts` through `serverGqlSSR` and read server-side by the marketing layout at `apps/web/src/app/(marketing)/layout.tsx`. The matching REST endpoint `GET /v1/features/enabled?key=...` stays available for external SDK consumers (CLIs, bots, scripts) - frontend code routes through GraphQL to keep the "Frontend → Next.js proxy → GraphQL" pattern consistent. Admins toggle them in the [feature flags admin page](../admin/feature-flags.md); changes propagate within ~5 minutes (in-memory cache in `FeatureService`).

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `addSafeSong(input: AddSafeSongInput)` | `copyright:edit` | Add a song to the account's safe list |
| `deleteSafeSong(id: UUID)` | `copyright:delete` | Delete a safe song (own account's only) |
| `addBlockedSong(input: AddBlockedSongInput)` | `copyright:edit` | Add a song to the account's blocked list |
| `deleteBlockedSong(id: UUID)` | `copyright:delete` | Delete a blocked song (own account's only) |
| `importPlaylist(spotifyPlaylistId)` | `copyright:edit` | Import tracks from a Spotify playlist as safe songs. Creates a playlist sync record. |
| `deletePlaylistSync(id: UUID)` | `copyright:delete` | Delete a playlist sync and its associated safe songs |
| `createCopyrightReport(input)` | `copyright:report` | Report a song as copyright-blocked |
| `createSafeRecommendation(input)` | `copyright:recommend` | Recommend a song as safe |
| `confirmCopyrightReport(reportId: UUID!, input: ConfirmReportInput!)` | `copyright:vote` | Cast a confirmation vote on an existing copyright report |
| `approveReport(id: UUID!, addToPlaylistId?: UUID)` | `copyright:moderate` | Approve a report: `copyright` reports add to the global blocked list, `recommendation` reports add to the global safe list. Optionally add to a curated playlist. |
| `dismissReport(id: UUID!)` | `copyright:moderate` | Dismiss a report without action |
| `previewPlaylist(spotifyPlaylistId)` | `copyright:edit` | Preview a Spotify playlist's tracks with copyright status (10-minute Redis cache) |
| `importSelectedSongs(input: ImportSelectedSongsInput!)` | `copyright:edit` | Import selected tracks from a previously previewed playlist. Returns `ImportResult`. |
| `createCuratedPlaylist(genre, spotifyPlaylistName)` | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) | Admin: create a system-curated playlist (global `copyright_curated_playlists` table) |
| `updateCuratedPlaylist(id, genre?, spotifyPlaylistName?)` | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) | Admin: update a curated playlist |
| `deleteCuratedPlaylist(id)` | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) | Admin: delete a curated playlist |
| `addToCuratedPlaylist(playlistId, safeSongId)` | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) | Admin: add a safe song to a curated playlist |
| `removeFromCuratedPlaylist(playlistId, safeSongId)` | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) | Admin: remove a safe song from a curated playlist |
| `syncCuratedPlaylist(id)` | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) | Admin: sync a curated playlist with Spotify (returns `SyncResult`) |

### REST Endpoints

All paths live under `/v1/copyright`. Bodies are snake_case.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/copyright/check` | `copyright:read` | Check a song's status by `spotify_track_id`, `isrc`, or `title`+`artist` |
| `GET` | `/v1/copyright/safe-songs` | `copyright:read` | List safe songs (account + globals) |
| `POST` | `/v1/copyright/safe-songs` | `copyright:edit` | Add a safe song |
| `DELETE` | `/v1/copyright/safe-songs/{id}` | `copyright:delete` | Delete an account safe song |
| `GET` | `/v1/copyright/blocked-songs` | `copyright:read` | List blocked songs (account + globals) |
| `POST` | `/v1/copyright/blocked-songs` | `copyright:edit` | Add a blocked song |
| `DELETE` | `/v1/copyright/blocked-songs/{id}` | `copyright:delete` | Delete an account blocked song |
| `POST` | `/v1/copyright/import-playlist` | `copyright:edit` | Import a Spotify playlist as safe songs |
| `GET` | `/v1/copyright/playlist-syncs` | `copyright:read` | List playlist sync records |
| `DELETE` | `/v1/copyright/playlist-syncs/{id}` | `copyright:delete` | Delete a playlist sync (removes imported safe songs) |
| `POST` | `/v1/copyright/vote` | `copyright:vote` | Submit a vote for operator review; does not update a global list |
| `GET` | `/v1/copyright/vote-candidates` | `copyright:read` | List tracks with at least one pending community report; tallies count pending reports only |
| `POST` | `/v1/copyright/vote-candidates/{track_id}/approve` | `copyright:moderate` (admin scope) | Approve the majority verdict into the global blocked or safe list |
| `POST` | `/v1/copyright/vote-candidates/{track_id}/dismiss` | `copyright:moderate` (admin scope) | Dismiss a candidate without changing either global list |

The REST surface covers the account-facing song lists, playlist syncs, and voting. The curated-playlist management and playlist preview/selected-import are GraphQL-only.

### Public REST endpoints

The public directory reads have unauthenticated REST twins. Each runs the same fail-closed `feature:copyright_detection` check as the GraphQL `public*` queries (resolved for the caller's account when one is signed in, otherwise globally) and answers `403 FEATURE_DISABLED` when it is off. Only global rows (`account_id IS NULL`) and system playlists are exposed.

| Method | Path | GraphQL twin | Description |
|--------|------|--------------|-------------|
| `GET` | `/v1/songs` | `publicSafeSongs` / `publicBlockedSongs` | Paginated global songs (`page`, `limit` ≤ 100, `search`, `status`, `source`) |
| `GET` | `/v1/songs/check` | `publicSongStatus` | Global status of one song |
| `GET` | `/v1/songs/sitemap` | `publicSongSitemap` | Global song ids for the sitemap (`after`, `limit` default and maximum 5000) → `{ items: [{ id, lastmod }], has_more }` |
| `GET` | `/v1/songs/{id}` | `publicSong` | One global song; `404` when unknown |
| `GET` | `/v1/playlists` | `publicSystemPlaylists` | System-curated playlists |
| `GET` | `/v1/playlists/{id}` | `publicSystemPlaylist` | One system-curated playlist with its tracks; `404` when unknown |

### Public music pages and sitemap

The marketing directory links to individual `/music/songs/{id}` and `/music/playlists/{id}` pages. Each page reads its one record through `publicSong(id)` or `publicSystemPlaylist(id)` on the server; the page and its metadata share that lookup within the request. An unknown or malformed UUID, or a disabled music feature, gives a real 404. A failed backend read shows a retryable error page instead of treating the record as missing. Song status badges describe the community assessment, and the source label and disclaimer appear in the detail card. Playlist pages show the same disclaimer and link to Spotify.

The public sitemap lists global safe and blocked song detail URLs and system playlists with at least one track. It uses the paged `publicSongSitemap` query and `publicSystemPlaylists`, includes language alternates, and uses the song creation date or playlist update date when available. The music part is cached for one hour and is omitted if its read fails; the curated static routes remain listed. See [SEO Foundation](/developer-guide/seo-foundation#crawler-rules-and-sitemap).

### Input Types

**AddSafeSongInput:**
| Field | Type | Description |
|-------|------|-------------|
| `songName` | `String` | Song title |
| `artist` | `String` | Artist name |
| `spotifyTrackId` | `String?` | Spotify track ID |
| `isrc` | `String?` | International Standard Recording Code |
| `source` | `String` | Source of the safe listing (e.g., "manual", "playlist_import") |
| `sourceRef` | `String?` | Reference to the source (e.g., playlist ID) |

**AddBlockedSongInput:**
| Field | Type | Description |
|-------|------|-------------|
| `songName` | `String` | Song title |
| `artist` | `String` | Artist name |
| `spotifyTrackId` | `String?` | Spotify track ID |
| `isrc` | `String?` | ISRC code |
| `source` | `String` | Source of the blocked listing |

## Permissions

| Permission | Description |
|-----------|-------------|
| `copyright:read` | View safe/blocked song lists and check song status |
| `copyright:edit` | Add safe/blocked songs, import playlists |
| `copyright:delete` | Delete safe/blocked songs, delete playlist syncs |
| `copyright:report` | Submit copyright reports |
| `copyright:recommend` | Submit safe-song recommendations |
| `copyright:vote` | Confirm existing copyright reports |
| `copyright:moderate` | Approve or dismiss submitted reports (`approveReport` / `dismissReport`) |

Every copyright query and mutation is additionally gated on the
`feature:copyright_detection` feature flag. The five `public*` queries carry
**only** that flag and no permission guard - they serve the unauthenticated
`/music` directory.

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `copyright_safe_songs` | PostgreSQL | id, account_id (null for global), song_name, artist, spotify_track_id, isrc, source, source_ref, verified, created_at |
| `copyright_blocked_songs` | PostgreSQL | id, account_id (null for global), song_name, artist, spotify_track_id, isrc, source, auto_learned, created_at |
| `copyright_playlist_syncs` | PostgreSQL | id, account_id, spotify_playlist_id, spotify_playlist_name, auto_sync, last_synced_at, song_count, created_at |
| `copyright_reports` | PostgreSQL | Community copyright reports and safe recommendations awaiting review |

### Song Status Check Logic

The `check_song_status` function checks in order:
1. Is the song in the blocked list (account-specific or global)?
2. Is the song in the safe list (account-specific or global)?
3. If neither, return `Unknown`.

Matching uses spotify_track_id first, then ISRC, then title+artist fuzzy match.

## Data Flow

### Manual Song Management
1. User adds a song to their safe or blocked list via the dashboard.
2. A client can request `checkSong` for the song.
3. The system checks the safe list, blocked list, and pending reports in that order and returns the status.

### Playlist Import
1. User provides a Spotify playlist ID.
2. System fetches playlist tracks from the Spotify API.
3. Tracks are bulk-inserted into `copyright_safe_songs` with source = "playlist_import".
4. A `copyright_playlist_syncs` record is created for tracking.

### Community Voting
1. Users submit reports (`createCopyrightReport`) or safe recommendations (`createSafeRecommendation`) for a song, and can confirm existing reports (`confirmCopyrightReport`).
2. Submissions and confirmations remain moderation candidates; vote counts do not automatically add or remove global entries.
3. Platform operators with the admin-scope `copyright:moderate` permission review candidates and either `approveReport` (a `copyright` report adds to the global blocked list, a `recommendation` report to the global safe list) or `dismissReport`. Approval and dismissal emit system-scope [audit events](./audit-log.md#event-catalog).

### Feature gating

Copyright detection is gated by the `feature:copyright_detection` feature flag,
resolved fail-closed through the account's plan (`plan_features`) with an
optional per-account override. It is not a hard-coded plan constant - an admin
can enable or disable it for a plan or a single account without a deploy.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/copyright.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/copyright.rs` | REST endpoints |
| `apps/api/src/db/copyright.rs` | Database operations for safe/blocked songs, playlists, votes |
| `apps/api/src/workers/copyright.rs` | Copyright checking worker implementation; no current startup caller |

---

## Features / Bot Modules

Source: https://docs.lumio.vision/features/bot-modules

# Bot Modules

## Overview

The Bot Modules system provides configurable chat bot modules for automated moderation and messaging. Each module can be independently enabled/disabled per account, with module-specific configuration and exemption rules. The system currently supports four modules: link protection, spam protection, word filter, and timed messages. Exempt roles (moderators, VIPs, subscribers) can be configured per module to bypass enforcement.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/bot_modules.rs`) -- Queries for listing all module configs and fetching individual modules by name. Mutations for upserting and deleting module configs.
- **Database** (`apps/api/src/db/bot_modules.rs`) -- PostgreSQL operations for the `bot_module_configs` table. Supports list, get, upsert, and delete operations.
- **Validation** -- Module names are validated against a whitelist: `link_protection`, `spam_protection`, `word_filter`, `timed_messages`.

### Frontend

- Bot modules settings page with a card per module.
- Toggle switch for enable/disable.
- Module-specific configuration form.
- Exempt roles selector (checkboxes for mods, VIPs, subs).

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `botModules` | `bot-modules:read` | List all bot module configs for the account |
| `botModule(name)` | `bot-modules:read` | Get a single bot module config by name. Validates name against whitelist. |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `updateBotModule(name, enabled, config?, exemptRoles?)` | `bot-modules:edit` | Upsert a bot module config. Name is validated against the whitelist. Config and exempt_roles default to `{}` if not provided. |
| `deleteBotModule(name)` | `bot-modules:edit` | Delete a bot module config. Name is validated against the whitelist. |

### REST Endpoints

All paths live under `/v1`.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/bot-modules` | `bot-modules:read` | List all module configs for the account |
| `PUT` | `/v1/bot-modules/{module_name}` | `bot-modules:edit` | Upsert a module config (enabled, config, exempt_roles). Module name is validated against the whitelist. |
| `DELETE` | `/v1/bot-modules/{module_name}` | `bot-modules:edit` | Delete a module config |

### Valid Module Names

| Module | Description |
|--------|-------------|
| `link_protection` | Detects and moderates messages containing links |
| `spam_protection` | Detects and moderates spam patterns (repeated messages, excessive caps, etc.) |
| `word_filter` | Filters messages containing blocked words/phrases |
| `timed_messages` | Sends automatic messages at configured intervals |

## Permissions

| Permission | Description |
|-----------|-------------|
| `bot-modules:read` | View bot module configurations |
| `bot-modules:edit` | Create, update, and delete bot module configurations |

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `bot_module_configs` | PostgreSQL | id, account_id, module_name, enabled (bool), config (JSONB), exempt_roles (JSONB), created_at, updated_at |

### Config JSONB Structure (per module)

The `config` field contains module-specific settings. Examples:

**link_protection:**
```json
{
  "action": "delete",
  "warning_message": "Links are not allowed",
  "whitelist_domains": ["youtube.com", "twitch.tv"],
  "timeout_duration": 60
}
```

Whitelist and blacklist entries match a domain itself and its subdomains, on a dot boundary: `youtube.com` covers `youtube.com` and `m.youtube.com`, but not `evilyoutube.com` or `youtube.com.evil.net`. Entries are compared case-insensitively, and a trailing dot is ignored.

**spam_protection:**
```json
{
  "max_repeated_messages": 3,
  "max_caps_percentage": 80,
  "min_message_length_for_caps": 10,
  "action": "timeout",
  "timeout_duration": 30
}
```

**word_filter:**
```json
{
  "blocked_words": ["badword1", "badword2"],
  "blocked_patterns": ["regex_pattern"],
  "action": "delete",
  "warning_message": "Your message was removed"
}
```

**timed_messages:**
```json
{
  "messages": [
    { "text": "Follow us on Twitter!", "interval_minutes": 15 },
    { "text": "Join our Discord!", "interval_minutes": 30 }
  ],
  "min_chat_lines_between": 5
}
```

### Exempt Roles JSONB Structure

```json
{
  "moderators": true,
  "vips": true,
  "subscribers": false
}
```

## Data Flow

1. Account owner/admin enables a bot module and configures it via the dashboard.
2. Configuration is saved via `updateBotModule` mutation (upsert pattern).
3. When a chat message is received, the bot checks each enabled module:
   - Is the user exempt (mod/VIP/sub based on `exempt_roles`)?
   - Does the message violate the module's rules (based on `config`)?
4. If a violation is detected, the configured action (delete, timeout, warn) is executed.
5. Timed messages module sends messages at configured intervals when chat activity meets the minimum threshold.

### Feature gating

The whole Bot Modules surface is gated on the umbrella `feature:bot_modules`
flag: every query and mutation (`botModules`, `botModule`, `updateBotModule`,
`deleteBotModule` on GraphQL; `GET`/`PUT`/`DELETE /v1/bot-modules` on REST)
enforces it on both protocols - GraphQL via
`FeatureGuard::new("feature:bot_modules")` chained before the permission guard,
REST via `require_feature(..., "feature:bot_modules", ...)` after the permission
check. With `feature:bot_modules` disabled the API rejects the call directly
(`Feature 'feature:bot_modules' is not available`, HTTP `403`), so listing
configs is gated too - the webapp route gate is UX only, not the boundary.

In addition, each built-in module has its own finer feature flag, keyed
`bot_module:{module_name}` - `bot_module:link_protection`,
`bot_module:spam_protection`, `bot_module:word_filter`,
`bot_module:timed_messages`. Writing or deleting a module config checks that
per-module flag on both protocols *after* the umbrella `feature:bot_modules`
check, so a specific module disabled for the account's plan cannot be
configured even when the Bot Modules area itself is enabled. Which plans enable
which module flag is a `plan_features` mapping, editable by admins without a
deploy.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/bot_modules.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/bot_modules.rs` | REST endpoints |
| `apps/api/src/db/bot_modules.rs` | Database operations |

## Extension Bot Modules

In addition to the four built-in modules above, accounts can install **extension bot modules** from the Lumio Extension Store. Extension bot modules are community-developed moderation and automation modules that run inside the same V8 isolate sandbox used by all extensions, with the same security guarantees.

### How It Works

Extension bot modules use the `bot_module` category in `lumio.config.json`. When installed, the extension registers one or more **triggers** (commands, keywords, patterns, events, timers, or a moderation hook) that the bots and the Bot Module Worker run against incoming chat messages, stream events and the clock.

```
Chat message arrives at the platform bot (Twitch, Kick, YouTube, Discord)
  → Bot matches it against the account's extension triggers (command, keyword, regex)
  → Command: min_role + cooldown check, then the Bot Module Worker runs the handler
    and the bot posts the reply
  → Keyword / pattern: published to the Bot Module Worker, which runs the handler
    and sends the reply back through the bot
  → Moderation (Twitch, Kick, YouTube): the module's moderate handler decides
    allow / delete / timeout / ban / warn within 500 ms
Stream event (follow, sub, raid, ...) → the Bot Module Worker runs the event handlers
Timer interval elapses              → the Bot Module Worker runs the timer handler
  → Handlers run in the V8 isolate sandbox
  → Any actions a handler returns run after its reply, through the same
    permission checks as widget actions
```

Installing, uninstalling or reconfiguring a bot module - or an admin suspending it - updates the bots' trigger set and the Bot Module Worker's install registry right away; no restart is needed. The same holds for the default system modules installed with a new account. Technical detail: [Bot Modules (developer guide)](../developer-guide/bot-modules.md#bot-module-worker).

### Installation and Configuration

Users install extension bot modules from the Extension Store like any other extension. Once installed, the module appears in **Dashboard > Bot Modules** alongside built-in modules. Each extension bot module supports:

- **Enable/disable toggle** per account
- **Configuration via `config_schema`** fields defined by the extension developer (rendered as a form in the dashboard)
- **Trigger overrides** - account owners can customize command prefixes, keyword lists, and regex patterns without modifying the extension code
- **Exempt roles** - the same moderator/VIP/subscriber exemption system used by built-in modules

### Configuration Validation

Config values set by users (through the dashboard settings panel or API) are validated against the extension's declared schema. Invalid values (wrong type, missing required fields, unknown settings) are rejected with clear error messages. This ensures extensions always receive correctly typed configuration.

### Kill Switch

Account owners can immediately stop all extension bot modules of their account with the **kill switch**. The kill switch:

1. Stops extension triggers for the account instantly (no restart required) - commands, keywords, patterns, moderation, event handlers, timers and any pending actions
2. Is stored per account, so a restarted bot starts with the switch still set, and stays in force when the bot reloads the account's triggers (an install change, a channel the bot joins later, a bot failover)
3. Preserves every install's configuration, so turning it off resumes the modules as they were
4. Also refuses every handler server function (`query()` / `mutation()` / `action()`) of the account's extensions with `403 EXTENSIONS_KILLED`, since those run on the same worker; declarative server functions (`queryRows`, `insertRow`, …) keep working

It is set with `POST /v1/bot-modules/kill` (`{ "account_id", "killed" }`) or the GraphQL mutation `setBotModuleKillSwitch(accountId, killed)`. Both require `bot-modules:edit`, only act on the caller's own account and write the audit event `account:extension_kill_switch_set`. To stop a single module, disable its install instead.

Disabled installs and installs of an extension that Lumio has **suspended** never reach the bots: the trigger feed leaves them out, and the Bot Module Worker drops their handlers on its next sync.

### Trigger Types

Triggers are **declared**, not registered in code: the extension's
`lumio.config.json` carries a `triggers` object whose keys are the trigger
types below. Each entry names the handler the Bot Module Worker dispatches to.

| `triggers` key | Description | Limits |
|----------------|-------------|--------|
| `commands` | Matches a chat command (e.g. `!rank`). Each entry carries `name`, `description`, `cooldown_global`, `cooldown_user`, `min_role`, and optional `discord_options`. | max 20 |
| `keywords` | Matches any of a list of keywords in message text | max 50, min 3 chars each |
| `patterns` | Matches a regex pattern against message text | max 10, max 200 chars each |
| `events` | Fires on a stream event (e.g. `twitch:follower`); the module's `event()` handler runs | - |
| `timers` | Fires on a recurring interval - `name`, `interval` (seconds), `handler`. The older form `timer: true` runs one timer named `timer` at the install's `intervalSeconds` setting (default 300 s, clamped to 60 s - 24 h) | min interval 60 s; shorter entries are ignored |

`min_role` accepts `everyone`, `follower`, `subscriber`, `vip`, `moderator`, or
`broadcaster`. Command triggers are **access-controlled exactly like dynamic
commands**: before a matched command reaches the Bot Module Worker, the bot checks
the sender's role against `min_role` and takes the `cooldown_global` /
`cooldown_user` slots (shared gate `lo_bot_commands::access`; Redis keys
`lumio:cmd_cd:{account_id}:ext:{install_id}:{name}:…`). A sender below `min_role`,
or a command still cooling down, is ignored silently. The worker re-checks
`min_role` before it runs a command handler and refuses a handler whose minimum it
does not know. The effective values are the manifest defaults with the install's
`config.triggers.commands[]` overrides on top. The command fields are snake_case as
documented (`min_role`, `cooldown_global`, `cooldown_user`); the camelCase spelling
of older CLI templates (`minRole`, …) is still read.

### Events

A module that lists event types in `triggers.events` has its `event()` handler
run once for every matching stream event of the account (followers, subs,
raids, donations, …). The handler receives the same event payload widgets
receive. A reply goes to the chat of the platform the event came from
(Twitch, Kick or YouTube); Discord events have no chat channel, so a reply to
them is dropped.

### Viewer input

Viewers interact with an extension only through chat commands (`!vote 2` runs
the module's `command("vote", …)` handler) and channel point rewards on Twitch
and Kick (`twitch:reward` / `kick:reward` run its `event()` handlers). There is
no viewer page and no viewer identity. A handler can store the input with
`ctx.db` and push it with `ctx.realtime.push(topic, payload)` to the
extension's editor panel and overlay layer, which receive it with
`useRealtime(topic, cb)` over the WebSocket channel
`extension_install:{install_id}`. Event handlers run at most 50 times per
install and minute (shared with timers). Details:
[Bot Modules (developer guide)](../developer-guide/bot-modules.md#viewer-input-chat-commands-and-channel-point-rewards).

### Timers

Each declared timer runs once per interval, no matter how many Bot Module
Worker replicas are running. A missed interval (for example during a restart)
is skipped, not caught up. Changing a timer's interval, disabling the install
or setting the kill switch takes effect right away. A timer's reply goes to
the chat of every platform the install runs on, except Discord.

**Only while live.** An install whose configuration sets `onlyWhenLive: true`
(the **Timed Messages** module offers this setting) runs its timer only while
at least one of its chat platforms is live, and posts only on the platforms
that are live.

### Moderation

A module that exports a `moderate` handler and declares `triggers.moderation: true` sees
every chat message of the account on Twitch, Kick and YouTube and returns a
decision:

| Decision | What happens | Permission the module must declare |
|----------|--------------|-----------------------------------|
| `allow` | nothing | - |
| `delete` | the message is deleted | `chat:delete` |
| `timeout` | the sender is timed out for the decision's `duration` (default 600 s) | `chat:timeout` |
| `ban` | the sender is banned | `chat:ban` |
| `warn` | the decision's `message` (or its `reason`) is posted to chat | `chat:send` |

Moderation never slows chat down: each check has 500 ms, and a check that
times out, fails or arrives while the account already has 16 checks running
lets the message through. Messages from the broadcaster and moderators are not
moderated. On **Discord** moderate handlers are not called, because none of
the chat actions supports Discord.

### Actions

Besides a chat reply, a handler can return **actions** - the same actions a
widget can run (for example `chat:timeout`, `obs:set_scene`, `spotify:skip`).
They run after the reply, at most once each (a failed action is not retried),
and pass the same checks as widget actions:

- the module's manifest must declare the action name as a permission;
- the account's plan must include the action's feature (`chat:*` →
  multichat, `obs:*` → OBS remote, `spotify:*` → music);
- the parameters must be valid.

Each install may run at most **120 actions per minute** (operator setting
`[extensions] bot_module_action_rate_per_minute`); actions beyond that are
refused until the next minute. Every outcome - success, refusal, failure,
including moderation decisions - appears in the install's **logs** in the
dashboard, at most one entry per second; an `allow` decision writes nothing.
Log entries carry the action name and, for chat actions, the platform and
target ids - never message text.

Bans, unbans and timeouts a module issues are recorded in the account's
[audit log](./audit-log.md) as `account:extension_moderation` with source
`bot_module`. Message deletions by a module appear only in the install log.

### Permissions

Extension bot modules use the same permission system as other extensions: an action a handler returns runs only when the manifest declares it (see [Actions](#actions)). The `chat:ban` permission requires enhanced review during the extension approval process due to its impact on user experience.

### Feature gating

Extension bot modules are gated by the extension-platform feature flags rather
than by a plan constant. Installing and running them requires the account to
have the extension platform enabled; see [Extensions](/features/extensions).

### Key Files

| Path | Description |
|------|-------------|
| `apps/bot-module-worker/` | Bot Module Worker HTTP service (binary) |
| `crates/lo-bot-module-worker/src/router.rs` | Trigger matching and dispatch logic |
| `crates/lo-bot-module-worker/src/executor.rs` | Handler execution and result handling |
| `crates/lo-bot-module-worker/src/types.rs` | `InstallTriggerConfig`, `CommandTrigger`, `KeywordTrigger`, `PatternTrigger` |
| `crates/lo-extensions-v8/src/executor.rs` | V8 isolate execution for extension handlers |
| `apps/api/src/routes/bot_module_extensions.rs` | Trigger sync, kill switch, and extension log/metric endpoints |

---

## Features / Bot Commands

Source: https://docs.lumio.vision/features/bot-commands

# Bot Commands

## Overview

Cross-platform custom command system. Users create commands in the dashboard, assign them to platforms, and bots execute them with template variable support, cooldowns, and automation triggers.

## Command Types

| Type | Description |
|------|-------------|
| **Text** | Fixed text response, one chat line — the dashboard editor turns typed or pasted line breaks into spaces |
| **Template** | Text with variables: `{user}`, `{user_login}`, `{uptime}`, `{song}`, `{count}`, `{random:a,b,c}` |
| **Automation** | Triggers an automation flow instead of sending text. Runs only where [automation triggers](/features/automations#trigger-path) are enabled, and never for a Twitch Shared Chat partner viewer |

## Platform Assignment

Each command has a `platforms` JSON array. When creating, user selects which platforms the command is active on via checkboxes. Discord commands support both slash commands and prefix commands (configurable per command).

## Permission Levels

Hierarchical - higher includes lower:

```
broadcaster > moderator > vip > subscriber > follower > everyone
```

Each bot maps platform-specific user data to this hierarchy.

## Response Text

A command answers with **one chat line**. `response_text` containing a line break
(CR or LF) is rejected on create, update and override, with the same error on
GraphQL and REST: `response_text must be a single line (no line breaks)` (REST wraps
it as `Validation error: …`, like every bot-command validation error).

Independently of that check, every bot sanitises each outgoing message at its
platform transport (`crates/lo-chat-outbound`): line breaks and other control
characters become spaces, a leading `/` or `.` is removed so the text is never read
as a chat command, and the text is capped at the platform maximum (Twitch and Kick
500, YouTube 200, Discord 2000 characters). On Discord line breaks are kept and no
message can ping `@everyone`, `@here`, users or roles — only a feature post's
configured role is mentionable.

## Cooldowns

Redis-based, per-command:
- **Global**: `lumio:cmd_cd:{account_id}:{command_name}:global` (TTL = cooldown seconds)
- **Per-user**: `lumio:cmd_cd:{account_id}:{command_name}:user:{user_id}` (TTL = cooldown seconds)

**Default:** a new command (account or global) gets a **5 s global cooldown** when
`cooldown_global_secs` is not sent. All tenants share one bot account per platform,
so an unthrottled command lets one chat burn the shared message budget. Set `0`
explicitly to turn the cooldown off. The dashboard editor already defaults to 5 s.

**Built-in commands** of the Twitch, Kick and YouTube bots:

| Command | Reply | Source |
|---------|-------|--------|
| `!song`, `!np` | `Now playing: Artist - Title`, or `No track is currently playing.` | The Spotify track cache (`lumio:spotify:current:{account_id}`) the API's Spotify worker writes while a track plays; behind the `widget:spotify_now_playing` plan feature like `{song}` |
| `!uptime` | `Stream has been live for 2h 5m.`, or `The stream is currently offline.` | The API's channel-status cache for the bot's platform (`lumio:channel_status:{account_id}:{platform}`), the same as `{uptime}` |
| `!commands` | The list above | - |

There is no built-in `!queue` or `!skip`. The built-ins read Redis directly; they call no API field. Every GraphQL document the bots send is validated against the API schema by `apps/api/tests/zaf1913_bot_graphql_documents.rs`.

The built-ins have a per-channel cooldown of 5 s per command, held in the bot's memory. On the
Twitch bot it is configurable (`TWITCH_BOT__BOT__BUILTIN_COOLDOWN_SECS`, `0` turns
it off); see [Installation](../getting-started/installation.md#bot-outbound-throttle).

## Template Variables

Extensible via `VariableResolver` trait in `crates/lo-bot-commands/`:

| Variable | Feature Gate | Description |
|----------|-------------|-------------|
| `{user}` | - | Display name of invoker |
| `{user_login}` | - | Login / @handle of invoker |
| `{channel}` | - | Channel/server name |
| `{platform}` | - | Platform name |
| `{uptime}` | - | Stream uptime on the command's platform, from the channel-status cache (same as `!uptime`) |
| `{song}` | `widget:spotify_now_playing` | Currently playing Spotify track (same as `!song`) |
| `{count}` | - | Command use count |
| `{random:a,b,c}` | - | Random selection from list |

`{user}` is the **display name**; `{user_login}` is the **login / @handle**. On
Twitch the two differ when a chatter has a localized display name (e.g. `{user}` →
`こさむん`, `{user_login}` → `pocom_2026`). On Kick and YouTube the bot chat payload
carries no separate handle, so both resolve to the same value. `{user}` is left
unchanged — templates that already print `{user}` keep printing the display name.

Adding new variables: implement `VariableResolver` trait + register in `VariableRegistry`.

## Global Commands & Overrides

- **Global commands**: `account_id IS NULL`, created by admins, inherited by all accounts
- **Account commands**: `account_id` set, owned by specific account
- **Overrides**: Accounts can override global commands (customize response, platforms, cooldowns) or disable them
- **Shadowing**: Account commands with same name as globals take priority
- **Security**: Overrides cannot make `min_role` less restrictive than global

## Database

- `bot_commands` - command definitions (global + account-scoped)
- `bot_command_overrides` - per-account overrides of global commands
- `bot_command_stats` - usage statistics (Redis live counter, periodic DB flush)

## Shared Crate: `lo-bot-commands`

Used by all four bots:
- `context.rs` - `CommandExecutionContext`, `UserRole`
- `builtins.rs` - data behind the built-in `!song` / `!uptime` and `{song}` / `{uptime}`, and the `!commands` list
- `registry.rs` - `LoadedCommand`, `AccountCommands`, `execute_command`
- `permission.rs` - Role hierarchy + checking
- `access.rs` - the shared access gate (`min_role`, then the atomic cooldown slots) used by dynamic commands **and** extension command triggers
- `cooldown.rs` - Redis cooldown check/set/increment
- `template.rs` - `{variable}` parser with right-to-left replacement
- `variables.rs` - `VariableResolver` trait, `VariableRegistry`, 8 built-in resolvers

## Bot Integration

All four bots (Twitch, YouTube, Kick, Discord):
1. Load commands per account via `botCommandsForAccount(accountId, platform)` system query
2. Store in-memory `CommandStore` (`HashMap<AccountId, AccountCommands>`)
3. On chat message: check dynamic commands → access gate (permission → cooldown) → execute
4. `command_sync` Redis action triggers reload
5. Discord: also registers slash commands per guild (bulk overwrite, 200/day rate limit)

**Twitch message processing.** One IRC connection serves every tenant, so the
Twitch bot never handles chat strictly one message at a time:

- Incoming IRC messages pass through a **bounded ingest queue** (4096). When it
  is full the newest message is dropped and counted in
  `bot_chat_messages_dropped_total{platform="twitch",outcome="ingest_full"}`.
- Each channel gets its own **ordered worker** (queue of 128, same drop-newest
  policy, `outcome="channel_queue_full"`), and at most 32 handlers run at once
  across all channels. A slow channel (worker call, send throttle) no longer
  delays the others; messages within one channel keep their order. An idle
  channel's worker exits after 5 minutes and is re-created on the next message.
- An account whose commands are not loaded yet is loaded lazily on its first
  command. If that load fails it is **not retried for 60 seconds**, so a failing
  API is not hit once per chat line.

## API

| Type | Endpoint | Permission |
|------|----------|------------|
| GraphQL Query | `botCommands: [BotCommand!]!` | `bot-commands:read` |
| GraphQL Query | `botCommand(id: ID!): BotCommand` | `bot-commands:read` |
| GraphQL Mutation | `createBotCommand(input: CreateBotCommandInput!)` | `bot-commands:create` |
| GraphQL Mutation | `updateBotCommand(id: ID!, input: UpdateBotCommandInput!)` | `bot-commands:edit` |
| GraphQL Mutation | `deleteBotCommand(id: ID!)` | `bot-commands:delete` |
| GraphQL Mutation | `overrideGlobalCommand(commandId: ID!, input: OverrideInput!)` | `bot-commands:edit` |
| GraphQL Mutation | `removeGlobalCommandOverride(commandId: ID!)` | `bot-commands:delete` |
| System Query | `botCommandsForAccount(accountId: ID!, platform: String!)` | System key with `bots:internal` |

### REST Endpoints

All paths live under `/v1` and mirror the GraphQL mutations.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/bot-commands` | `bot-commands:read` | List account commands (+ inherited globals) |
| `POST` | `/v1/bot-commands` | `bot-commands:create` | Create an account command |
| `PUT` | `/v1/bot-commands/{id}` | `bot-commands:edit` | Update a command |
| `DELETE` | `/v1/bot-commands/{id}` | `bot-commands:delete` | Delete a command |
| `POST` | `/v1/bot-commands/{id}/override` | `bot-commands:edit` | Override a global command for the account |
| `DELETE` | `/v1/bot-commands/{id}/override` | `bot-commands:delete` | Remove the account's override of a global command |

## Plan Limits

The `plans.max_commands` column caps how many commands an account may define. It
is read straight from the account's canonical `plans` row on every create - both
`POST /v1/bot-commands` and the `createBotCommand` mutation enforce the same cap
with the same `PLAN_LIMIT_REACHED` error (ZAF-1092). `0` means unlimited; if the
plan row cannot be resolved the cap fails open (unlimited). There is no
per-account override for this limit.

| Tier | Max Commands |
|------|-------------|
| Free | 25 |
| Pro | 200 |

## Feature Gating

The whole Bot Commands surface is gated on the `feature:bot_commands` flag, in
addition to the `bot-commands:*` permissions. Every query and mutation
(`botCommands`, `botCommand`, `createBotCommand`, `updateBotCommand`,
`deleteBotCommand`, `overrideGlobalCommand`, `removeGlobalCommandOverride` on
GraphQL; `GET`/`POST`/`PUT`/`DELETE /v1/bot-commands` and the `/override`
endpoints on REST) enforces it on both protocols - GraphQL via
`FeatureGuard::new("feature:bot_commands")` chained before the permission guard,
REST via `require_feature(..., "feature:bot_commands", ...)`. With the flag
disabled the API rejects the call directly (`Feature 'feature:bot_commands' is
not available`, HTTP `403`); the webapp route gate is UX only. The
fleet-only `botCommandsForAccount` query (used by bot workers; System key with `bots:internal`) is
intentionally **not** feature-gated.

## RBAC Permissions

Account: `bot-commands:read/create/edit/delete`
Admin: `bot-commands:read/create/edit/delete` (via `require_admin_permission`)

## Key Files

| Path | Description |
|------|-------------|
| `crates/lo-bot-commands/` | Shared command execution crate (context, registry, permission, cooldown, template, variables) |
| `apps/api/src/db/bot_commands.rs` | Database operations |
| `apps/api/src/graphql/bot_commands.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/bot_commands_crud.rs` | REST endpoints |

## See Also

- [Bot Control](/features/bot-control) - Bot pause/resume/reconnect dashboard
- [Bot Connections](/features/bot-connections) - Custom bot identity OAuth flow
- [Bot Modules](/features/bot-modules) - Chat moderation modules
- [Automations](/features/automations) - Automation flows triggered by commands

---

## Features / Bot Connections

Source: https://docs.lumio.vision/features/bot-connections

# Bot Connections

The dashboard shows an explanation of the requested platform permissions before starting bot OAuth. It warns against using the channel's main account as the bot identity; the API rejects that account. The **Chat re-enter** action re-joins chat through `/v1/bot-rejoin` and does not reauthorize the bot credential. Connection results appear as dashboard toasts.

## Overview

Bot connections let chat workers act with a bot identity for each platform. Lumio supports global bot identities configured by admins and account-level bot identities connected by an account, but the OAuth app that issues bot tokens is resolved by Lumio's credential mode system. Operator-managed system bots use dedicated bot OAuth app keys, separate from the channel app keys, while account-fallback bot connects use the account's app credentials.

The **Chat bot** section in each Twitch, YouTube and Kick area of the [Connections group](/user-guide/connections) shows that platform's bot state, pause control, chat re-entry and own-bot connection. A bot OAuth flow returns to its platform area with `kind=bot`; a Discord invite returns to the Discord area (`/dashboard/settings/channel/connections/discord`).

## Global vs Custom Bots

- **Global Bot**: Connected by admins in the Provider Management page. All accounts use this bot by default. OAuth global bots are pinned to `credential_source = "system"` and use the platform's dedicated bot config keys. Discord has one global bot token; accounts connect servers to that bot through a verified invite.
- **Account Bot**: Connected by an account through the dashboard. It stores a separate bot access/refresh token in `bot_connections` and is meant to take priority over the global bot for that account. The OAuth client source is resolved for `(platform, bot)` and pinned on the row. The chat workers do not act as the account bot yet - see [Known Exceptions](#known-exceptions--operational-risk).

### Fallback Logic

```
Account has account bot connection for platform?
  -> YES: Use account bot token
  -> NO: Use global system bot token
```

## Platforms

| Platform | Auth Type | Token Refresh |
|----------|-----------|---------------|
| Twitch | OAuth2 | Yes (automatic) |
| YouTube | OAuth2 | Yes (automatic) |
| Kick | OAuth2 | Yes (automatic) |
| Discord | Static Bot Token | No (permanent) |

Spotify has no bot connection. YouTube channel connections remain BYO/account because of Google Cloud quota and consent-screen constraints, while YouTube bot connections have their own bot credential mode. A YouTube bot connect uses `youtube_bot_client_id` / `youtube_bot_client_secret` when configured; with no YouTube bot keys it degrades to the account-credential path because there is no YouTube channel app to fall back to.

## Credential Resolution

`CredentialResolver` resolves bot OAuth apps per `(platform, bot)`. The system path first reads the dedicated bot pair from `[auth]`:

| Platform | Bot config keys |
|----------|-----------------|
| Twitch | `twitch_bot_client_id`, `twitch_bot_client_secret` |
| YouTube | `youtube_bot_client_id`, `youtube_bot_client_secret` |
| Kick | `kick_bot_client_id`, `kick_bot_client_secret` |
| Discord | `discord_bot_client_id`, `discord_bot_client_secret` (server invite) |

If a dedicated bot pair is empty, Twitch and Kick bot flows fall back to the platform's channel pair and log a one-time warning. With neither bot nor channel keys, those OAuth flows degrade to `account` and use `app_credentials`. Discord has no account-app fallback: without both Discord bot app keys, a server invite fails closed. `[platform_credentials.bot].discord` accepts only `"system"`; an `"account"` override is ignored with a warning. `platformCredentialModes` includes a Discord Bot row whose `systemConfigured` becomes `true` when the Discord bot app pair is set.

The bot/channel split keeps provider limits separate by `client_id`: Twitch app-access tokens allow 800 requests per minute per `client_id`, and Kick EventSub subscription caps are 10,000 subscriptions per event type per app.

## Bot Scopes

Bot connections use minimal scopes focused on chat functionality, plus the
Twitch moderation scopes that extension chat actions need:

| Platform | Scopes |
|----------|--------|
| Twitch | `chat:read`, `chat:edit`, `user:write:chat`, `user:bot`, `user:read:chat`, `moderator:manage:banned_users`, `moderator:manage:chat_messages` |
| YouTube | `youtube.force-ssl` |
| Kick | `chat:write` |
| Discord | `bot`, `applications.commands`, `identify` for the verified server invite |

### Extension chat actions

Extensions moderate chat (`chat:delete`, `chat:ban`, `chat:unban`,
`chat:timeout`) with the account's **own bot connection**, never with a
person's login. The bot must be a moderator of the channel. Twitch supports all
four actions, YouTube all except unban, and Kick none. A Twitch bot connected
before the two `moderator:manage:*` scopes were requested keeps chatting
normally (it is **not** flagged for reconnect), but extension moderation fails
with `bot_scope_missing` until the streamer reconnects the bot. Extension
`chat:send` is published to the account's running bot like an automation chat
step; on Twitch it therefore comes from the global bot (see below). Details:
[useLumioAction → Chat](https://developers.lumio.vision/sdk/hooks/use-lumio-action#chat).

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/bot_connections.rs`) -- Queries for listing bot connections, bot connection statuses with enablement. Mutation for deleting bot connections.
- **REST** -- Bot connection OAuth uses the unified web-host callback for `system` flows and retains the legacy per-flow exchange for `account` fallback. Both exchanges are bound to the interactive session of the user who started the authorize step (ZAF-1922).
- **Database** (`apps/api/src/db/bot_connections.rs`) -- PostgreSQL operations for the `bot_connections` table. Supports list, get, upsert, and delete operations.
- **OAuth** (`apps/api/src/oauth.rs`) -- `get_fresh_bot_token()` reads the pinned `credential_source`, resolves the matching OAuth client source, and returns fresh tokens; `update_bot_connection_tokens()` saves refreshed tokens.

### Frontend

- Platform areas in the Connections group show bot status beside the channel, its rights and its app.
- **Connect** starts OAuth with bot-specific scopes for Twitch, YouTube, or Kick.
- Discord's global token is configured by admins. Account members invite that same bot to individual servers on the Discord tab; no account bot token is stored or refreshed.

### Discord servers

The Discord area (`/dashboard/settings/channel/connections/discord`) lists every server linked to the active account. **Add server** opens the shared connect dialog, which explains that the inviter needs **Manage Server** on Discord. The invite asks to add the bot, register slash commands, and read the Discord name once (`identify`); the user token is revoked immediately after the verified code exchange. Discord returns through `/api/connections/oauth/discord/callback`, then the browser returns to the Discord area with a toast naming the server.

Each row shows **Connected**, **Bot was removed from the server**, or **Permissions missing**. A server whose live notification is switched on also names the Discord channel it posts to. For the latter two, **Reconnect** repeats the verified invite. A removed bot keeps its server settings until reconnect or **Disconnect**; disconnect removes the mapping and settings. Several servers can belong to one account, but an active server cannot be taken over by another account.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `botConnections` | `bot-connections:read` | List bot connections for the account |
| `botConnectionStatuses` | `bot-connections:read` | Bot platform statuses with `enabled` field |
| `botStatus` | `bot-connections:read` | Per-platform bot status for the Bot Control dashboard |
| `botChannels(platform)` | System key with `bots:internal` | All bot-enabled channels for a platform (consumed by bot workers), plan-gated per account at read time |
| `platformCredentialModes` | `connections:read` | Credential mode per `(platform, kind)`, including bot rows for OAuth bot platforms |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `authorizeBot(platform)` | `bot-connections:create` | Start a bot OAuth flow. For Discord, return the verified invite URL for the global bot; an interactive session and `feature:bots` are required. |
| `deleteBotConnection(platform)` | `bot-connections:delete` | Delete a bot connection |
| `toggleBotForPlatform(platform, enabled)` | `bot-connections:create` | Toggle `bot_enabled` on the platform's channel connection |
| `rejoinBot(platform)` | `bot-connections:create` | Send a rejoin command to the bot worker for a platform |

### REST Endpoints

All paths live under `/v1`.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/bot-connections` | `bot-connections:read` | List bot connections for the account |
| `DELETE` | `/v1/bot-connections/{platform}` | `bot-connections:delete` | Delete a bot connection |
| `GET` | `/v1/bot-connections/{platform}/authorize` | `bot-connections:create` | Start OAuth and return the authorize URL; `discord` returns the verified server invite and requires an interactive session |
| `POST` | `/v1/bot-connections/{platform}/exchange` | `bot-connections:create` + session of the initiating user | Legacy account-source exchange for encrypted tokens. Bound to the initiator's interactive session (same check as the unified exchange, before PKCE and the token exchange; ZAF-1922). Discord server invites complete only at the unified callback |
| `POST` | `/v1/connections/oauth/{platform}/exchange` | -- | Unified exchange for system-sourced channel, account-bot, and admin global-bot OAuth callbacks |
| `GET` | `/v1/discord-guilds` | `bot-connections:read` | List servers with `bot_removed` and `missing_permissions` |
| `DELETE` | `/v1/discord-guilds/{guild_id}` | `bot-connections:delete` | Disconnect one server, remove its settings and make the bot leave it |
| `GET` | `/v1/bot-status` | `bot-connections:read` | Aggregated bot runtime status for the account |
| `POST` | `/v1/bot-toggle` | `bot-connections:create` | Pause or resume the bot for a platform |
| `POST` | `/v1/bot-rejoin` | `bot-connections:create` | Force the bot to reconnect / rejoin the channel |

Request and response bodies use snake_case and mirror the GraphQL counterparts.

## Channel Discovery (bot workers)

Each bot worker polls `botChannels(platform)` to learn which channels to join.
The query requires a system key carrying
[`bots:internal`](../api-reference/permissions.md#system-key-only-permissions)
(ZAF-1922) - a system key without that grant is refused. The returned
`BotChannel` carries `accountId`, `channelName`, `channelId`, `botEnabled`,
`botType`, `customBotToken`, and `accessToken` - the decrypted channel OAuth
token, exposed only over this `bots:internal`-gated query (the same trust
boundary as `customBotToken`).

The list is plan-gated per account **at read time**: an account whose
`feature:bots` is off is left out entirely, and a `custom` bot row whose account
lacks `feature:custom_bot` is served as the global bot with no custom bot token.
Because the check runs on every read, plan downgrades, per-account overrides and
kill switches take effect on the fleet without rewriting the account's stored bot
configuration - re-enabling the feature restores it unchanged.

Each worker requests only the fields it needs:

| Bot | Fields requested | Uses them for |
|-----|------------------|---------------|
| twitch-bot | `accountId`, `channelName`, `channelLogin` | IRC `JOIN` target and message routing |
| youtube-bot | `accountId`, `channelName`, `accessToken` | Live-chat poll + send |
| kick-bot | `accountId`, `channelName` | Discovery only (see below) |

A worker must request only fields `BotChannel` actually exposes: GraphQL rejects
the **entire** query on an unknown field, which leaves the worker subscribed to
zero channels. The struct must also carry `#[serde(rename_all = "camelCase")]`
or the camelCase response fails to deserialize. Both traps are guarded by
`apps/api/tests/bot_channel_queries.rs` and per-bot deserialization tests.

### Worker health signal

A channel sync that fails repeatedly is surfaced, not silent: each worker's
`/ready` endpoint returns `503` once channel sync has failed several times in a
row, and reports `channels_active`, `channels_skipped`, and
`consecutive_sync_failures` as JSON. `/health` (liveness) stays OK while the
process runs.

## Outbound Safety

All tenants on a platform share one Lumio bot connection, so the bots protect it
centrally:

- **Sanitised sends.** Every outgoing message passes the platform transport wrapper
  (`crates/lo-chat-outbound`): one line, no leading `/` or `.`, capped at the
  platform maximum. Discord messages never ping `@everyone`, `@here`, users or
  roles except a feature post's configured role.
- **Twitch throughput.** The Twitch bot throttles its connection with a token bucket:
  100 messages per 30 s sustained, bursts of 20, across all channels. A send that
  would wait more than 2 s is dropped and logged. Configure it with
  `TWITCH_BOT__BOT__OUTBOUND_MESSAGES_PER_30S` / `TWITCH_BOT__BOT__OUTBOUND_BURST`
  ([Installation](../getting-started/installation.md#bot-outbound-throttle)); raise it
  only for a Twitch-verified bot account.
- **Built-in command cooldown.** `!song`, `!uptime` and the other built-ins fire at
  most once per 5 s per command and channel.
- **State keyed by stable ids.** Bots key per-tenant state by account id and the
  platform's stable id (Twitch login, Kick slug, YouTube channel id, Discord
  snowflake) — never by a display title. The YouTube bot also ignores the echo of
  its own chat posts and logs chat events without viewer names or message text.

## Discord Feature Channels

`setDiscordGuildFeature` binds a feature (live notification, event feed, …) to a
channel only if the channel is one of that server's channels **as reported by the
Discord gateway** that the bot can view (the bot's
`lumio:discord_guild:{guild_id}:channels` cache, which also feeds the channel picker
via `discordGuildChannels`). Otherwise the mutation fails with
`Channel does not belong to this Discord server or the Lumio bot cannot view it`;
if the bot has not reported the server's channels yet it fails closed with
`Cannot verify the channel: …`.

The channel list holds only channels the bot has `VIEW_CHANNEL` on, computed from
the bot's roles and the channel's permission overwrites; a category is listed when
any of its channels is. Discord sends channels a bot cannot view as obfuscated
objects named `___hidden___` (mandatory for all bots from 2026-11-16) — they never
appear in the picker. The list is rebuilt on `GUILD_CREATE`, `CHANNEL_*`, role
changes and changes to the bot's own member, so a channel shows up again as soon as
the bot is given access. If the bot's own member is missing from the gateway cache,
the list is empty (fail closed).

The Discord bot builds its channel→server map only
from gateway data (`GUILD_CREATE`, `CHANNEL_CREATE/UPDATE/DELETE`, including
channels it cannot view), re-checks the
channel before every feature post, and skips (and logs) a stored mapping whose
channel is not in that server. Mappings are never deleted for this. This mutation is
GraphQL-only; there is no REST twin.

## Known Exceptions & Operational Risk

- **Twitch chat always runs as the global bot.** The twitch-bot holds a single
  IRC connection authenticated with the configured global bot account
  (`[bot] username` / `oauth_token`) and joins every channel with it. An account
  bot connection is stored and kept fresh by the Token Refresh Worker, but the
  twitch-bot does not connect as it, so commands and replies come from the
  global bot. The worker therefore does not request `botType` or
  `customBotToken` from `botChannels` - it holds no account bot secret in memory.
- **Kick live subscription is deferred.** The kick-bot subscribes to chat over
  Kick's Pusher WebSocket keyed by a `chatroom_id`, which Lumio does not store
  server-side, so `botChannels` cannot supply it. The kick-bot therefore
  discovers its channels but subscribes to none, logging a `warn!` with a skip
  counter (reflected on `/ready`). The Pusher path also uses a hard-coded public
  app key with no auth frame - an **unofficial** channel with no platform
  contract; the official Kick chat ingest used by `apps/api` is the documented
  webhook. Building out Kick bot chat is tracked separately.

## Permissions

| Permission | Owner | Admin | Moderator |
|------------|-------|-------|-----------|
| `bot-connections:read` | Yes | Yes | Yes |
| `bot-connections:create` | Yes | Yes | No |
| `bot-connections:delete` | Yes | Yes | No |

## Database

Bot connections are stored in the `bot_connections` table:

| Column | Type | Description |
|--------|------|-------------|
| `id` | UUID | Primary key |
| `account_id` | UUID | Account (nil UUID for global bots) |
| `platform` | VARCHAR | Platform name |
| `bot_type` | VARCHAR | `global` or `custom` |
| `bot_username` | VARCHAR | Bot display name |
| `access_token` | TEXT | Encrypted OAuth token |
| `refresh_token` | TEXT | Encrypted refresh token |
| `scopes` | TEXT[] | Granted scopes |
| `expires_at` | TIMESTAMPTZ | Token expiration |
| `credential_source` | TEXT | Pinned OAuth app source: `system` or `account` |

## Token Refresh

The Token Refresh Worker automatically refreshes bot connection tokens alongside channel and login connection tokens. For OAuth bot rows, refresh follows `bot_connections.credential_source`: `system` rows use Lumio's configured bot OAuth app for the platform, with the channel fallback when the dedicated bot pair is missing, while `account` rows use the account's encrypted `app_credentials`. The Discord global bot token is static, and server mappings contain no OAuth token or refresh token. See [Token Refresh](/features/token-refresh) for details.

## Feature Flags

The whole Bot Control surface is gated on the umbrella `feature:bots` flag.
Every query and mutation (`botConnections`, `botConnectionStatuses`, `botStatus`,
`authorizeBot`, `deleteBotConnection`, `toggleBotForPlatform`, `rejoinBot` on
GraphQL; `GET /v1/bot-connections`, `GET /v1/bot-status`, `POST /v1/bot-toggle`,
`POST /v1/bot-rejoin`, the authorize/exchange OAuth endpoints, and
`DELETE /v1/bot-connections/{platform}` on REST) enforces it on both protocols —
GraphQL via `FeatureGuard::new("feature:bots")` chained before the permission
guard, REST via `require_feature(..., "feature:bots", ...)`. With `feature:bots`
disabled the API rejects the call directly (`Feature 'feature:bots' is not
available`, HTTP `403`); the webapp route gate is UX only. The fleet's
`botChannels` query (used by bot workers to discover channels to join) is not a
caller-facing guard but applies the same plan flags per account when it builds
the list: `feature:bots` off drops the account's row, `feature:custom_bot` off
serves a custom bot as the global bot (see
[Channel Discovery](#channel-discovery-bot-workers)).

For Twitch, YouTube and Kick, new account-bot connections also check the finer
`platform:{platform}:bot` sub-flag on authorize; existing connections continue
working when it is off. The Discord authorize branch checks `feature:bots` and
`bot-connections:create` but does not run that platform sub-flag check; the
Discord tab is disabled in the web UI when Discord bot connections
are unavailable. See
[Provider Management](/features/provider-management) for details.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/bot_connections.rs` | GraphQL queries and mutations |
| `apps/api/src/db/bot_connections.rs` | Database operations |
| `apps/api/src/oauth.rs` | Token refresh utilities (`get_fresh_bot_token`, `update_bot_connection_tokens`) |
| `apps/api/src/platforms.rs` | Bot OAuth scopes per platform |

## See Also

- [Provider Management](/features/provider-management) -- Feature flag controls for bot connections
- [Connections](/features/connections) -- Channel credential modes and the unified OAuth callback
- [Token Refresh](/features/token-refresh) -- Automatic token refresh worker
- [Bot Modules](/features/bot-modules) -- Chat moderation modules that use bot connections

---

## Features / Bot Control

Source: https://docs.lumio.vision/features/bot-control

# Bot Control

## Overview

The [Connections group](/user-guide/connections) of the settings window shows bot control in the **Chat bot** section of the Twitch, YouTube and Kick areas. Discord server status and connection actions appear in the [Discord area](/features/bot-connections#discord-servers). The Overview lists bots and servers that need attention.

## Chat Bot Control

Per-platform bot management in the platform's area of the settings window (`/dashboard/settings/channel/connections/{platform}`):

- **Status:** in chat, paused, offline, disconnected or waiting for a channel.
- **Pause / resume:** `toggleBotForPlatform` updates `channel_connections.bot_enabled`.
- **Re-enter chat:** `rejoinBot` sends a `bot_join` action via Redis pub/sub to trigger an immediate channel rejoin. This does not renew OAuth.
- **Reconnect bot:** a disconnected own bot repeats its OAuth grant on the same platform tab.

### Database

`channel_connections.bot_enabled` (BOOLEAN, default true) - when false, bots ignore this channel during sync.

### API

| Type | Endpoint | Permission |
|------|----------|------------|
| GraphQL Query | `botStatus` | `bot-connections:read` |
| GraphQL Mutation | `toggleBotForPlatform(platform, enabled)` | `bot-connections:create` |
| GraphQL Mutation | `rejoinBot(platform)` | `bot-connections:create` |
| REST | `GET /v1/bot-status` | `bot-connections:read` |
| REST | `POST /v1/bot-toggle` | `bot-connections:create` |
| REST | `POST /v1/bot-rejoin` | `bot-connections:create` |
| System Query | `botChannels(platform)` | System key with `bots:internal` |

### Bot Worker Actions

All chat bots listen for Redis pub/sub actions on `lumio:bot:action:{platform}:{account_id}`:
- `bot_join` / `bot_sync` - Refresh the Discord guild map immediately; other bot workers apply their own sync behavior
- `bot_leave` - Immediately remove account's channels from in-memory map + clear Redis cache
- `guild_leave` (Discord only, `data.guild_id`) - Published when an account disconnects a Discord server. The bot re-syncs its guild map and leaves the server unless it is mapped again (reconnect or takeover); without a fresh map it stays

## Discord Server Mapping

Discord guilds are mapped to Lumio accounts via `discord_guild_connections` table.

### Tables

- `discord_guild_connections` - guild_id → account_id mapping (UNIQUE on guild_id)
- `discord_guild_settings` - per-guild JSONB settings
- `discord_guild_channel_mappings` - feature → Discord channel routing (live_notification, event_feed, chat_mirror, etc.)

### Server connection

The **Discord** area (`/dashboard/settings/channel/connections/discord`) shows each server's status. **Add server** and **Reconnect** start `authorizeBot(platform: "discord")` through `/api/connections/bot/discord/authorize`. Discord returns to `/api/connections/oauth/discord/callback`; the unified exchange redeems the code and takes the server ID from Discord's token response. After verification it links the server to the account, returns to the Discord area and notifies the running bot to refresh its guild map. A Discord user token is revoked after that one-time check and is never stored. The equivalent REST authorize endpoint is `GET /v1/bot-connections/discord/authorize`; the old `/v1/discord-guilds/exchange` route is not part of this flow.

The server's status is **Connected**, **Bot removed**, or **Permissions missing**. Removal on Discord marks the connection while preserving its settings; reconnecting clears the mark. **Disconnect** removes the mapping and its server settings, and the bot leaves the server.

### Redis Cache

| Key | Content | TTL |
|-----|---------|-----|
| `lumio:discord_guild:{guild_id}` | account_id | 1h |
| `lumio:discord_guild:{guild_id}:channels` | JSON array of the channels the bot can view (`VIEW_CHANNEL`) | 1h |
| `lumio:discord_guild:{guild_id}:roles` | JSON array of roles | 1h |
| `lumio:discord_guild:{guild_id}:features` | JSON array of feature mappings | 1h |
| `lumio:discord_channel_guild:{channel_id}` | guild_id (reverse lookup) | 1h |

### Feature-Channel Mappings

The catalogue is the `DISCORD_FEATURES` const in `apps/api/src/graphql/discord_guilds.rs` - adding one is a code change, not a database migration. `setDiscordGuildFeature` rejects any key not in the list:

| Feature Key | Description |
|-------------|-------------|
| `live_notification` | Stream live alerts |
| `event_feed` | Follows, subs, donations |
| `chat_mirror` | Platform chat → Discord |
| `announcement` | Announcements |
| `moderation_log` | Ban/timeout logs |
| `clip_feed` | New clips |

### API

| Type | Endpoint | Permission |
|------|----------|------------|
| GraphQL Query | `discordGuildConnections` | `bot-connections:read` |
| GraphQL Mutation | `authorizeBot(platform: "discord")` | `bot-connections:create`, interactive session and `feature:bots` |
| GraphQL Mutation | `disconnectDiscordGuild(guildId)` | `bot-connections:delete` |
| GraphQL Query | `discordGuildChannels(guildId)` | `bot-connections:read` |
| GraphQL Query | `discordGuildRoles(guildId)` | `bot-connections:read` |
| GraphQL Query | `discordGuildFeatures(guildId)` | `bot-connections:read` |
| GraphQL Mutation | `setDiscordGuildFeature(...)` | `bot-connections:create` |
| System Query | `discordBotGuilds` | System key with `bots:internal` |
| System Mutation | `updateDiscordGuildInfo(...)` | System key with `bots:internal` |
| System Mutation | `removeDiscordGuildByBot(guildId: String!)` | System key with `bots:internal` |
| REST | `GET /v1/bot-connections/discord/authorize` | `bot-connections:create`, interactive session and `feature:bots` |
| REST | `GET /v1/discord-guilds`, `DELETE /v1/discord-guilds/{guild_id}` | `bot-connections:read` / `bot-connections:delete` |

## Admin

Admin permissions: `bot-control:read/edit`, `discord-guilds:read/delete` (enforced via `require_admin_permission`).

- `/admin/bot-control` - View/toggle bots per account. REST: `GET /v1/admin/bot-control/statuses`, `PUT /v1/admin/bot-control/{account_id}/{platform}`.
- `/admin/discord-guilds` - View all guild-to-account mappings, delete connections. REST: `GET /v1/admin/discord-guilds`, `DELETE /v1/admin/discord-guilds/{guild_id}`.

## Feature Gating

The Bot Control surface (`bot_connections` resolvers/routes - bot status, toggle,
rejoin, authorize, delete) is gated on the `feature:bots` flag on both protocols
(GraphQL `FeatureGuard`, REST `require_feature`). With `feature:bots` disabled the
API rejects the call directly; the webapp route gate is UX only. See
[Bot Connections › Feature Flags](/features/bot-connections#feature-flags) for the
full endpoint list.

## Security

- Guild ownership verified before channel/role queries
- Channel ownership verified in Discord bot actions (post_message)
- GuildDelete with `unavailable=true` only cleans cache, preserves DB
- Admin middleware on API routes
- Snowflake validation on all Discord IDs
- UUID validation on action listener account_id

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/bot_connections.rs` | GraphQL queries and mutations for bot status/toggle/rejoin |
| `apps/api/src/graphql/discord_guilds.rs` | GraphQL for Discord guild management |
| `apps/api/src/db/discord_guilds.rs` | Database operations for Discord guilds |
| `apps/discord-bot/src/handlers/events.rs` | Discord bot gateway event handling |
| `extensions/system/` | System extension manifests and handlers for built-in bot modules |

## See Also

- [Bot Connections](/features/bot-connections) - Custom bot identity OAuth flow
- [Bot Commands](/features/bot-commands) - Dynamic command system for all bots
- [Bot Modules](/features/bot-modules) - Chat moderation modules
- [Provider Management](/features/provider-management) - Feature flag controls

---

## Features / Tokens

Source: https://docs.lumio.vision/features/tokens

# Tokens

## Overview

The Tokens module manages popout tokens for dashboard popout pages and other browser-source contexts where cookie-based authentication is not practical. Popout tokens are non-expiring by default, but each token can optionally be given an expiry time or revoked (see the `expires_at` / `revoked_at` lifecycle fields). Each token has configurable permissions, an optional user assignment, and a label for identification. The full token is only shown once at creation time; afterward, only a prefix is stored for identification. Tokens are hashed before storage for security.

Popout tokens are one of Lumio's nine authentication types and carry the raw prefix `lm_pop_`. This module and the **Access → Popout Tokens** area (`/dashboard/settings/channel/tokens`) cover popout tokens (`overlay_tokens` table) exclusively. Do not confuse them with the other token types: **User API Keys** (`AuthContext::ApiKey`, `api_keys` table; the `is_system = true` rows are System Keys and are managed from the admin panel), **Overlay Token** (`lm_overlay_*`), **Shared Overlay Token** (`lm_share_*`), **Extension Token** (`lm_ext_*`) and **Widget Token** (`lm_widget_*`). Each has its own table, its own lifecycle, and its own feature documentation.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/tokens.rs`) -- Queries for listing tokens. Mutations for creating, updating, and deleting tokens.
- **Token Generation** (`crates/lo-auth/src/popout_token.rs`) -- `generate_popout_token()` produces a cryptographically random token, its hash (for storage), and a prefix (for display).
- **Authentication** -- Popout tokens are one of Lumio's authenticated token contexts. When a request includes a raw `lm_pop_*` token, the auth middleware hashes it and looks it up in the `overlay_tokens` table. The token's permissions are used for authorization.

### Frontend

- The settings area gate checks `tokens:read` and `feature:tokens` in both the window list and `GET /api/settings/sections/[id]`. A deep link to a disallowed area receives a locked or no-access state; hiding its list entry alone does not authorize a read.
- Token management page (`token-list.tsx`) listing all tokens as cards (`token-card.tsx`) with their labels, permissions, prefixes, assigned member, and an always-visible lifecycle status line derived in `token-status.ts`.
- A single full-screen wizard (`token-wizard.tsx`, on the shared `FullscreenWizard` primitive) handles **both** create and edit via an `isEdit` switch - three steps: **Identity** (label + assignee), **Permissions**, **Lifetime**. Create is linear and ends on a one-time token reveal; edit lets you jump to any step and Save from anywhere.
- Lifetime is chosen from presets (7 / 30 / 90 days, 1 year, Never, or a custom date) that resolve client-side to an absolute `expires_at` at end-of-day in the browser timezone (`token-lifetime.ts`, unit-tested); only the absolute timestamp is persisted.
- The permission selector only offers permissions the creator holds (mirroring the backend subset rule); copy-to-clipboard for the full token at creation (shown only once).
- Delete is a separate confirmation dialog, distinct from revoke.
- Popout URLs use format: `/popout/[view]?token=xxx`.

## API

### GraphQL Queries

| Query | Permission | Description |
|-------|-----------|-------------|
| `popoutTokens` | `tokens:read` + `feature:tokens` | List all popout tokens for the account. Returns `id`, `accountId`, `userId`, `tokenPrefix`, `label`, `permissions`, `effectivePermissions` (the stored scopes the bound member's current role still grants), `createdAt`, `expiresAt`, `revokedAt`, `lastUsedAt`. Never exposes the token hash. |
| `myPermissions` | Auth | Return the permissions of the *current* auth context - role-derived for a JWT user, the token's own scope for a popout token or API key. Never returns the `["*"]` sentinel. REST twin: `GET /v1/tokens/me`. |

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `createPopoutToken(input: CreatePopoutTokenInput)` | `tokens:create` + `feature:tokens` + **first-party session** | Create a new popout token. Returns `token` (the full string, shown only once) and `popoutToken` (the metadata). If no `userId` is provided, binds to the **creator** (the acting first-party user) - a popout token is always bound to an explicit user (see the first-party note below). An optional `expiresAt` sets the lifetime at creation; `null`/absent = never expires, and a past value is rejected (see below). |
| `updatePopoutToken(input: UpdatePopoutTokenInput)` | `tokens:edit` + `feature:tokens` | Update a token's label, permissions, user binding, expiry, or revocation state. A new user binding follows the same rule as create (self, or a member whose role does not exceed yours). Uses double-option semantics: absent = don't change, null = clear, value = set - except `userId: null`, which binds the token to the **editor** (see below). |
| `deletePopoutToken(id: UUID)` | `tokens:delete` + `feature:tokens` | Delete/revoke a popout token. Verifies account ownership. Returns `DeleteTokenResult { success }`. |
| `exchangePopoutToken(token: String!)` | None - possession of a valid popout token *is* the authorization | Exchange a raw `lm_pop_*` token for a 15-minute **popout session** JWT and return `PopoutSession`. Validates the prefix, lifecycle, and continued membership of any assigned user, then sets the session as an httpOnly cookie (`lumio-popout-token`, `Path=/`, `SameSite=Lax`). REST twin: `POST /v1/auth/popout/exchange`. |

Every popout-token query and mutation is gated **twice** - by the `feature:tokens`
plan flag and by the RBAC permission. GraphQL composes them as
`FeatureGuard::new("feature:tokens").and(PermissionGuard::new(…))`; REST calls
`auth.require_permission(…)` followed by `require_feature(…, "feature:tokens", …)`.
Both gates must pass on both protocols; only the order in which the two errors
surface differs (GraphQL reports `FEATURE_DISABLED` first, REST reports the
permission failure first).

**Minting requires a first-party session (ZAF-1017 / ZAF-469).** Creating a popout
token - `createPopoutToken` / `POST /v1/tokens` - is itself a first-party action:
the caller must be a logged-in user session or a user's own API key. A
popout/overlay/widget/extension token is rejected with `FORBIDDEN` (`403` on REST).
**A popout token is always bound to an explicit user (ZAF-1922).** The token's
bound `user_id` is its acting-user identity, and there is no implicit fallback to
the account owner anywhere: an omitted `userId` (NULL) on create binds the
**creator**, and an unassign on update (`"user_id": null` on `PATCH /v1/tokens/{id}`,
`userId: null` on `updatePopoutToken`) binds the **editor**. Both need a
first-party editor/creator - a popout/overlay/widget/extension token gets
`FORBIDDEN` "This endpoint requires a logged-in user session" - and the resulting
binding goes through the same binding check as an explicit assignment. A token row
with no bound user (`overlay_tokens.user_id IS NULL`) resolves to nothing: the
raw-token path, the popout exchange and the WebSocket credential re-check all treat
it as invalid. Migration `20261007000001_bind_unassigned_popout_tokens` bound every
legacy unbound token to its account's owner at migration time (reversible; the
touched ids are recorded in `zaf1922_popout_token_owner_backfill`); a token on an
ownerless account stays unbound and fails closed. Binding to another member requires that every account permission
on the target's role is in the caller's grantable set. The account owner counts
as holding the full account permission registry. The personal API-key
routes (`/v1/api-keys`, `userApiKeys` / `createUserApiKey` / `updateUserApiKey` /
`deleteUserApiKey`) carry the same first-party gate for the same reason.

### REST Endpoints

All paths live under `/v1/tokens`. Bodies are snake_case and mirror the GraphQL inputs. The full token string is returned only from `POST /v1/tokens` and cannot be retrieved later.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/tokens` | `tokens:read` | List popout tokens for the account (hash never exposed) |
| `POST` | `/v1/tokens` | `tokens:create` | Create a popout token; returns full token once. Accepts optional `expires_at` (RFC3339; `null`/absent = never expires; past value rejected) |
| `PATCH` | `/v1/tokens/{id}` | `tokens:edit` | Update label, permissions, user binding, expiry, or revocation state. `"user_id": null` binds the token to the editor (first-party session or own API key required) |
| `DELETE` | `/v1/tokens/{id}` | `tokens:delete` | Revoke a popout token |
| `GET` | `/v1/tokens/me` | Auth | Return the permissions granted to the current token (self-introspection). GraphQL twin: `myPermissions` |
| `POST` | `/v1/auth/popout/exchange` | None - the raw token is the credential | Exchange an active `lm_pop_*` token whose assigned member still belongs to the account for a 15-minute popout session JWT (also set as the `lumio-popout-token` httpOnly cookie). GraphQL twin: `exchangePopoutToken` |

`POST /v1/auth/popout/exchange` lives under the `Auth` tag rather than `/v1/tokens`,
because it is the authentication step, not token management.

### WebSocket

There is no `tokens:*` WebSocket channel. A popout token reaches live data by
exchanging itself for a popout session and then subscribing to the account-scoped
channels its own permission scope allows (`events:{account_id}`,
`chat:{account_id}`, …) - the channel gate in `crates/lo-websocket/src/gate.rs`
evaluates the token's permissions exactly like a user's.

### Input Types

**CreatePopoutTokenInput:**
| Field | Type | Description |
|-------|------|-------------|
| `label` | `String?` | Human-readable label for the token |
| `permissions` | `[String]` | List of permission strings the token grants |
| `userId` | `UUID?` | User to bind the token to (defaults to authenticated user). Must be a **member or the owner of the account** - a token cannot be bound to a user outside the account (rejected with `FORBIDDEN`), since the binding becomes the token's authenticated identity. Binding the token to **another** member additionally requires that every account permission of that member's role is one you hold yourself, and the account **owner** counts as holding every account permission - so only a caller holding the full permission set can bind a token to the owner. Otherwise both protocols return `FORBIDDEN` "Cannot bind a token to a member whose role exceeds your own permissions" (ZAF-1740 A1). Binding to yourself is always allowed. |
| `expiresAt` | `String?` | Optional lifetime (RFC3339). `null`/absent = never expires (the default). Must **not** be in the past - a back-dated value is rejected with `VALIDATION_ERROR` "expires_at cannot be in the past", identically on GraphQL and REST. Optional and additive: existing callers are unaffected. |

**UpdatePopoutTokenInput:**
| Field | Type | Description |
|-------|------|-------------|
| `id` | `UUID` | Token ID to update |
| `label` | `MaybeUndefined<String>` | Absent = no change, explicit `null` = clear, value = set. Explicit `null` and absent are distinct, as on REST. |
| `permissions` | `Option<[String]>` | Replace permissions list (absent = no change) |
| `userId` | `MaybeUndefined<UUID>` | Absent = no change, explicit `null` = unassign, which binds the token to the **editor** (a first-party user; a token-authenticated editor gets `FORBIDDEN`), value = assign. Explicit `null` and absent are distinct. An assigned user must be a **member or the owner of the account**. Binding to another member also requires the caller to hold every account permission on that member's role; the owner counts as holding the full account registry. |
| `expiresAt` | `MaybeUndefined<String>` | RFC3339. Absent = no change, explicit `null` = clear expiry (never expires), value = set expiry. Explicit `null` and absent are distinct, as on REST. |
| `revoke` | `Option<Boolean>` | `true` = revoke now, `false` = un-revoke, absent = no change |

## Permissions

| Permission | Description |
|-----------|-------------|
| `tokens:read` | View popout tokens (prefix, label, permissions) |
| `tokens:create` | Create new popout tokens |
| `tokens:edit` | Update token label, permissions, user binding |
| `tokens:delete` | Delete/revoke popout tokens |

In addition to the permission, the account's plan must carry the `feature:tokens`
flag - see the feature-gate note under *GraphQL Mutations*.

**Subset rule.** A token can never grant more permissions than its creator holds.
`services/token_permissions::ensure_within_creator_permissions` runs on create
**and** on any permission-replacing update, on both protocols, and returns the
same `ApiError` (routed through `to_graphql_error` on GraphQL) so the message and
code are identical.

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `overlay_tokens` | PostgreSQL | id, account_id, user_id (nullable column; a NULL row never resolves - every live token is bound), token_hash (sha256 hash), token_prefix (first N chars for display), label, permissions (text array), created_at, expires_at (nullable), revoked_at (nullable), last_used_at (nullable; written at most once a minute per token, so a polling overlay does not rewrite the row on every request) |

### Security

- The full token is generated using `generate_popout_token()` from `lo-auth`.
- Only the hash is stored in the database; the full token cannot be recovered.
- The full token is returned exactly once at creation time.
- The `token_prefix` (first few characters) is stored for identification in the UI.
- Tokens are non-expiring by default (for browser sources that run unattended), but an optional `expires_at` can be set. Expired, revoked (`revoked_at`), or member-bound tokens whose assigned member has left the account are rejected by raw-token resolution and exchange exactly like invalid ones, without disclosing which state applies.
- A token's `user_id` becomes its authenticated popout identity, so it is validated against the account on create **and** update: only a **member or the owner** of the account may be bound (both protocols return `FORBIDDEN` otherwise). This prevents a member from minting a token bound to another user (ZAF-450 S1). Binding the token to **another** member additionally requires that every account permission of that member's role is one you hold yourself, and the account **owner** counts as holding every account permission - so only a caller holding the full permission set can bind a token to the owner. Otherwise both protocols return `FORBIDDEN` "Cannot bind a token to a member whose role exceeds your own permissions" (ZAF-1740 A1). Binding to yourself is always allowed.
- A popout token must never act on the **first-party user surface** - the endpoints keyed on the acting user's *own* identity. Reading or editing the profile (`/v1/users/me`), listing/revoking sessions, listing/deleting login connections and flagged connections, linking/reconnecting an OAuth login provider (`POST /v1/auth/link`), managing login assignments, notifications (list, mark read, preferences, bulk read/delete, actions), the developer application, creating/dissolving/leaving an account, and **minting a session JWT** (`POST /v1/auth/ws-token` / `issueWsToken`, `POST /v1/accounts` / `createAccount`) all require a logged-in user session or a user's own API key. A popout/overlay/widget/extension token - whose bound `user_id` could be the account owner - is rejected with `FORBIDDEN` on **both** REST and GraphQL, so it can never read the owner's data, act as the owner, or obtain an owner-bound JWT (ZAF-450 S1 / ZAF-469).
- `expires_at` may be set **at creation** (`createPopoutToken` / `POST /v1/tokens`) and there it must be in the future - a back-dated value is rejected with `VALIDATION_ERROR`. The **update** path (`updatePopoutToken` / `PATCH /v1/tokens/{id}`) intentionally allows a past `expires_at`, so back-dating an existing token remains a supported soft-revoke.
- The same gate covers the **extension-developer surface**, which keys off the acting user's developer identity (ZAF-471). Developer profile, revenue and payout data; payout-settings changes and payout requests; developer limits and limit-increase requests; creating/submitting/deleting extensions and inviting testers; developer-team reads and management; and extension-access grants/invites all require a logged-in user session or a user's own API key - a popout/overlay/widget/extension token is rejected with `FORBIDDEN` on both protocols. Extension secrets belong to the extension, not to an account, so they sit behind the same developer-identity gate. The money-moving writes - payout-settings changes, payout requests, Stripe Connect onboarding and the billing checkout / portal / cancel mutations - are stricter still: they are session-only (ZAF-1750) and refuse a user's own API key too (see [Authentication → Session-only Surfaces](../api-reference/authentication.md#session-only-surfaces)).

## Data Flow

1. User creates a popout token, selecting which permissions it should grant.
2. `generate_popout_token()` creates a random token, computes its hash, and extracts a prefix.
3. The hash, prefix, permissions, and metadata are stored in `overlay_tokens`.
4. The full token is returned to the user (shown once, must be copied).
5. User adds the token to a popout URL: `/popout/events?token=xxx`.
6. When the popout loads, the auth middleware:
   - Extracts the `token` query parameter.
   - Hashes it and looks up the hash in `overlay_tokens`.
   - Checks the lifecycle via `popout_origin_active` (not revoked, `expires_at` not passed) and verifies that any assigned member still belongs to the account.
   - If usable, authenticates the request with the token's `account_id`, its bound `user_id`, and permissions. A token with no bound user is rejected like an invalid one.
7. Rather than resending the raw token on every request, the popout can exchange it once for a **popout session** (`exchangePopoutToken` / `POST /v1/auth/popout/exchange`). The session is a short-lived JWT stored as the httpOnly `lumio-popout-token` cookie and resolves back to `AuthContext::PopoutToken` with the origin token's permission subset. The lifecycle and assigned-member checks are re-run per request against the origin token, so revocation, expiry, or the assigned member leaving the account also ends live sessions.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/tokens.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/tokens.rs` | REST handlers under `/v1/tokens` |
| `apps/api/src/db/tokens.rs` | Database operations for token CRUD |
| `apps/api/src/services/token_permissions.rs` | Creator-subset, expiry and account-membership validation shared by both protocols |
| `apps/api/src/services/popout_exchange.rs` | Raw token → popout session exchange |
| `crates/lo-auth/src/popout_token.rs` | Token generation (random token, hash, prefix) and the `popout_origin_active` lifecycle gate |
| `crates/lo-auth/src/jwt.rs` | `create_popout_session_token` - mints the popout-session JWT |
| `crates/lo-auth/src/context.rs` | `AuthContext::PopoutToken` - the popout authentication type |

---

## Features / Uploads

Source: https://docs.lumio.vision/features/uploads

# Uploads

## Overview

The Uploads module provides file upload and management for Lumio accounts. Files are uploaded via multipart REST endpoints and stored in a configurable storage backend (e.g., S3-compatible object storage). Upload metadata (filename, content type, size, storage key, purpose) is tracked in PostgreSQL. Download URLs are generated as presigned URLs with a one-hour expiry.

Every uploads operation on both protocols is gated on the `feature:uploads` feature flag **in addition to** the `uploads:*` permission. The dashboard segment `/dashboard/uploads` is wrapped in a `FeatureRouteGate` for the same flag.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/uploads.rs`) -- Queries for listing and fetching uploads. Mutation for deleting uploads (stored file + metadata, via the shared deletion service).
- **REST** (`apps/api/src/routes/uploads.rs`) -- Full REST CRUD: list uploads, get upload with presigned download URL, multipart file upload, and delete (stored file + metadata, via the shared deletion service).
- **Storage** -- Configurable storage backend accessible via `AppState.storage`. Supports `upload()`, `presigned_download_url()`, and `delete()` operations. When no backend is configured, `POST /v1/uploads` returns `400 Storage is not enabled` and `GET /v1/uploads/{id}` returns the metadata with `download_url` omitted.
- **Deletion service** (`apps/api/src/services/uploads.rs`) -- `delete_upload` is the single delete path behind GraphQL `deleteUpload` and REST `DELETE /v1/uploads/{id}`, so both protocols remove the stored file and return the same errors.
- **Database** (`apps/api/src/db/uploads.rs`) -- PostgreSQL operations for upload metadata CRUD.

### WebSocket

Uploads have no WebSocket channel - `channel_gate_for` in `crates/lo-websocket/src/gate.rs` has no `uploads` arm, so an `uploads:{account_id}` subscription resolves to `ChannelGate::Unknown` and is rejected. Clients refresh the list by re-querying. This is a gap against the three-protocol rule, not a design choice.

### Frontend

`/dashboard/uploads` (`apps/web/src/app/(main)/(app)/dashboard/uploads/upload-list.tsx`) renders:

- a flat file list showing icon (by content-type family), filename, human-readable size, content type and creation date;
- an **Upload** button that opens a hidden single-file `<input type="file">` and `POST`s it to `/api/uploads` as `multipart/form-data`, then calls `router.refresh()`;
- a per-row delete button with an inline confirmation card.

The page uploads one file at a time, sends no `purpose` field, shows a busy state rather than a byte-level progress bar, and does not surface a download link - download URLs are obtained via `GET /v1/uploads/{id}`. Files are referenced by other features (e.g., overlay custom assets, alert images).

## API

### GraphQL Queries

| Query | Guards | Description |
|-------|--------|-------------|
| `uploads` | `feature:uploads` + `uploads:read` | List all uploads for the account. Each row carries a generated `downloadUrl`. |
| `upload(id: UUID!)` | `feature:uploads` + `uploads:read` | Get a single upload by ID (account-scoped) |

The GraphQL `Upload` type is camelCase: `id`, `accountId`, `uploadedBy`, `filename`, `contentType`, `sizeBytes`, `storageKey`, `purpose`, `createdAt`, `downloadUrl`. `downloadUrl` is **not** a presigned storage URL - it is `{server.public_url}/v1/uploads/{id}`, the REST endpoint that mints the presigned URL on request.

### GraphQL Mutations

| Mutation | Guards | Description |
|----------|--------|-------------|
| `deleteUpload(id: UUID!)` | `feature:uploads` + `uploads:delete` | Delete upload: removes the file from storage (best effort) and the metadata from the database. Returns `{ success: true }`; an unknown or foreign-account id fails with `Upload not found`. |

There is no GraphQL upload mutation: file transfer stays on REST because the payload is multipart.

### REST Endpoints

| Method | Path | Guards | Description |
|--------|------|--------|-------------|
| `GET` | `/v1/uploads` | `feature:uploads` + `uploads:read` | List all uploads for the account |
| `GET` | `/v1/uploads/{id}` | `feature:uploads` + `uploads:read` | Get upload details with a presigned download URL (1-hour expiry) |
| `POST` | `/v1/uploads` | `feature:uploads` + `uploads:create` | Upload a file via multipart form. Returns `201`. |
| `DELETE` | `/v1/uploads/{id}` | `feature:uploads` + `uploads:delete` | Delete upload: removes file from storage (best effort) and metadata from database. Returns `204`; an unknown or foreign-account id returns `404 Upload not found`. |

REST payloads are snake_case (`account_id`, `content_type`, `size_bytes`, `storage_key`, `download_url`, `created_at`).

### Upload Request Format

Multipart form data with fields:
- `file` (required) -- The file to upload. Filename and content type are read from the content disposition; the server does **not** sniff or validate the content type, and there is no allow-list of file types. A request with no `file` field returns `400 No file provided (use field name 'file')`.
- `purpose` (optional) -- Free-form purpose label for the upload (e.g., `alert_sound`, `overlay_image`). It is not validated against any enum; the only constraint is the column width (`varchar(50)`).

Any other multipart field is silently ignored.

### Storage Key Format

```
accounts/{account_id}/uploads/{uuid_v7}.{extension}
```

Example: `accounts/550e8400-e29b-41d4-a716-446655440000/uploads/01912345-6789-7abc-def0-123456789abc.png`

The extension is the segment after the last `.` in the client-supplied filename, and only when it is at most 10 characters; otherwise `bin` is used. Every account-owned object lives under `accounts/{account_id}/`, so the files of one account can be listed by prefix (`StorageClient::list_prefix`). Uploads stored before this layout keep their key `{account_id}/{uuid_v7}.{extension}`; the `storage_key` column always holds the real key.

## Permissions

| Permission | Description |
|-----------|-------------|
| `uploads:read` | View and download uploaded files |
| `uploads:create` | Upload new files |
| `uploads:delete` | Delete uploaded files |

## Database

| Table | Database | Description |
|-------|----------|-------------|
| `uploads` | PostgreSQL | `id`, `account_id` (FK, cascade), `uploaded_by` (nullable user FK, `ON DELETE SET NULL`: the file stays with the channel when the uploader deletes their profile), `filename` (varchar 255), `content_type` (nullable varchar 100), `size_bytes` (nullable bigint), `storage_key` (text), `purpose` (nullable varchar 50), `created_at`. Indexed on `account_id`. |
| `storage_deletion_queue` | PostgreSQL | Object keys of deleted channels, uninstalled installs and deleted extensions whose files still have to be deleted: `storage_key` (unique), `account_id` (no FK; empty for extension and sweep keys), `reason` (`account_deleted`, `install_deleted`, `extension_deleted`, `orphaned`), `attempts`, `next_attempt_at`, `last_error`. |

## Data Flow

### Upload Flow
1. Client sends a multipart POST to `/v1/uploads` with the file and optional purpose.
2. Server reads the file data in chunks, checking against `max_upload_size_bytes` during upload.
3. A unique storage key is generated: `accounts/{account_id}/uploads/{uuid_v7}.{ext}`.
4. File is uploaded to the storage backend via `storage.upload()`.
5. Metadata (filename, content_type, size, storage_key, purpose) is saved to PostgreSQL by `db::uploads::create_upload_within_quota`, which inserts the row only when the file fits the account's storage quota (see [Storage quota](#storage-quota)). If it does not fit, the stored file is deleted again and the request fails with `403 PLAN_LIMIT_REACHED` "Storage limit reached".
6. Response includes the upload metadata.

### Download Flow
1. Client requests `GET /v1/uploads/{id}`.
2. Server verifies account ownership.
3. If a storage backend is available, a presigned download URL is generated with 1-hour expiry.
4. The upload metadata and download URL are returned.

### Delete Flow
GraphQL `deleteUpload(id)` (used by the dashboard through `/api/uploads/{id}`) and REST `DELETE /v1/uploads/{id}` both call `services::uploads::delete_upload`:
1. Server verifies account ownership. An unknown id and another account's id are both reported as `Upload not found` (GraphQL error / REST `404`), so ids do not leak across accounts.
2. File is deleted from storage (best effort -- logged if it fails; skipped when no storage backend is configured).
3. Metadata is deleted from PostgreSQL.

### Size limit

The upload size cap comes from the deployment config key `storage.max_upload_size_bytes` (`LUMIO__STORAGE__MAX_UPLOAD_SIZE_BYTES`, `10000000` in `apps/api/config/default.toml`). It is the **same value for every account regardless of plan**. The check runs while the multipart stream is consumed, so an oversized file is rejected with `400 File exceeds maximum upload size of {n} bytes` before the whole body has to be read.

The per-plan `max_upload_size_bytes` column (Free: 10 MB, Pro: 50 MB) is surfaced through the billing queries and the admin plan editor but is **not** read by this route; the per-file cap is the deployment-wide value above.

### Storage quota

The account's total upload storage is capped by the plan's `max_storage_bytes` (Free: 100 MB, Pro: 1 GB; an `account_limits.max_storage_bytes` override wins; an account without a plan gets 100 MB). The bytes counted are every row in `uploads` **plus** the account's own sounds - extension-bundled sounds are the extension's files and do not count. The check and the insert run in one transaction under a per-account advisory lock, so two parallel uploads cannot both pass. A file that does not fit is refused with `403 PLAN_LIMIT_REACHED` ("Storage limit reached") and leaves neither a row nor a stored object.

The quota exists only on `POST /v1/uploads`: there is no GraphQL upload mutation (multipart stays on REST). The Sounds library keeps its own `max_sound_storage_bytes` cap; see [Sounds](./sounds.md).

### Deletion with the channel

When a channel is deleted - dissolved by its owner (immediately or at the end of the grace period) or deleted by a platform operator - its uploads go with it, files included. The delete transaction first copies the `storage_key` of every upload (and of the channel's other stored objects, see [Accounts](./accounts.md)) into `storage_deletion_queue`, then deletes the account; after the commit the files are deleted. A file whose delete fails stays queued, and the hourly account security worker retries it until it is gone. The count of deleted files is recorded as `deleted_object_count` on the `account:dissolved` / `system:account_deleted` audit event.

### Extension uploads: deletion with the install or the extension

Extensions upload images through `POST /v1/extensions/{extension_id}/uploads` (extension token). These files are stored once per extension under `extensions/{extension_id}/uploads/{hash}.{ext}`, named after their content: when two channels upload the same image, both get a row in `extension_uploads` for the same file. A file is therefore deleted only when no other install still has a row for it.

- **Uninstall.** Uninstalling with "delete data now" deletes the install and, in the same transaction, queues every upload file of that install that no other install references; the files are deleted right after. Uninstalling with the 30-day retention keeps the install (and its files) until the window ends; the daily data-deletion worker then deletes the install and queues the files the same way, and the hourly account security worker deletes them. A file another channel also uploaded stays.
- **Extension delete.** Deleting a draft extension (`DELETE /v1/developer/extensions/{id}` / `deleteExtension`) queues all its files in the same transaction - every install's uploads, the version files, bundle, source archive and manifest of every version, the icon and the screenshots - and deletes the bundled sounds of its installs, which point at those version files. After the commit the extension's storage prefixes (`{extension_id}/` and `extensions/{extension_id}/`) are listed and any file no row names is queued as well; then the files are deleted. Only files under these two prefixes are ever deleted.
- **Re-upload during a delete.** Uploading a file and deleting a queued file of the same name take the same per-file database lock, and the upload always writes the file again. A channel uploading an image at the moment another channel's copy is deleted therefore keeps a working file. If the file is written but its row cannot be recorded (for example because the install was uninstalled in the meantime), the file is queued for deletion as an orphan.
- **Orphan sweep.** Uploads left behind by uninstalls and extension deletes before this cleanup existed are found by `POST /v1/admin/storage/orphaned-extension-uploads/sweep` (GraphQL `adminSweepOrphanedExtensionUploads`), which needs the `admin:privacy-erase` admin permission. It lists `extensions/{extension_id}/uploads/` for every existing extension and counts the files no `extension_uploads` row references. By default it is a dry run and changes nothing; with `apply: true` it queues those files for deletion and records a `system:orphaned_storage_swept` audit event. Each queued file is checked again under the per-file lock before it is deleted.

Failed deletes stay in `storage_deletion_queue` and are retried hourly, as for channel deletion. The queue's `reason` is `install_deleted`, `extension_deleted` or `orphaned` for these cases (`account_deleted` for a channel).

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/graphql/uploads.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/uploads.rs` | REST endpoints (list, get, upload, delete) |
| `apps/api/src/services/uploads.rs` | Shared delete path (ownership, storage object, metadata) for GraphQL and REST |
| `apps/api/src/db/uploads.rs` | Database operations for upload metadata, including the quota-checked insert |
| `apps/api/src/services/storage_erasure.rs` | Deletes the stored files of a deleted channel, install or draft extension (queue + retry); orphaned extension upload sweep |
| `apps/api/src/db/storage_deletion.rs` | Deletion queue: enqueue per channel / install / extension, per-file lock, claim + retry |
| `apps/api/src/routes/extension_uploads.rs` | Extension upload + serve endpoints (extension token) |
| `apps/api/src/state.rs` | `AppState.storage` -- storage backend reference |
| `apps/web/src/app/(main)/(app)/dashboard/uploads/layout.tsx` | `FeatureRouteGate feature="feature:uploads"` on the whole segment |
| `apps/web/src/app/(main)/(app)/dashboard/uploads/upload-list.tsx` | File manager UI |
| `apps/web/src/app/api/uploads/route.ts` | Next.js proxy for list + multipart upload |

---

## Features / Sounds

Source: https://docs.lumio.vision/features/sounds

# Sounds

## Overview

The Sounds module provides a per-account audio library. Sounds are uploaded once and can be played directly in browser sources without leaving the dashboard. Extensions can bundle their own sounds and reference them via config fields, and automations can trigger playback in response to stream events.

Sounds are stored in the account's library and played back via the `sounds:{accountId}` WebSocket channel. Browser sources subscribed to this channel receive `sound:play` and `sound:stop` commands and execute them locally, keeping audio latency minimal.

The whole surface is gated on the `feature:sounds` feature flag in addition to the `sounds:*` permissions - on REST, on GraphQL, and on the WebSocket channel.

## Upload limits

Upload limits are enforced per plan, resolved as `COALESCE(account_limits.<col>, plans.<col>)` so a per-account override wins over the plan value:

| Limit | Plan column | Free | Pro |
|-------|-------------|------|-----|
| Max sounds | `max_sounds` | 10 | 50 |
| Max sound file size | `max_sound_file_size` | 5 MB | 20 MB |
| Max total sound storage | `max_sound_storage_bytes` | 100 MB | 1 GB |

Free and Pro are the only plans that exist.

The count and total-storage checks run inside the insert as a single atomic CTE, so two concurrent uploads cannot both slip past the cap. Extension-bundled sounds (`source_extension_id IS NOT NULL`) are excluded from both counters.

Accepted audio content types (`ALLOWED_AUDIO_TYPES` in `apps/api/src/routes/sounds.rs`): `audio/mpeg`, `audio/wav`, `audio/x-wav`, `audio/wave`, `audio/ogg`, `audio/webm`, `audio/mp4`, `audio/aac`, `audio/flac`. The type is detected from the file's magic bytes, not from the client-supplied `Content-Type` - an unrecognised file is rejected with `400 Unsupported audio format`.

Uploaded sounds also count toward the account's general upload quota (plan `max_storage_bytes`), which `POST /v1/uploads` checks against uploads plus own sounds; see [Uploads](./uploads.md#storage-quota).

## Storage and deletion

An uploaded sound is stored at `accounts/{account_id}/sounds/{sound_id}.{ext}`. Deleting a sound (`deleteSound` / `DELETE /v1/sounds/{id}`) deletes the row and the file.

When the channel is deleted - dissolved by its owner or deleted by a platform operator - its uploaded sound files are deleted with it: the delete transaction queues each sound's `storage_key` in `storage_deletion_queue` before the account CASCADE removes the rows, and the files are deleted after the commit. A failed delete stays queued and the hourly account security worker retries it. Extension-bundled sounds are not deleted: their rows point at the extension's own version files (`{extension_id}/versions/{version}/sounds/{file}`), which every install of the extension shares.

## Playback in browser sources

Browser sources (layers) that subscribe to `sounds:{accountId}` receive real-time playback commands. When a sound is played from the dashboard or via automation, the server publishes a `sound:play` event to the channel and all subscribed browser sources execute the audio locally.

Playback commands include:

- **`sound:play`** - start playing a specific sound. The payload carries `sound_id`, `stream_path` (`/api/sounds/{id}/stream`), `name`, the resolved `volume`, and `target`.
- **`sound:stop`** - stop playback of a specific sound. The payload carries `sound_id` and `target`.

A third event, **`sound:list:updated`**, is published on the same channel when the library changes (payload `{ action, sound_id }`), so open editors and pickers can re-sync.

## Targeting

When triggering sound playback, you can either broadcast to all browser sources or address one surface:

- **All browser sources** (default) - omit `target`; every browser source subscribed to the account's sounds channel receives the command.
- **A single surface** - pass a `target` object. It is not an overlay key but a two-field record:

```json
{ "type": "overlay", "id": "01912345-6789-7abc-def0-123456789abc" }
```

`type` must be exactly `"widget"` or `"overlay"` and `id` must be a UUID. Anything else is rejected with `400 target.type must be 'widget' or 'overlay'` - identically on REST (`target`) and GraphQL (`SoundTargetInput`).

This is useful when you have multiple overlays (e.g. a gameplay overlay and a facecam overlay) and want sounds to play from one specific source.

The `volume` argument is clamped server-side into `0.0–1.0` and defaults to `1.0`.

## RBAC

| Permission | Description | Owner | Admin | Mod |
|-----------|-------------|:-----:|:-----:|:---:|
| `sounds:read` | View the sound library | x | x | x |
| `sounds:create` | Upload new sounds | x | x | |
| `sounds:edit` | Rename and update sounds | x | x | |
| `sounds:delete` | Delete sounds from the library | x | x | |
| `sounds:play` | Trigger and stop sound playback | x | x | x |

## Extension-bundled sounds

Extensions can ship their own sounds in the `dist/sounds/` directory. When an extension is installed, its bundled sounds are registered in the account's sound library and can be referenced in config fields of type `sound`.

The `lumio deploy` command automatically detects audio files placed in `dist/sounds/` and includes them in the upload. Bundled sounds are scoped to the extension install - uninstalling the extension removes its sounds from the library.

### Bundled sound behavior

- Bundled sounds appear alongside user-uploaded sounds in the Sounds Panel (the overlay/widget-editor panel at `apps/web/src/components/editor/sounds-panel.tsx`; there is no standalone `/dashboard/sounds` page)
- Users **cannot delete or rename** bundled sounds - they are controlled by the extension developer
- Bundled sounds **do not count** against the account's plan sound limit or storage total (the limit CTE filters on `source_extension_id IS NULL`)
- The Sounds Panel shows an extension badge (`source_extension_name`) on bundled sounds and provides a filter dropdown with *All* / *Uploaded* / one entry per contributing extension
- Installing or uninstalling an extension broadcasts a `sound:list:updated` event for live sync in the editor

### Sound limits for extensions

Each extension has a configurable limit on how many sounds it can bundle. The limit resolves in priority order:

1. **Per-extension override** - set by admin on the extension itself (`extensions.max_sounds`)
2. **Per-developer override** - set by admin on the developer profile (`developer_limit_overrides` with key `max_sounds_per_extension`)
3. **Platform default** - `DEFAULT_MAX_SOUNDS_PER_EXTENSION = 50` sounds per extension

The resolver returns the source alongside the value (`extension_override` / `developer_override` / `default`), which is what the admin UI shows next to each limit.

Two sibling per-extension limits resolve the same way, with the same three-level priority: `max_sound_file_size` (default 10 MB) and `max_sound_storage_bytes` (default 200 MB). A `max_sounds_per_extension` override is capped at 500.

System extensions install with `skip_limits = true`, so none of the three limits is resolved or applied to them. For a regular extension that declares more sounds than its resolved count limit, the install logs a warning and truncates the list rather than failing.

The `lumio deploy` CLI checks the resolved limit before uploading. The server validates the count again during the upload and at install time (defense in depth).

### Declaring sounds in `lumio.config.json`

```json
{
  "sounds": [
    { "file": "alert.mp3", "name": "Alert" },
    { "file": "chime.wav", "name": "Chime", "default_volume": 0.8 }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | string | yes | Relative path in `dist/sounds/`. 1-255 characters. |
| `name` | string | yes | Display name. 1-255 characters. |
| `default_volume` | number | no | Default volume (0.0-1.0). |

Supported formats: MP3, WAV, OGG, WebM, M4A, AAC, FLAC.

### Referencing sounds in config

Use a config field of type `sound` to let users pick from the sound library:

```json
{
  "config_schema": [
    {
      "key": "alertSound",
      "type": "sound",
      "label": "Alert sound"
    }
  ]
}
```

The SchemaEditor renders a dropdown picker listing all sounds in the account's library (including extension-bundled sounds). The stored value is a sound ID (UUID string).

## API

### GraphQL

| Operation | Guards | Description |
|-----------|--------|-------------|
| `sounds(offset: Int! = 0, limit: Int! = 20, search: String): SoundsResult!` | `feature:sounds` + `sounds:read` | List sounds with pagination and search. Returns the rows **plus** the resolved plan limits (`totalCount`, `userSoundCount`, `maxSounds`, `maxSoundFileSize`, `maxSoundStorageBytes`, `usedStorageBytes`). |
| `sound(id: UUID!): SoundGql` | `feature:sounds` + `sounds:read` | Get a single sound |
| `updateSound(id: UUID!, input: UpdateSoundInput!): SoundGql` | `feature:sounds` + `sounds:edit` | Update name, duration and waveform |
| `deleteSound(id: UUID!): Boolean!` | `feature:sounds` + `sounds:delete` | Delete a sound |
| `playSound(id: UUID!, volume: Float! = 1.0, target: SoundTargetInput): Boolean!` | `feature:sounds` + `sounds:play` | Trigger playback |
| `stopSound(id: UUID!, target: SoundTargetInput): Boolean!` | `feature:sounds` + `sounds:play` | Stop playback |

`SoundGql` fields: `id`, `accountId`, `name`, `filename`, `contentType`, `sizeBytes`, `durationMs`, `waveform`, `createdAt`, `sourceExtensionName`.

There is no GraphQL upload mutation - creating a sound is REST-only because the payload is multipart.

See [GraphQL](../api-reference/graphql.md#sounds) for the full schema.

### REST

| Method | Path | Guards | Description |
|--------|------|--------|-------------|
| `GET` | `/v1/sounds` | `feature:sounds` + `sounds:read` | List sounds (`offset`, `limit`, `search` query params) |
| `GET` | `/v1/sounds/{id}` | `feature:sounds` + `sounds:read` | Get single sound |
| `POST` | `/v1/sounds` | `feature:sounds` + `sounds:create` | Upload sound (multipart: `file` required, `name` optional - defaults to the filename without its extension) |
| `PATCH` | `/v1/sounds/{id}` | `feature:sounds` + `sounds:edit` | Update metadata |
| `DELETE` | `/v1/sounds/{id}` | `feature:sounds` + `sounds:delete` | Delete sound. Returns `204`. |
| `POST` | `/v1/sounds/{id}/play` | `feature:sounds` + `sounds:play` | Trigger playback (body: `volume`, `target`) |
| `POST` | `/v1/sounds/{id}/stop` | `feature:sounds` + `sounds:play` | Stop playback (body: `target`) |
| `GET` | `/v1/sounds/{id}/stream` | account ownership only | Stream audio bytes |

`GET /v1/sounds/{id}/stream` deliberately carries **no** RBAC check: it has to be readable by Widget and Overlay tokens, which hold no account-level permissions. Access is bounded by the query itself, which filters on the caller's `account_id`. Because the payload is account-scoped and carries no `Vary`, responses are served with `Cache-Control: private, max-age=86400, immutable` - cacheable long-term in the caller's own browser, but never in a shared/CDN cache that could serve one account's sound to another.

REST payloads are snake_case (`account_id`, `content_type`, `size_bytes`, `duration_ms`, `source_extension_name`, `total_count`, `user_sound_count`, `max_sounds`, `used_storage_bytes`).

These routes are registered under `/v1` but carry no `utoipa::path` annotations, so they are not present in `apps/api/openapi.json` - the table above is the contract.

### WebSocket

Subscribe to `sounds:{accountId}` to receive real-time playback commands. The gate is `ChannelGate::AccountScoped` plus the `feature:sounds` flag (`channel_gate_for` / `channel_feature_for` in `crates/lo-websocket/src/gate.rs`) - **not** a `sounds:read` permission check. Account-scoping rather than RBAC is what lets a Widget or Overlay token subscribe, while still confining every identity to its own account's channel.

See [WebSocket](../api-reference/websocket.md) for the channel protocol.

## Key files

| Path | Description |
|------|-------------|
| `apps/api/src/routes/sounds.rs` | REST endpoints (list, get, upload, update, delete, play, stop, stream) |
| `apps/api/src/graphql/sounds.rs` | GraphQL queries and mutations |
| `apps/api/src/db/sounds.rs` | Database operations, `get_resolved_sound_limits` |
| `apps/api/src/services/bundled_sounds.rs` | Provisioning of extension-bundled sounds at install time |
| `apps/api/src/db/developer_extensions.rs` | `resolve_max_sounds` and the per-extension sound-limit defaults |
| `crates/lo-websocket/src/gate.rs` | `sounds` channel gate (`AccountScoped`) + `feature:sounds` |
| `apps/web/src/components/editor/sounds-panel.tsx` | Sounds Panel (library, filter, playback) |
| `apps/web/src/components/editor/sound-upload-modal.tsx` | Upload dialog |
| `apps/web/src/components/sound-select.tsx` | `sound`-type config-field picker |
| `apps/api/migrations/20260528000007_sounds.up.sql` | Schema migration + plan/account limit columns |

---

## Features / Stream History

Source: https://docs.lumio.vision/features/stream-history

# Stream History

## Overview

Stream History records every stream **session** - a run that can span several
simultaneous platform broadcasts ("multistream") - and turns the raw event and
chat data already collected in TimescaleDB into per-session **reports**: viewer
curves, follower/subscriber growth, chat, emote and GIF totals, donations, and a
per-platform breakdown.

The feature is platform-neutral by design: Twitch, YouTube and Kick each start
and end sessions from their live status, and adding a new platform never
changes the schema or the API. Core metrics are fixed fields;
anything platform-specific rides in a `platform_metrics` JSON object with
namespaced keys.

Stream History is gated behind the `feature:stream_history` feature flag
(enabled for the Free and Pro plans) and the specific `history:read`, `history:share`, `history:export`, `history:delete`, `history:revenue-read`, `history:revenue-edit` and `history:keywords-edit` permissions.

## Session list & filtering

`channelHistory` / `GET /v1/history` returns paged sessions with combinable date, platform, category, type, and title filters, plus server-side sorting. `channelHistoryFilterOptions` supplies the platform and category choices. The dashboard keeps its filter, sort, and page state in the URL, shows monthly groups, a table on desktop and cards on phones, and preserves the query when returning from a report. A live session refreshes in place after each 60-second sample. Its running peak and average viewers, duration, messages, followers, paid and gifted Subs, chatters, platform figures and top lists come from a read-time overlay; unavailable values are explicitly marked unknown. YouTube subscriber gain is available after the stream ends.

`channelHistoryOverview` / `GET /v1/history/overview` returns totals, platform counts, month summaries, and activity days. Month/day grouping uses an IANA `timeZone` / `time_zone` (UTC by default); a session belongs to the local day it started. `days` covers today and the preceding 370 days, regardless of `from`/`to`, while respecting the other filters. A blank zone means UTC; an invalid one returns a bad request. The dashboard turns these days into an accessible activity calendar with a day tooltip and click-to-filter action. The overview revenue total and monthly revenue require `history:revenue-read`.

For dashboard metrics, pass `range: "today" | "7d" | "30d"` (REST `range=`). It fills `range` (local `from`/`to` and preceding-window bounds), `current`, `previous`, and a zero-filled daily `kpiSeries`. The KPI figures are sessions, duration, time-weighted average viewers, new followers, messages, paid Subs/Members and gifted Subs. The existing totals and estimated revenue then cover the selected window; the 371-day calendar `days` still covers its full span. `range` cannot be combined with `from` or `to` (400 on both protocols). Empty windows return zero figures rather than undefined growth.

`latestSession` / `latest_session` is the account's newest session even when other overview filters are set. It carries the session summary, up to 60 viewer-curve points per platform, the combined curve `viewerTotal` / `viewer_total` on the same bucket times (per bucket the highest per-minute sum across the selected platforms, not the sum of the per-platform bucket maxima), its persisted milestones, and `live` totals from the latest sampler probes. `live` is `null` before the first probe. GraphQL computes `latestSession` only when selected; REST includes `latest_session` in the overview. The dashboard reads the selected range again after a `history:session_sampled` WebSocket event instead of polling.

**Platform filter.** `platforms` / `platforms=` (`twitch`, `youtube`, `kick`) filters the list, the overview and the milestones by platform. The start page uses it for one platform switch that applies to every KPI, trend line, the timeline and the calendar. The list keeps sessions that include a selected platform. The overview counts only the selected platforms' **share** of each session. A multistream on Twitch and YouTube with only YouTube selected therefore counts YouTube's stream time, viewers, followers, messages and Subs/Members, not Twitch's. Stream time is the time a selected platform was live. Ø viewers weight each platform's average by its live time, and concurrent platforms add up. The peak is the sum of the selected platforms' peaks. The counters come from the per-platform breakdown. A session whose every platform is selected keeps its own values, so selecting everything equals no filter. The estimated revenue still covers whole sessions. `latestSession` follows the selection: it is the newest session with a selected platform, and its viewer curve, live totals and follower marks cover only those platforms. Follower-mark milestones are filtered by platform, while viewer, Sub and raid records stay. Each session can also carry `platformStats` / `platform_stats`: its per-platform card figures (stream time, peak and Ø viewers, followers, messages, Subs/Members, gifted Subs). Combining `platforms` with `platform`, or naming an unknown platform, returns a bad request on both protocols.

The sampled live totals keep gifted Subs, Bits, KICKs, Super Chats, Super Stickers and StreamElements tips separate. Money counters include a count, cents per currency, unknown-currency cents, and a converted total in the requested display currency. `convertedCents` is `null` if any part lacks a currency or ECB rate. Tips are session-wide and must not be added once per platform. Chat messages per minute come from the difference between the two newest probes. An already-running session starts these counters when sampling begins; older samples have `liveCounters: null`.

## Milestones

`channelHistoryMilestones(from, to)` / `GET /v1/history/milestones` reads persisted milestones with `history:read`, up to 1,000. `from` includes its instant; `to` excludes it. Each milestone has an id, session id, kind, platform (for follower marks), value, previous value and achievement time (the session start). The four kinds are `viewer_record`, `sub_record`, `biggest_raid` and `follower_mark`. A record needs an earlier value to beat; equal values do not qualify. Follower marks need a previous recorded follower count for that platform, so they start only after two finalized streams with such counts. Milestones are computed when a session is finalized. Sessions finalized before milestones existed are computed once in the background after the API starts, so viewer records, Sub/Member records and biggest raids cover the whole history. For those older sessions a session with exactly one raid counts with that raid's size; a session with several raids has no known largest raid and is skipped. Older streams have no stored follower count, so they get no follower marks. `channel_history.milestones_computed_at` marks a computed session; the background run handles only finalized sessions without it, one API replica at a time and in batches. A second run changes nothing, and a failed session is tried again at the next start. The session report always includes milestones; a session list includes them when GraphQL selects the field or REST requests `include=milestones`. They are deleted with the session or account.

`viewerSparkline` / `viewer_sparkline` has at most 32 combined-viewer points per session. GraphQL computes it only when the list query selects it; REST uses `include=sparkline`. The dashboard's **Viewer trend** column draws a line and filled area, marks the peak, and marks the latest point in red while a stream is live. The list can also request revenue with `include=revenue`; values are omitted on REST and `null` on GraphQL without `history:revenue-read`. Raw samples are used when available, with a 5-minute rollup fallback for older sessions. The filtered list exports through REST `GET /v1/history/export` as CSV or JSON (up to 5,000 sessions); CSV contains `streams.csv`, `months.csv`, and `totals.csv`. Its menu identifies the selected currency and each stream day's ECB rate, or notes that revenue is omitted without permission. Streamer Mode warns when the download contains amounts. This binary download has no GraphQL operation.

## Permissions

| Permission | Grants |
|-----------|--------|
| `history:read` | Session list, overview, reports and time-series stats |
| `history:share` | Create, extend and revoke share links |
| `history:export` | Export a filtered list or a finalized report |
| `history:delete` | Delete a stored session |
| `history:revenue-read` | Read revenue, including YouTube Analytics values where available, converted amounts and assumptions; optionally include the Lumio estimate in a share link |
| `history:revenue-edit` | Replace revenue assumptions |
| `history:keywords-edit` | Add, change and remove the account's tracked keywords; `history:read` permits reading and pattern tests |

Owner and Administrator hold all seven by default. Moderator holds `history:read` and `history:export`.

## Reports

A report joins session aggregates, per-platform stream rows, 60-second viewer samples, chart markers, and frozen top lists. Its headline KPIs, platform comparison, moments, three charts on one time grid (each chart's crosshair and tooltip show only while you hover that chart), stream table, and chatter/emote/GIF panels adapt to screen width. Twitch ad breaks appear on the viewer chart and in an ad card. `adBreaks` / `ad_breaks` gives each break's time, duration, automatic flag and viewer counts; `adStats` / `ad_stats` gives counts, time, impressions, threshold and viewer-change estimates. Kick and YouTube do not supply ad breaks here.

**Terminology follows the metric scope.** Twitch and Kick call these Followers and Subs; YouTube calls them Subscribers and Members. A mixed aggregate reads **Followers & Subscribers** and **Subs & Members**. The German paid term is **Subs**, never **Abo**; rounded YouTube subscriber figures carry `≈`. Twitch tier counts remain separate from YouTube members. See [Platform adapters](../developer-guide/stream-history-platforms.md).

### Shared Chat and chart markers

A Twitch stream row carries `shared_chat_sources` when the broadcast had a Shared Chat, and `null` otherwise. Each partner has its channel identity, message count, peak and average viewers, and `active_from` / `active_to`. For sessions with transition events, those boundaries are exact event times; a channel that returns has multiple spans in `shared_chat_timeline`. The timeline is derived from events while live and frozen with the report at finalization, so it survives event-log retention. Older streams without transition events use minute samples as an approximate fallback (± one minute). Each 60-second sample carries `shared_viewers` (the sum of own and partner counts) and `shared_chat_viewers` with partner counts and cumulative messages. A missing partner was not in that bucket; a null viewer count means the partner was present but not live. These are channel-level aggregates, never viewer identities.

Events from a Shared Chat partner channel never count toward your history. That includes Bits cheered in a partner's chat, partner subs, resubs, gift subs and raids. They appear in your event feed, labelled with the partner channel, but are marked `is_shared_chat`. The live report, the finalizer and every boot backfill skip them. Partner events therefore never reach `platform_metrics.twitch.bits`, the sub and gift counters, the report's KPI strip or the estimated Bits revenue. Only your own `channel.cheer` Bits count.

Each stream row also has `tags` (the tags at stream end) and `category_changes` / `title_changes` (`at` plus the value; the first entry is the state at stream start). Twitch and Kick fill them; YouTube returns empty lists. The report shows the tags as chips and, when the category changed during the stream, a category timeline under the stream row. Title changes are in the API and the JSON export only. Top chatter names and avatars, emote images, and GIF thumbnails are frozen when a session finalizes; a report keeps the fields and number of entries it was finalized with. The UI can render up to 20 top emotes; a report frozen with 10 stays at 10. Each top emote carries `emote`, `provider`, `url`, `count` and, for the hover card, the provider `id`, `animated`, `owner_id` and `platform` (the chat platform it was used on most; a tie goes to the alphabetically first). Emotes with the same name and provider but different ids are separate entries; the same 7TV, BTTV or FFZ emote used on several platforms is one entry. Reports frozen before these fields were added omit them. Top emote and top GIF tiles open the [emote card](./emotes.md#in-stream-reports) on the dashboard and on a shared report; on a shared report the card makes no server requests and shows only the frozen fields. Top GIFs use 9 slots in a 3 × 3 grid, and top chatters use 10.

The session list can mark a Shared Chat session: `sharedChat` / `shared_chat` (GraphQL when selected, REST `include=shared_chat`) lists every channel of the session's Shared Chats, host first, then your own channel, then join order, and says whether a Shared Chat is running in the live session. Finalized sessions read the frozen timeline; a session that is live or not finalized yet derives it from transition events. Sessions stored before the timeline list only the partner channels. The **Shared Chat** filter accepts **All / With / Without** (`sharedChat: WITH | WITHOUT` or `?shared_chat=with|without`) and applies to list, overview, trend, heatmap, export and dashboard start. It appears when Twitch history exists. A live session matches **With** from its begin event. The list row puts a three-avatar host-first marker beside its existing Twitch icon.

The report and Dashboard **This stream** card offer **My channel** (default) and **Whole session** for Shared Chat sessions. My channel's chat figures use only messages from the own room; its viewer figure is the own Twitch Helix count. Whole session shows **Sum of all channels** plus one channel line in host → own → partner order; a partner who left keeps its past line, with gaps rather than zeros where no count exists. The report marks joins and leaves on the chart's time axis and shows a Shared Chat session card with partner values once. Its stream-table row keeps a one-line sum. Revenue and support always come only from the own channel, including in Whole session. The selected view is URL state; list tiles, trends and export stay on My channel. A shared report link and the summary email also show only My channel.

`latestSession.sharedChatSeries` / `latest_session.shared_chat_series` supplies the Whole session chart on the same buckets as the normal viewer series. It is null when the session never had Shared Chat, Twitch is excluded, or the raw samples have expired. `LiveSnapshot.sharedChat` gives the live host, participants, partner viewers and messages, sum and session chat rate. The card updates on `history:session_updated` without a reload. Whole session leads the chat cell with session messages and shows the own-channel count below; its Chat/min headline uses `sessionChatPerMin` and shows **—** until a second sample exists. My channel uses the own rate.

### Zuschauerzahlen im Shared Chat

Lumio treats Twitch Helix `viewer_count` as each channel's own count, including during Shared Chat. This has not been confirmed with a live side-by-side measurement. Twitch [describes individual viewership beside unique Shared Viewership](https://blog.twitch.tv/en/2024/12/05/shared-viewership); its current API and EventSub surfaces do not expose the unique metric. **Sum of all channels** adds the channel counts and can count a viewer watching several channels more than once; it is never labelled as Twitch's unique count.

The server computes peak, low and median markers for the viewer chart and net gain and steepest-rise markers for growth charts. A shared time grid gives every chart and KPI trend line the same timestamps. Long sessions are downsampled with LTTB while preserving peaks and troughs.

### Bot messages

Chat bots are left out of the chat figures, so command spam does not inflate them. A message counts as a bot message when any of these holds:

- **Bot badge** — Twitch `bot` or `bot-badge`, Kick `bot`.
- **Known bot** — the curated list of common bots (Nightbot, StreamElements, Moobot, Fossabot, Botrix and others). Twitch and Kick match the login. YouTube has no bot badge and its display names are neither unique nor fixed, so YouTube bots are recognised only by channel ID (`UC…`), from a list that holds only entries verified as the bot's chat account (today Nightbot and Fossabot). A YouTube viewer who merely uses a bot's name is never matched.
- **Your own bot account** — the Twitch or Kick bot account connected under Bot Connections. A YouTube bot connection stores only the channel title, so it is not used.
- **Your channel's bot list** — platform accounts marked under [Channel settings → Bots](../user-guide/channel-settings.md#bots), matched by stable user or channel ID on Twitch, Kick and YouTube.

A broadcaster badge always wins, so a channel that writes through its own account is never counted as a bot. A login that merely contains "bot" is not matched. The chatter list uses the same definition, so a bot there is a bot here.

Bot messages are excluded from total messages, the messages-per-minute series, per-platform message and chatter counts, unique chatters, top chatters, emote and GIF totals, and top emotes and GIFs. Events (follows, subs, gifts, raids, Bits, donations) and viewer counts are unchanged. The filter is always on. `botMessages` / `bot_messages` gives the number of messages left out, including on a shared report. For a live session it is calculated from the retained chat log with the other chat figures. It is `null` when that live calculation is unavailable, and for an older session whose chat log was gone when bot filtering arrived — `null` means unknown, not zero.

A bot that has no bot badge and is not on the curated list, such as a third-party bot that writes through an ordinary account, is counted like a viewer. Lumio does not guess bots from their name.

The per-platform figures add up to the session figures. Unique chatters are counted per platform: nobody can be matched across platforms, so the same person on Twitch and YouTube counts once on each, and the session figure is the sum of the platform figures. Total messages and unique chatters also include chat from a connected platform that was not live during the session; the platform comparison lists only the platforms that streamed, so in that case its sum is lower than the session figure.

Sessions finalized before bot filtering are corrected once at API start while their chat log is still complete. Their counts, top lists, per-platform figures and stored per-minute samples only ever go down, and `bot_messages` is filled in. Marking an account bot also starts a background recalculation of retained sessions with complete chat logs. A session whose log the chat retention already removed, even in part, keeps its original figures. Removing a mark does not restore figures already recalculated.

### AutoMod log

The report's **Chat insights** card has a private AutoMod tab for Twitch sessions when the reader has both `history:read` and `chat:automod-read`. `automodLog` / `GET /v1/history/reports/{id}/automod` reads held messages from `platform_automod_messages` for that session, with per-outcome counts and cursor pagination. The tab shows hold time, sender, flagged text, reason, outcome, moderator and decision source, and waiting time. It filters by open, allowed, denied or expired and sorts by hold time. It is not in the finalized report, shared reports, exports or popouts; sessions without a Twitch broadcast or outside chat retention have no log. Held messages never contribute to chat insights counts until Twitch publishes an allowed message as a new chat message.

Each entry, its text, flagged spans and blocked-term text included, is deleted once `held_at` is older than the account's chat plan window (Free 365 d, Pro 1,095 d, an `account_limits` override wins, at most 1,095 d), for every outcome. A message above the 4 KiB storage cap has no stored text (`text_state: not_stored`). The tab renders Twitch emotes and Cheers (cheer art from the channel's cheermote catalog at read time, with the amount) and matches 7TV, BTTV and FFZ emotes by word from the connected channels' emote sets. Its sender cell shows the avatar Lumio knew at hold time and the name, or initials without an avatar; it does not show badges. The channel's instructed erasure of a participant deletes their rows in that channel; holds after it are new channel data and are stored. A Lumio-level objection does not touch the log (it belongs to the channel), so an objecting participant is logged like anyone else, and disconnecting Twitch keeps the rows. See [Data & Privacy](../user-guide/privacy-and-export.md).

### Links and commands

The Chat insights card also has **Announcements** and **Pins** tabs. A Twitch
announcement carries its colour, time, author (avatar, name, bot flag) and
optional Shared Chat source. A pin records its platform, sender and moderator
(avatar, name, bot flag), planned duration, changes, actual duration and end
reason: `expired`, `unpinned`, `replaced`, `message_deleted`, `stream_end`,
`ran_past_stream_end`, `unknown` or `active`. A Twitch removal observed by
polling shows **≈** for its approximate time. The actual duration uses the
chat's pin wording: seconds or minutes under an hour, hours and minutes from one
hour, days and hours from one day, rounded down. The report contains up to 500
announcements and 200 pins and marks a truncated list. A session begun before
capture started says **Not captured for this stream**, even if it ended after
capture began.

Neither tab freezes message text in the report. It shows text while the chat
message is stored; pin text can also come from the retained channel pin event.
When no retained source has text, the row says **Text no longer stored**. The
same rule applies to a public share and an export. An instructed erasure masks
the person in these lists of that channel's reports and removes their message
reference from the frozen report; an objection does not touch them (it acts on
Lumio Stats only). The pin events themselves are channel-owned and stay in
`platform_event_logs` after a viewer's support-tool erasure.

Share links can include `announcements` and `pins` as separate sections,
both off by default and in the group that exposes viewer names. Exports carry
these sections in JSON, PDF and TXT; a CSV report ZIP includes
`announcements.csv` and `pins.csv` when the lists are present. PDF and TXT
word pin durations like the dashboard (minutes, hours or days); `pins.csv`
keeps the seconds and adds a worded `duration` column. Announcements
participate in ordinary chat message totals, chatter counts, commands and
keyword insights.

A report lists the links posted in chat and the chat commands viewers used during the session, in the same time window as the other chat figures. `links` and `commands` are on the report in GraphQL and REST and in the JSON export.

**Links.** A link is an `http://` or `https://` URL, a `www.` address, or a bare `host.tld/path` whose top-level domain is on a short list of common ones (`.com`, `.gg`, `.tv`, `.de` and others). That keeps chat noise such as `lol.xd`, `v1.2` or `z.B.` out. Trailing punctuation and a closing bracket the link did not open are stripped, and e-mail addresses are ignored. Variants of the same link are merged into one entry. To compare them, the scheme and host are lower-cased, `www.` is dropped, tracking parameters (`utm_*`, `fbclid`, `gclid`, `si`) are removed and a trailing slash is ignored; the path keeps its case. `url` is that normalized form, `display` the link as it was first posted, and `domain` the host. A link posted twice in one message counts once. Bots are **included and flagged** here: a bot posting the Discord link forty times is useful to see, so every poster and occurrence carries `is_bot`, using the [bot definition](#bot-messages) above.

**Commands.** A command is a message whose text starts with a command prefix followed by a name that starts with a letter, up to 32 characters of letters, digits, `_` and `-` (`[A-Za-z][A-Za-z0-9_-]{0,31}`), and then a space or the end of the message. The prefixes come from the API setting `[history] command_prefixes`; the defaults are `!` and `#` (see [Installation](../getting-started/installation.md)). The setting must include the prefix of Lumio's own chat bots. With a multi-character prefix, the longest match wins. The prefix is part of the entry, so `!discord` and `#discord` are two entries, and a hashtag at the start of a message counts as a `#` command. `!`, `!!!`, `#1`, `#2024` and a `!` in the middle of a message are not commands. The rest of the message, trimmed and cut to 100 characters, is the command's argument text. Commands are what **viewers** type, so messages from bots are left out entirely: they are not counted and appear neither as posters nor as occurrences. `known` says whether the name, without its prefix, is an enabled Lumio bot command of the account or a global one on a platform where it was used. It is information only and does not change the counts.

**Keywords.** The account's [tracked list](../user-guide/channel-settings.md#keywords) forms a third Chat insights tab. Each of its at most 50 entries has a row, including entries with zero hits. Whole-word, contains and regex matching count a keyword once per message, anywhere in its text. Bot messages are included and flagged, as for links. A leading token that matches a keyword, such as `#ad`, counts as a keyword and not as a command. Each row also has `bot_count`, `unique_users`, first/last time, top posters and the first 100 occurrences. Changing the list recounts finalized sessions in the background while their full chat log remains; sessions without it keep their frozen keyword figures. A missing frozen list with no complete chat log returns `null` (unknown).

Each entry has `count`, `first_seen_at`, `last_seen_at`, the top 5 `posters` (`platform`, `user_id`, `login`, `display_name`, `count`, `is_bot`) with `other_posters` for the number of further people, and `occurrences`: the first 100 uses, oldest first, each with its time, platform and author. When there were more, `occurrences_truncated` is `true` and `count` holds the full number. A command entry adds `name` (prefix plus lower-cased name), `prefix`, `unique_users`, `top_args` (the 5 most used argument texts, trimmed and lower-cased, `""` = no arguments) and `args` on each occurrence. Each list holds the 50 entries with the highest count.

**Dissolved or deleted channels.** When a channel is dissolved (at once, or at the end of its 7- or 30-day grace period) or deleted by an operator, all of its stream reports are deleted with it: sessions, streams, viewer samples, the viewer curve in both rollups and milestones (founder ruling ZAF-2626). Deleting a single report removes the same rows for that session. Only a finalized report can be deleted: while a session is live, in its grace window or waiting for the finalizer, `deleteChannelHistory` / `DELETE /v1/history/reports/{id}` refuses it with `409` (`This stream session is still live; it can be deleted once it is finalized`), because Lumio still writes samples and rollups for it. Scheduling a dissolution deletes nothing, and a cancelled one keeps the reports. See [Accounts › Account Dissolution Flow](./accounts.md#account-dissolution-flow).

**Erased chatters.** When a channel has a chatter's data erased ([Chat → Erasure](./chat.md#erasure-gdpr-art-17)), their top-chatter entries, posters and occurrences stay in every finalized session of that channel with their counts but without identity: `user_id` is `null`, `login` and the name are empty, the avatar and a command's `args` are removed, and the entry carries `erased: true` (REST: the key appears only on erased entries; GraphQL `erased: Boolean!`). The report, the public share and every export show such an entry as "Deleted user" ("Gelöschter Nutzer" in German), never as an empty name. A later recount works from the chat log, which no longer holds the chatter's messages, so the name does not come back.

**Suppressed chatters (instructed erasure).** Each channel keeps its own suppression list (`account_chatter_suppressions`) of chatters it had erased by name ([Chat → Erasure](./chat.md#erasure-gdpr-art-17)): the instructed erasure of one person in one channel adds them in the same operation, and the entry stays until the account is deleted or the channel withdraws its instruction. Each entry records who initiated the erasure (`initiated_by`): `channel` when the channel initiated it, `subject` when the person asked for it. Only a `channel` entry can be withdrawn; a `subject` entry stays (the withdrawal answers 409), a later `channel` erasure never turns it back into `channel`, and entries recorded before the initiator was stored count as `subject`. A withdrawal (`POST /v1/admin/privacy/chat/erase/withdraw` / GraphQL `withdrawChannelChatterSuppression`, operator-only with `admin:privacy-erase-withdraw`, audit `privacy:channel_suppression_withdrawn`) deletes that channel's entry only: sessions frozen from then on name the chatter again, while names the erasure already blanked and everything it deleted stay gone. Every list of **that channel** built afterwards — the top chatters when a session finalizes or is recounted, links, commands and keywords when they are frozen or recounted, and the lists of a live or unfrozen session built on read — shows a listed chatter the same way as an erased one: the entry and its counts stay, the identity is blanked and `erased: true` is set, so the report shows "Deleted user". On Twitch and Kick, entries without a user id are matched by the logins stored with the list entry. If the list cannot be read, the session is not frozen (the finalizer retries on its next run), and a report built on read shows no links, commands or keywords instead of named ones. Other channels' reports are not affected by it. The global Lumio list (`chatter_suppressions`, which also holds GDPR Art. 21 objections — [Chat → Objection](./chat.md#objection-gdpr-art-21)) acts only on the public Stats leaderboard, never on a channel's report, export or share link ([Public Stats](./public-stats.md)). A share link and its public export show the frozen lists as stored, without a read-time mask: past sessions are cleaned by the channel's instructed erasure, later ones are frozen blanked by the channel's list. Crawled sessions hold no chatter names and are not affected.

Links and commands are frozen when a session finalizes, so they outlive the chat log like the other top lists. A live session, and a session finalized before links and commands existed, builds them from the chat log on read while that log is still complete. Once the chat retention has removed it, even in part, both are `null`, which means unknown, not "none". Frozen links, commands, argument texts and poster names stay with the report after the chat log is deleted, capped as described above.

### Revenue and currency

`estimatedRevenue` / `estimated_revenue` can appear on the report session, list rows, and overview. It is `null` in GraphQL or omitted from REST without `history:revenue-read`. The estimate combines these sources:

| Source | Fixed value or account setting | How a line is priced |
|---|---|---|
| Twitch Tier 1 / 2 / 3 subs and gifts | Fixed USD $4.99 / $9.99 / $24.99 | Count × tier price × editable Twitch share. Prime uses the fixed USD $4.99 Tier 1 value and the same share. An old gift without a recorded tier uses Tier 1 (`assumed_tier_1`). |
| Twitch Bits | Fixed USD $0.01 per Bit | Count × value; no additional share. Shared Chat partner Bits do not count. |
| Kick subs and gifts | Fixed USD $4.99 | Count × value × editable Kick share. |
| Kick KICKs | Fixed USD $0.01 per KICK | Count × value, without a share. The value is a third-party assumption, marked `please_verify` because Kick does not publish it. |
| YouTube memberships and gifts | Account-entered membership levels | Each paid month uses its level price × the membership share. A join and each membership milestone count as a paid month. A name without a matching entered price, or a month without a level name, uses the cheapest entered level and carries `assumed_lowest_level`. Without any entered level, memberships and gifts remain `unpriced`. |
| Twitch and Kick ads | Account-entered CPM, ad share and ad-free viewer share | For each break, viewers at its start × `ceil(duration_seconds / 30)` gives viewer spots. Sum them, remove the ad-free share, then multiply impressions ÷ 1,000 × CPM × ad share. Kick breaks come from the live-only `ad-break-status` poller, not a webhook. |
| YouTube ads | Account-entered CPM, mid-rolls per hour, ad share and ad-free viewer share | Viewer-hours (sampled viewer-minutes ÷ 60) × mid-rolls per hour × (1 − ad-free share) ÷ 1,000 × CPM × ad share. No pre-rolls are counted. The line exists only with a mid-roll rate and viewer samples and carries `estimated_from_midrolls`. |
| YouTube Super Chats and Super Stickers | Amounts reported by YouTube | Each has its own editable creator share (70% by default). These amounts appear under `actuals`; the payout after the share is an estimate. |
| Donations | Amounts reported by StreamElements | Actual gross amounts under `actuals`, before fees. |

The fixed values are read-only USD values in `fixedValues` / `fixed_values`; their source currency is converted at the stream-day ECB rate. CPMs, membership prices and payout currency are account assumptions. An ad break without a CPM still has a line with zero amount and `cpm_missing`; a YouTube stream without a mid-roll rate has no ad line. If a YouTube Analytics `estimatedAdRevenue` value becomes available, it replaces the mid-roll estimate rather than being added to it. Platform settlement, taxes, regional prices and silent renewals can differ from this estimate.

#### YouTube Analytics revenue

For a connected channel in the YouTube Partner Program that granted the optional `yt-analytics-monetary.readonly` scope, the report labels the source **Estimated revenue according to YouTube Analytics**. Its `youtubeAnalytics` / `youtube_analytics` state is `pending` until figures arrive, normally 2–3 days after the stream. While pending, the report labels and shows the **Lumio estimate**. With values it shows `provisional` or `final` and the `fetchedAt` / `fetched_at` date. YouTube may correct provisional values.

The reported lines `youtube_analytics_ads`, `youtube_premium` and `youtube_transactions` represent ads, Premium and a remainder derived from YouTube's reported total. They **replace**, rather than add to, Lumio's YouTube ad estimate, membership and gift estimates, and the Super Chat and Super Sticker amounts in the revenue breakdown. Other platforms and donations keep their own lines. A missing scope (`not_granted`), a channel outside the Partner Program (`not_in_ypp`), or a disabled Analytics API in the account's Google project (`api_disabled`) leaves the Lumio estimate in place and shows a hint only on the revenue area. See [YouTube Analytics API setup](/getting-started/oauth-setup#youtube-analytics-api). Existing connections without the scope receive one dismissible history-list announcement, not a standing connection warning.

`channelHistoryYoutubeRevenueStatus` / `GET /v1/history/youtube-revenue/status` reports the account's connection and Analytics state without amounts under `history:revenue-read` and `feature:stream_history`. Lumio batches due videos into at most **one Analytics revenue request per channel per day**, usually none; the Partner Program check is cached for a week. The requests count against the customer's own Google app quota.

Only account members with `history:revenue-read` can read the Analytics amounts. A share link and its public export **always use the Lumio estimate**, even when the private report uses Analytics; the public path does not load Analytics values or totals derived from them. Private report and list exports can contain YouTube Analytics amounts when permitted. Their menus warn that a downloaded file contains YouTube revenue and is outside Lumio's control afterward.

Stored Analytics rows are deleted when the connection is disconnected, the scope is removed or the grant is revoked, the authorization stays unconfirmed for 30 days, a video no longer exists on YouTube, the account is deleted, or the stream report is deleted (`deleteChannelHistory` / `DELETE /v1/history/reports/{id}`; rows of a video that another report still shows stay). Lumio confirms the authorization daily and the videos' existence every 30 days while rows exist, also when the channel has left the Partner Program or the Analytics API is disabled. While a channel dissolution is scheduled, Lumio fetches nothing: no new videos, Partner Program checks or revenue requests, only the deletion checks keep running. The owner's GDPR data export (**Your channels**) contains the channel's stored rows, fetch schedule and check state as `channels/<channel-id>/youtube_revenue.json`.

When more than one platform has revenue items, the report card offers **All** and tabs for Twitch, YouTube and Kick as applicable. **All** shows a clickable sum row per platform and donations, which have no platform. A platform tab shows its items and a subtotal when the amounts can be summed in one currency; a single-platform report has no tabs. The grand total, currency and assumptions action stay above the tabs, while the display-currency switch sits in the report header. Streamer Mode masks monetary sums and prices. `grandTotal` and `averages` use converted amounts where possible.

`channelHistoryRevenueSettings` / `GET /v1/history/revenue-settings` returns saved assumptions or defaults and the read-only fixed values. `updateChannelHistoryRevenueSettings` / `PUT /v1/history/revenue-settings` writes the editable values with `history:revenue-edit` and emits `account:history_revenue_settings_updated` only when values change. The event names the changed fields (`youtube_member_levels` for any added, removed or repriced level) but not their values, because the audit log is readable with `audit-log:read` alone and the assumptions are behind `history:revenue-read`. YouTube level names seen in retained events are available through `channelHistoryYoutubeMemberLevelSuggestions` / `GET /v1/history/revenue-settings/youtube-member-level-suggestions` under `history:revenue-read`.

The optional `currency` argument on history reads and exports defaults to the user's display currency. A `Money` value carries `amountCents`, `currency`, `sourceAmountCents`, `sourceCurrency`, `rate`, `rateDate`, and `convertible` (snake_case in REST). Conversion uses the ECB reference rate for the stream's UTC start date, falling back to the last rate within seven days. Missing rates leave the source value intact, mark it unconvertible, and exclude it from converted totals and averages. Historical Super Chat and Sticker sums are tracked per currency; old mixed-currency rows remain marked as such.

`displayMoney` / `display_money` on the report session gives the money the report shows in the source currency, converted into the display currency (or the `currency` argument). Its fields are `currency`, `donationsCents`, `superchatsCents`, `superstickersCents` and `rateDate` (snake_case in REST). Each amount sums every currency of its kind, and each part is converted at the stream-date rate as above, so mixed Super Sticker currencies end up as one figure. An amount is `null` when any part has no rate or no known currency, for example old mixed-currency Super Chat totals. A kind with no money is `0`. The source amounts stay unchanged in `donationsTotalCents` / `donationsCurrency` and `platformMetrics` (`donations_by_currency`, `youtube.superchats_amount_by_currency`, `youtube.superstickers_amount_by_currency`). This conversion is not a revenue estimate: it needs only `history:read`, while `estimatedRevenue` stays behind `history:revenue-read`. It adds no data a `history:read` caller cannot already see, only a converted view of it. The session list leaves `displayMoney` `null`. On a shared report the donation and Super Chat/Sticker money stays stripped, so every amount is `null`, and `currency` is the link currency.

### Export

A finalized report exports as PDF, CSV, TXT or JSON. The PDF has up to four A4 pages: Overview, Timeline, Revenue & Ads, and Chat & Streams; empty sections drop out. TXT follows the same sections, CSV adds `revenue.csv` and `ad_breaks.csv`, and JSON keeps machine field names. The Chat & Streams part has **Links**, **Commands** and **Keywords** tables when those lists are present. CSV adds `links.csv`, `commands.csv` and `keywords.csv` with one row per entry, plus `link_posts.csv`, `command_posts.csv` and `keyword_posts.csv` with one row per stored occurrence, times in the export time zone. A public export includes keywords only when the share link includes the `keywords` section. The PDF overview lists donations, Super Chats and Super Stickers in the display currency, or in their source currencies when a rate is missing. CSV `summary.csv` adds `display_currency`, `display_rate_date` and, for donations, Super Chats and Super Stickers, a `*_display_cents` row plus a `*_source` row with the source amounts per currency (`200 EUR + 10000 JPY`). JSON carries `session.display_money` next to the source fields. Exports honor locale, timezone, currency, revenue permission, and public link section choices. CSV text cells that could be interpreted as spreadsheet formulas receive a leading apostrophe; numeric cells remain numeric. A live report returns `409`.

## Stream summary email

When a session is **finalized** (its grace window closes), Lumio sends the
account **owner** a summary of the stream. The email uses the C · Brief layout
with average viewers, peak viewers, and live time as key figures. Viewer figures
show their change from the previous completed stream when one exists. A short
sentence lists follower, subscriber/member, and chat-message counts; gifted
subscriptions, StreamElements tips, Bits, KICKs, Super Chats/Stickers, and raids
appear there when non-zero. The email then shows a transparent viewer-and-chat
chart, a platform table, and a button to the full report. The chart is a single
CID PNG for light and dark layouts, with axes and legend labels as HTML text.
The email does not show the report's peak/median markers or top lists.

The summary is sent only when **all** of these hold:

- the session lasted at least **5 minutes** (test streams are skipped),
- e-mail delivery is enabled for the deployment (`email.enabled`), and
- the owner has not opted out (below).

### Opt-out

The summary reuses the standard notification-preference system under the
`stream_summary` notification type, with four channels: **off**, **in-app only**, **e-mail only**, or **in-app + e-mail** (the default). Owners change it in **Settings → Notifications**. The in-app notification is delivered when the selected channel includes in-app delivery.

## Shareable links

When a link includes revenue, its public report and export show only the Lumio estimate for YouTube, never Analytics values or totals derived from them.

A time-limited share token (`lm_share_*`) opens `/share/history/{token}`. Up to 20 active links per report can have a password and an export toggle. `options` controls the public sections (`chat`, `top_chatters`, `ads`, `revenue`, `links`, `commands`, `keywords`), `include_revenue`, and currency. For new links, chat and ads are on; top chatters, revenue, links, commands and keywords are off. `links`, `commands` and `keywords` show viewer names, and commands show the text viewers wrote, so each has its own switch; a section that is off is `null` on the shared page and absent from its export. A link created without options (every link from before share options existed) shows chat and top chatters, with no ads, revenue, links, commands or keywords. Ad breaks and the ad card are shared only when the creator turned on `ads`, so older links no longer show them. Including revenue requires `history:revenue-read` at link creation, and extending a link that shares revenue requires it too, on GraphQL and REST alike (`403` with `Missing permission: history:revenue-read`). Share-link create, extend and revoke audit events carry the effective options.

The public response includes the permitted report sections, channel display information and expiry. Its viewer, chat and follower charts use the same samples as the owner's report, reduced to the public fields: viewers, messages, followers, subs and the platform counts. The separate live totals (gifted Subs, Bits, KICKs, Super Chats, Super Stickers and tips with their amounts) and every sample amount are left out, even on a link that shares revenue; shared revenue appears only as the estimated-revenue card. The page uses its own header and the standard legal footer. A password prompt exposes no report metadata.

**Images and cookie consent on the shared page.** People who open a share link are not Lumio customers. Channel and chatter avatars (Twitch, Kick, YouTube, Discord), emotes (Twitch, 7TV, BetterTTV, FrankerFaceZ, Kick), badges and Bits / KICKs graphics load through Lumio's [image proxy](../developer-guide/image-proxy.md) (`/img/…` on `lumio.vision`), so the visitor's browser never contacts those servers and the images show without a consent choice. An image the proxy does not cover renders a neutral placeholder: initials instead of an avatar, the emote code as text, the cheer as text. GIPHY GIFs are not proxied: they load only after the visitor allows **Functional** cookies in the cookie-consent banner; until then a **GIF** chip with the caption stands in and the emote/GIF hover card is not mounted. The signed-in dashboard shows the same report with direct image URLs. A locked link falls into one of two classes, each with one fixed response:

- **Unavailable** — a malformed or unknown token, or an expired or revoked link, returns `410` with `SHARE_UNAVAILABLE`. The page shows that the link is no longer available.
- **Password required** — an active link with a password, opened with no password or a wrong one, returns `401` with `SHARE_PASSWORD_REQUIRED`. The page shows the password prompt.

**Rate limiting and password lockout.** The public view and export are rate-limited per end-user IP. A request the web app forwards on a visitor's behalf counts against that visitor's IP, not against the web server. Wrong passwords lock a protected link: after 10 failed attempts on one link, or 20 from one client IP across links, within 15 minutes, every password attempt returns `429` with `RATE_LIMIT_EXCEEDED` until the window ends, including the correct password. Each attempt is counted before its password is checked, so the limit holds for simultaneous requests too, and a refused attempt also counts. A correct password is taken off the count again, so it does not count. An IPv6 client is counted per `/64` network. Expired, revoked and unknown links never reach the password check, so they never count either. Password checks run off the request threads. When the rate limiter's store is unavailable, the public share endpoints return `503` rather than going unthrottled.

Expiry and revocation are checked first, so an expired link never asks for a password. Share tokens are 256-bit random values, so a guessed token gets the same `410` as an expired one and does not reveal whether a link exists. Only someone who already holds a real token learns whether it still works, which is what the page needs to tell them. A missing and a wrong password stay indistinguishable. Neither response carries a title, channel, date or expiry, and the social preview of a locked link is neutral. A public export requires the link's `allow_export` flag and contains only permitted sections. The plaintext token is returned once, at creation; the link list exposes only its prefix.

## Live updates

While a session is live it appears in the list with a live badge, and the
WebSocket `history:{account_id}` channel emits `history:session_started`,
`history:session_updated` and `history:session_ended` events for live refresh.
`channel_gate_for` maps the channel to `ChannelGate::Permission("history:read")`
and `channel_feature_for` to `feature:stream_history`, so both must hold to
subscribe.

## API

GraphQL `POST /v1/gql` is the primary structured read/write surface; [GraphQL](../api-reference/graphql.md#stream-history) lists the queries and mutations. REST mirrors structured operations under `/v1/history` and serves the two file downloads: [REST Stream History](../api-reference/rest-api.md#stream-history). The `history:{account_id}` WebSocket channel emits session started, updated, and ended events behind `history:read` and `feature:stream_history`.

---

## Features / Public Stats

Source: https://docs.lumio.vision/features/public-stats

# Public Stats

## Overview

Public Stats is the per-channel **publicness** layer for the public Stats
app. Channel listing is an **opt-out / public-by-default** model: every channel
is listed unless its broadcaster opts out. The chatter leaderboard is the
exception - it is **opt-in** (hidden until the broadcaster explicitly enables it,
Art. 25(2) privacy-by-default), because it exposes viewer identities. Because the
Stats app indexes non-customer channels too, publicness is keyed by **channel
identity** (`platform` + `platform_channel_id`), not by account.

This backend surface ships two parts: the **opt-out registry** with the
customer-facing dashboard toggle a first-party broadcaster uses to manage their
own channels (see [Managing publicness](#managing-publicness)), and the
**public read model** the Stats app consumes (see
[Public read model](#public-read-model)). The **public app** (`apps/stats`)
renders the public channel and stream pages against that read model (see
[The public app](#the-public-app-channel--stream-pages)). A broadcaster can also
opt out **without a Lumio account** by typing a verified `!optout` in their own
channel's chat - the crawler honours it (broadcaster badge alone) and writes
`opted_out_via = 'crawler_command'`; see the
[crawler developer guide](../developer-guide/public-stats-crawler.md#broadcaster-optout-chat-command).

## The public app (channel & stream pages)

The public Stats app (`apps/stats`, own origin `stats.lumio.vision`) is an
unauthenticated, edge-cacheable Next.js app. It renders public pages against
the read model, server-side (SSR) with no session cookie:

- **`/{channel}`** - channel page: a single **top card** (ZAF-866) that merges
  the channel **identity** - the name, the **Lumio channel** badge (shown when
  `source = first_party`), the Twitch **partner / affiliate** channel-type badge
  after the name when the channel carries one (ZAF-842; absent for none/null and
  non-Twitch platforms), a **LIVE** badge with the current viewer count when the
  channel is streaming right now (ZAF-795), and the handle - with the **About box**
  (bio / social links / team) as the card's lower region. When a Twitch channel's
  display name is a *localized* (non-Latin) name that differs from its login - e.g.
  `こさむん` whose login is `kosamun` - the name renders as `こさむん (kosamun)` so the
  handle stays visible; ordinary case-variant names (`Cruex` / `cruex`) render the
  name alone, and a separate `@login` line is shown only when the login adds
  information the name line does not already carry. The same rule applies to the
  ranking / search lists and the personal watchlist. Each About sub-field is
  independently optional; when bio, links and team are all absent the card
  collapses to the identity block (never an empty About shell). Directly beneath
  the card a **content submenu** (tab bar) switches the page body between four
  tabs, all rendered server-side and streamed in the same payload (the page stays
  fully edge-cacheable - the client only toggles which tab is mounted):
    - **General** - aggregate headline tiles (stream count, watchtime, peak/avg
      viewers, followers/subscribers, total messages, last streamed) and the
      link to the separate change-history page.
    - **Streams** - the recent-streams list linking to each stream page.
    - **Placements** (badged **Beta**) - for Twitch channels that carry them, the
      **ad-marked panels** the broadcaster **marked as advertising** ("als Werbung
      gekennzeichnet"), grouped **per panel** (not one entry per artwork version),
      each showing its title, current image, description and link. Removed panels
      and earlier artwork versions appear on `/{channel}/history` (`noindex,
      follow`), not on the indexable channel page. The tab reads the per-panel
      data via `publicChannelPanelHistory` (see below). The heading and
      disclaimer state these are broadcaster *self-declared* markings that Lumio
      does not verify - never asserted as fact. Panel artwork loads through the
      Stats [image proxy](../developer-guide/image-proxy.md) (`/img/ttvpanel/…`), so the
      visitor's browser never contacts the Twitch CDN. A channel with no
      ad-marked panels shows a muted empty state. **Ad-detection over chat**
      (matching chat links/keywords against panels) remains a separate track,
      pending a founder ruling.
    - **Stats** (badged **Beta**) - a **follower-growth** line chart and an
      **average-viewers-over-time** line chart, each with a selectable
      30 / 90 / 180 / 365-day range (ZAF-891). The dated channel-scope series come
      from the `publicChannelTrends` read model; the page fetches the widest
      window server-side once and the range selector slices shorter windows
      client-side, so it stays edge-cacheable. A channel with no history in the
      window renders an honest "not enough history" empty state rather than a
      fabricated chart.
- **`/{channel}/stream/{broadcastId}`** - stream page: the viewer-curve chart,
  duration, peak/avg viewers, message and unique-chatter counts, emote count,
  new-follower count, **de-identified** subscription and gifted-sub counts, the
  top-emotes list, the **GIF count** (shown ungated like the emote count - it is a
  plain number, not a third-party fetch) and the **Top GIFs** (ZAF-968 - which
  GIFs appeared in the public chat and how often; a content datum kept for **90
  days** then auto-deleted). The Top-GIFs **images** load from GIPHY only after
  the visitor grants the **Functional** consent category (ZAF-969/970); without
  that consent the card lists the most frequent GIFs **by name/id + count as
  text** and fires **no** request to GIPHY,
  and - **only when the broadcaster opted the leaderboard in**
  (`show_top_chatters`) - the per-channel chatter leaderboard. For
  `source = external_crawler` streams the follower / subscription / gifted-sub
  tiles render **"—" ("not collected")** rather than `0`: under Regime B
  (ZAF-633) the crawler keeps aggregates only and never captures
  follower/sub/gift events, so those fields are legitimately unavailable, not
  zero (viewer, message, unique-chatter, emote and GIF counts *are* crawled and
  show real numbers). When a stream ran in a Twitch **Shared Chat** session, the stream
  summary's `shared_chat_sources` names the **source channels** whose chat appeared
  in the room (ZAF-819), and the stream page renders a **Shared Chat** indicator —
  a card with a Twitch icon, overlapping channel avatars and a per-channel list
  of "who these stats are coming from" with each source channel's shared-chat
  message count (ZAF-867), matching the live-chat Shared Chat styling. A stream
  with session events also shows the host and a compact start/join/leave/end
  timeline; crawled streams without EventSub session events retain the partner
  list. The public timeline contains channel identity and participation times,
  **no viewer counts**. Session avatars are round, host first with a crown; the
  images load through the image proxy, and initials keep the order where there is none.
  Each entry
  carries the source channel's `display_name` + `avatar_url` (ZAF-868, resolved from
  the crawler channel-profile store, falling back to the channel id when
  uncaptured). The channel page's recent-streams list marks each shared-chat
  broadcast with the same **Shared Chat** badge. Those shared-chat messages are
  attributed to their source channel, **not** folded into the host's message /
  unique-chatter counts (attribution by channel, never by viewer - aggregates only).
  The stream page also renders a **stream-metadata change timeline** card
  (ZAF-890) - the broadcast's title / category / tag changes old→new, most-recent
  first, mirroring the channel history page's About-box change-history card (title and
  category as text diffs, tags as chips with added tags emphasised and removed
  tags struck through). It renders nothing when the stream is opted out or has no
  recorded metadata changes. See
  [Stream-metadata change history](#stream-metadata-change-history-zaf-890) below.

It also renders the cross-channel **browse** surfaces over the Form-B read model
(see [Cross-channel browse & search](#cross-channel-browse--search-form-b) below
for the protocol and field set):

- **`/rankings/{metric}`** - the top-bar metric nav. One route per ranking, each
  its own edge-cacheable URL: `watchtime`, `viewers`, `follower-gain`, `peak`, and
  `live` (live channels, most-recent first). A tab bar switches metric; a
  platform filter and a **Live only** toggle refine the list; a `?category=`
  filter (arriving from a Games card) scopes it to one game. Bare `/rankings`
  redirects to `/rankings/watchtime`; an unknown metric is a clean 404.
- **`/games`** - the Games directory: distinct categories with per-category
  channel / stream / peak-viewer / watchtime aggregates and a live-stream count.
  Each card drills into `/rankings/watchtime?category=…` for that game.
- **`/search`** - channel search: a debounced box driving `?search=`, matching on
  handle + display name across every opted-in channel (results reuse the ranking
  list in Watchtime order). Empty query shows a prompt, not an unbounded dump; the
  top-bar search field submits here as a plain GET form (no client JS needed).
- **`/partners`** - the Partners directory over the
  [cross-channel placements read model](#cross-channel-placements---advertisers-zaf-1578):
  one card per advertiser (link host) with its channel and placement counts, the
  last-seen date and the channels carrying it, sortable by **Most channels** or
  **Recently seen** (`?sort=recent`) and keyset-paginated (`?after=`). A card
  drills into `/partners?domain=…`, which lists that advertiser's placements
  across channels - channel (linking to its Stats page), panel title, artwork and
  outbound link. Artwork and avatars load through the image proxy exactly like the
  per-channel Placements tab. Twitch only, since only Twitch panels are captured.

The left sidebar links Home, Emotes, Games, Search and Partners. **Events** is
listed as a non-interactive **Soon** entry until its surface exists.

The founder's separate **Followers** (absolute total) tab is intentionally not
shipped: the Form-B read model exposes no non-account-keyed follower total, so it
is deferred to the crawler follower-capture work - **Follower Gain** is the
shipped follower ranking. Every browse route is cookieless, server-rendered, and
carries all filter/page state in the URL, so each combination is its own cacheable
URL; when the read model is unavailable the page shows a calm unavailable state.

**Field discipline (§5 visibility matrix).** The pages render only what the read
model exposes, which is the §5 *public* column: donations, raw platform metrics,
and subscriber / gifter identities are **not modelled** server-side and can never
reach the page. Subscription and gift data appear as **de-identified counts
only**.

**Platform resolution.** The read model is keyed by `(platform, channel)`. The
`/{channel}` URL takes the platform from an optional `?platform=` query param and
defaults to `twitch`; stream links carry the resolved platform forward.

**Localization.** The app is bilingual (English + German) but **carries no locale
in the path** - there is no `/de/` or `/en/` prefix for any locale, and
`/{channel}` / `/{channel}/stream/{broadcastId}` are the only public paths. The
active language is resolved exactly like the main webapp: from the functional
`locale` cookie (the visitor's remembered choice), falling back to the browser's
`Accept-Language` for a first-time visitor, then English. The language switcher
writes that cookie server-side and re-renders the page - the choice is remembered
across visits without ever changing the URL.

**Empty & opt-out states.** A channel or stream that is opted out (or unknown)
resolves to GraphQL `null` / REST `404` and the app renders a clean **not-found**
page - never a crash, and never a partial payload with hidden fields. Sections
with no data yet (e.g. a crawled channel not yet covered by chat capture) render a
calm empty state rather than disappearing or erroring.

Stats for **non-connected (foreign) channels** are gathered by the
[Public Stats Crawler](../developer-guide/public-stats-crawler.md), which writes
`source = 'external_crawler'` rows into the same `channel_history*` tables. Those
rows carry no Lumio "connected channel" badge and, until a channel is
verified-claimed, hold only non-personal aggregates (no per-username data).

## Signed-in layer: Watchlist

The Stats app is public first, but a thin **authenticated layer** sits on top of
it: **Sign In / Connect your Lumio ID account** and a personal **Watchlist**
(favourite-streamer tracking). The public/authenticated split is **per-function,
not per-page** - every page stays publicly reachable, and only individual
controls (the Watchlist star, the personal Watchlist view) require a signed-in
Lumio ID. This keeps the public origin cookieless and edge-cacheable.

**Sign in.** Stats has **no auth mechanism of its own**. Login reuses the central
[Lumio ID app](../getting-started/oauth-setup.md) (NextAuth) exactly like the web
and admin apps: the Sign-In control redirects to `id.lumio.vision/login` with a
`redirect_uri` back to Stats, and after login the shared `lumio-token` session
cookie (set on the `.lumio.vision` domain) is read by the Stats proxy routes. No
popout / overlay tokens are involved.

**Cacheability is preserved.** The public `/{channel}` and stream pages are still
rendered server-side with **no session read** - the signed-in chrome (avatar
menu, Watchlist state) is resolved **client-side after hydration** via dedicated
dynamic proxy routes, so the cached SSR HTML is identical for every visitor:

| Route | Method | Purpose |
|-------|--------|---------|
| `/api/session` | `GET` | Probe the current viewer (`me`) for the chrome. Signed-out → `{ user: null }`. |
| `/api/auth/logout` | `POST` | Invalidate the session and clear the shared cookies. |
| `/api/watchlist` | `GET` / `POST` / `DELETE` | List / add / remove the viewer's favourited channels. |

**Watchlist.** A signed-in viewer taps **Watch** on any channel page to add it to
their Watchlist; the `/watchlist` view lists their favourited channels with a
link to each public channel page and an inline remove control. A signed-out tap
routes to the Lumio-ID login and returns to the channel. Persistence is
**per-user** and lives entirely behind the authenticated proxy routes above —
distinct from the cookieless public read path. The `/watchlist` page is
`force-dynamic` and `noindex` (a personal surface, never cached or crawled).

> **Backend persistence:**
> The Watchlist persistence API (GraphQL `myWatchlist` / `addToWatchlist` /
> `removeFromWatchlist`, REST `GET/POST/DELETE /v1/watchlist`, and the
> `stats_watchlist` table) is a per-user authenticated surface tracked separately
> from the public read model. See the API reference for the endpoint shapes.

## The registry

`public_channel_settings` is a carve-out registry - **absence of a row means the
channel is public but its chatter leaderboard is hidden** (channel listing
opt-out, leaderboard opt-in). A row records:

| Field | Meaning |
|-------|---------|
| `platform`, `platform_channel_id` | Channel identity the row is keyed on (`UNIQUE`). |
| `account_id` | The owning account for a first-party channel; `NULL` for a crawled channel. `ON DELETE SET NULL` - an account dissolving never re-publishes or drops a channel's opt-out. |
| `is_public` | `false` = opted out (hidden from the Stats app). Default `true` (opt-out). |
| `show_top_chatters` | The chatter leaderboard is **opt-in**: hidden until the broadcaster explicitly enables it (Art. 25(2) privacy-by-default). Default `false`, independent of `is_public`. |
| `opted_out_by` / `opted_out_via` | Provenance of an active opt-out (who / how - `dashboard` for the toggle, `crawler_command` for a verified `!optout`). `opted_out_by` is the Lumio user id for `dashboard` and the broadcaster's Twitch user id for `crawler_command`. Cleared to `NULL` on opt-in. |

## Managing publicness

A first-party broadcaster manages their own connected channels from the
dashboard (OAuth-proven ownership). The channel is always resolved to the
caller's own connected channel for the platform - the channel id is never taken
from the client, so an account can only change a channel it has connected.

- **GraphQL** - `channelPublicSettings` (read), `setChannelPublicSettings` (write).
- **REST** - `GET /v1/public-stats/channels`, `PUT /v1/public-stats/channels/{platform}`.

Both protocols are identical in fields, permissions, validation, and errors.

## Search indexing and sharing

Only `https://stats.lumio.vision` can be indexed. The app reads
`LUMIO_STATS_URL` at request time; staging, the production-preview host and any
missing or invalid origin send `noindex, nofollow` and `X-Robots-Tag`, serve
`robots.txt` with `Disallow: /`, and return 404 for sitemap routes. On the
production host, `robots.txt` advertises `/sitemap.xml` and disallows `/api/`.

The home page, ranking pages, Games, Emotes and Partners are indexable. Channel
pages are indexable for Twitch and Kick; YouTube channel pages remain available
but are `noindex, follow` and are not in the sitemap. Stream pages and `/{channel}/history` are always
`noindex, follow`. Search results are `noindex, follow`; the personal watchlist
is `noindex, nofollow`. These pages are not in the sitemap. The channel page
shows current profile and active-panel content only, with a link to its separate
history page. A channel's canonical URL uses the current login from
`publicChannelCard.channelLogin`, including after a handle change.

`/sitemap.xml` indexes a static sitemap and zero-based channel files at
`/sitemaps/channels/{page}.xml`. The static file lists the home page, five
ranking metrics, Games, Emotes and Partners. Channel files contain at most
45,000 URLs each, only for the API's server-side platform allowlist (default
Twitch and Kick), channels with a login and a stream started in the last 12 months, and
channels that have not opted out. They contain no stream URLs. `lastmod` is the
date of the latest stream start, not the date the read model was refreshed.
The page count is calculated at request time; because its count does not
subtract opt-outs, the last file can be short or empty. Each URL carries
English, German and default language alternates.

Page share images are available for home, rankings, Games, Emotes and Partners.
Channel share images use the stable platform channel ID, so a handle rename
does not change the image key. A channel image shows only the current display
name, handle and aggregates; it contains no chatter names, bio, links, team or
change history. Unknown or opted-out channels and card errors receive the same
generic banner. The footer states in English and German that Lumio Stats is an
independent service, has no affiliation with Twitch, YouTube or Kick, and that
those marks belong to their owners.

## Public read model

The Stats app consumes an **unauthenticated, cache-friendly** read surface over
the signed-off field-visibility matrix. It carries **no per-user data** - every
caller sees the same response for a given channel/stream, so it caches cleanly at
the edge. Two reads:

- **Channel page** - aggregate over a channel's streams, matched by the stable
  `(platform, platform_channel_id)` and addressed by the URL **handle**
  (`channel_login`): stream count, total streamed duration, peak/avg viewers,
  total messages, the channel's **follower / subscriber totals** (current values;
  unavailable metrics render as "—", see §5), a **live status** (`is_live` + the
  current stream's title/category/start/current viewers when live; see §Live
  status), a recent-streams list, the **current active ad-marked panels**
  (broadcaster-marked advertising panels - title/image/text/link; see
  §5), and the **About box** (bio, social links, team; see §5).
- **Stream page** - one stream by its public key `(platform, broadcast_id)`, its
  session-level public aggregates, and its viewer-curve timeseries.

Exposed through GraphQL and REST with identical fields, validation, and errors (a per-broadcast WebSocket snapshot also exists):

| Protocol | Channel page | Stream page |
|----------|--------------|-------------|
| **GraphQL** | `publicChannelStats(platform, channel)` | `publicStreamStats(platform, broadcastId)` |
| **REST** | `GET /v1/public-stats/channels/{platform}/{channel}` | `GET /v1/public-stats/streams/{platform}/{broadcast_id}` |
| **WebSocket** | - | `public-stats:{platform}:{broadcast_id}` (bootstrap snapshot on subscribe) |

The whole surface is gated by the `system:public_stats` kill-switch flag - an
infrastructure flag (no plan pairing) that turns the public read model on/off
globally across all three protocols. Because the path is account-less, the flag
is checked with no account; flipping it off returns "not available" on
REST/GraphQL and rejects the WS subscribe with `FEATURE_DISABLED`.

The Stats app reads this surface server-side and counts each visitor in their own
rate-limit bucket: every read sends the internal token (`LUMIO_INTERNAL_TOKEN`)
and the visitor's address from the Cloudflare `CF-Connecting-IP` header as
`X-Lumio-Client-IP`, so the API limits per visitor (600 requests/min) rather than
per Stats server. The sitemap reads serve no single visitor and send the token
alone (shared internal budget, 1200 requests/min). Without
`LUMIO_INTERNAL_TOKEN` all Stats traffic shares one anonymous budget of 120
requests/min, so the variable is required in every deployment.

Each `public-stats:*` subscribe reads the stream snapshot from the database, and
anonymous callers may subscribe. The per-session
[subscribe rate limit](../api-reference/websocket.md#subscribe-rate-limit)
bounds how many of these reads one socket can trigger: 120 subscribe/unsubscribe
frames back-to-back by default (never fewer than the session channel cap), then
5 per second, answered with `RATE_LIMITED` beyond that.

### Field visibility (§5)

The read model serves **only** the public-safe field set and enforces the
registry on every read:

- **Served:** stream title/category, start/end/duration, viewer curve
  (peak/avg + the per-minute `viewer_count` series), total messages, unique
  chatters, emote count + top emotes, new-follower count, de-identified paid/
  gifted **sub counts** (numbers only), and the `source` provenance badge
  (`first_party` renders the "Lumio channel" badge; `external_crawler` renders
  none). First-party and crawled rows flow through the **same** resolvers/types,
  distinguished only by `source`.
- **Ad-marked panels**: the timeline of Twitch panels the
  broadcaster **marked as advertising** - each version's title, image URL, text,
  link, and `firstSeenAt`/`lastSeenAt` period. This is a **narrow** served slice
  of panel data, by founder ruling (ZAF-794/ZAF-798): only panels whose title,
  description, or link URL carries a self-declared ad/sponsorship signal
  (`werbung`/`anzeige`/`ad`/`ads`/`advert…`/`sponsor…`/`gesponsert`/`partner`, or
  an affiliate/tracking link) are captured - every other panel is dropped at
  crawl time and never persisted. The classification is **self-declared**: the UI
  presents these as panels the broadcaster *marked* as advertising, never as an
  assertion that they *are* advertising. Only image **URLs** are stored; the page
  shows the artwork through the image proxy, which keeps no copy beyond the 24-hour
  HTTP cache. Non-ad panels are provably absent - the
  matching is word-boundary (so *Adventskalender*/*download* never match `ad`).
  Each panel carries a lifecycle `status` (`active`/`removed`) + explicit
  `removedAt` (ZAF-892): the crawler reconciles the channel's current ad-marked set
  every observation and marks a `panelId` removed when it disappears (or is edited
  so it is no longer ad-marked - the disclosure ended), clearing it if the panel
  reappears.
- **Panel lifecycle + image-change history** (separate channel history page,
  ZAF-892): `publicChannelPanelHistory(platform, channel)` returns the ad-marked
  panels **grouped by panel**, each with its latest content, full observed span,
  lifecycle (`status` + `removedAt`), and an **image slideshow** —
  `images: [{ imageUrl, firstSeenAt, lastSeenAt }]`, the old→new artwork timeline
  (distinct image URLs over time, oldest-first). The image versions come from the
  same `content_hash` versioning that already records a new row on any artwork
  change, so no extra store is needed. Same empty-state discipline (absent channel
  → null, no panels → `[]`), opt-out gating, and proxied-artwork rule as the flat
  panel timeline. It powers the separate `/{channel}/history` page; the indexable Placements tab shows only active panels and their latest artwork.
- **Follower / subscriber counts** (channel page only, ZAF-796): the channel's
  current **follower total** and **subscriber total** - channel-level aggregates
  (a broadcaster publishes them on their own channel page; no viewer identity),
  stored current-values-only in `public_channel_metrics` keyed by the same
  `(platform, platform_channel_id)` identity. **Availability is per-platform and
  per-metric**, and an unavailable metric is served as `null` and rendered as "—",
  **never `0`**: the Twitch **follower total** is captured from the public GQL
  surface; a Twitch **subscriber count is not public** (obtainable only with the
  broadcaster's own OAuth), so it is always "—" for crawled channels; a YouTube
  **subscriber count** is public via the Data API and is populated once a YouTube
  crawl path exists (until then, "—").
- **About box** (channel page only, ZAF-799; rendered as the lower region of the
  consolidated identity top card since ZAF-866): the broadcaster's **bio /
  description**, their configured **social links**, and their **team**
  membership(s), stored current-values-only in `public_channel_profile` keyed by
  the same `(platform, platform_channel_id)` identity. Served under the §5
  approval (ZAF-793 plan, accepted 2026-08-27) with three conditions that are
  part of the ruling, not styling: **(1)** the bio is **plain text**, republished
  **verbatim and inert** - no HTML, no markdown, no link auto-embedding, no
  enrichment - and follows **refresh-and-overwrite**: each crawl overwrites the
  stored value (including to empty), so a shortened or deleted bio is never
  retained. **(2)** social links are served as label + raw URL and rendered
  `rel="nofollow noopener ugc"`, `target="_blank"` with **no unfurl, preview, or
  shortener resolution**. **(3)** team is structured display name(s) only. Each
  field is independently optional: `description` is `null` when absent, and
  `social_links` / `team` are empty lists (never `null`); a channel with all
  three absent renders no About region, collapsing the top card to its identity
  block (ZAF-866). The channel page shows the **current**
  values; the versioned **change history** of these three fields is a separate
  read - see [About-box change history](#about-box-change-history-zaf-836) below.
- **Channel type** (`broadcaster_type`, ZAF-841/ZAF-842/ZAF-860): the
  Twitch **partner / affiliate** status, rendered as an icon badge after the
  channel name (a verified-style mark for partner, a lighter
  marker for affiliate - mirroring the main web app's partner/affiliate language).
  It is exposed on **both** read models: the channel-page model
  (`PublicChannelStats`) and the cross-channel **browse / rankings / search** rows
  (`PublicChannelBrowseItem`, ZAF-860), so the same badge renders after the name on
  the channel page and in every browse-list row. On the browse path the type is not
  a Timescale aggregate column - it is stitched from `public_channel_profile` with
  one batched lookup per page (keyed by channel identity), not a per-row join.
  Stored current-values-only on `public_channel_profile`
  (the same About-box row) and captured from the same undocumented Twitch GQL
  `user` node (`roles { isPartner isAffiliate }`) - the same public partner/
  affiliate badge Twitch shows logged-out visitors, no viewer identity. Values are
  `"partner"` / `"affiliate"`, or `null` when the channel is neither (Twitch's
  none case), not captured, or a non-Twitch platform ⇒ **no badge is rendered**
  (never a "none" label). Like every profile field it is **refresh-and-overwrite**:
  a partner→affiliate→none demotion propagates on the next crawl, so no stale
  partner badge is retained. **"Twitch DJ" is a separate program and is _not_ a
  `broadcaster_type`** - it is not exposed per channel by any Twitch API field, so
  the badge is only ever partner/affiliate.
- **Chatter leaderboard** (`top_chatters`, usernames + counts) is served **only**
  when the channel opted the leaderboard in (`show_top_chatters = true`);
  otherwise it is absent (`null`), never an empty list. A chatter the channel
  had erased ([Chat → Erasure](./chat.md#erasure-gdpr-art-17)) keeps their rank
  and count with an empty name and `erased: true`; the stream page shows them as
  "Deleted user" without an avatar. The same applies to a chatter on Lumio's
  global suppression list (`chatter_suppressions`: Lumio-level erasures and
  GDPR Art. 21 objections, [Chat → Objection](./chat.md#objection-gdpr-art-21)):
  the leaderboard is checked against that list on every read, across all
  channels, so an objection also hides the name on streams published before it.
  This read-time mask is a Lumio Stats surface only; it does not change any
  channel's own report, export or share link. The stored session is not changed, so lifting the objection shows the name
  again. If the list cannot be read, the leaderboard is `null` (hidden) while the
  rest of the stream page is still served. The stream page caches the API answer
  for at most 30 seconds, so a change shows on the next refresh after that; a
  page nobody opened since the change can serve the old answer to one more visit.
- **Never served:** donations, subscriber/gifter identities, revenue splits, and
  the raw `platform_metrics` / `platform_breakdown` JSONB. These are not modelled
  on the public types, so they cannot leak.

### Live status (ZAF-795)

The channel page carries an `is_live` flag and, when live, a `live_stream`
summary (broadcast id, self-reported title/category, `started_at`, and the
current viewer count). The data already exists - the Twitch crawler's StatsPoller
sweeps currently-live streams every 60s and writes a `channel_history_stats`
viewer sample per live channel; no new external fetch is made.

Liveness is derived from **observation freshness**, not `ended_at`: a channel is
live iff it has a still-open stream row whose most-recent viewer sample is newer
than a 5-minute window. The crawler stops emitting samples as soon as Twitch drops
the channel from the live sweep, but only sets `ended_at` on
`channel_history_streams` after 10 minutes without a sample (its close sweep). An
`ended_at IS NULL` check alone would keep a just-ended crawled stream live for that
long; the freshness window clears it for both first-party and crawled channels
within one window of the stream end. Served identically on GraphQL (`isLive` / `liveStream`) and
REST (`is_live` / `live_stream`); the channel page has no WebSocket bootstrap.

### About-box change history (ZAF-836)

The three About-box fields - **bio**, **social links**, and **team** - are
broadcaster-published, freely accessible profile data. By founder ruling
(ZAF-791) they are **not** personal data under the §5 minimisation regime, so
in addition to the current-values row the crawler keeps a **versioned change
history**: every time it detects that a field differs from the stored value, it
records one timeline entry with the **old value**, the **new value**, the
**change type** (`bio` / `link` / `team`), and the **detection time**. This is
the same timeline treatment the ad-marked panels get (`firstSeenAt → lastSeenAt`).

- **Read surface** - a paginated, most-recent-first timeline. GraphQL query
  `publicChannelProfileHistory(platform, channel, limit, offset)` (primary) and
  REST `GET /v1/public-stats/channels/{platform}/{channel}/profile-history?limit=&offset=`
  return the identical field set (parity); `limit` defaults to 50 and is capped
  at 200. It is gated exactly like the channel view - the `system:public_stats`
  kill-switch plus the opt-out check - so an opted-out or unaddressable channel
  returns GraphQL `null` / REST `404`. The separate `/{channel}/history` page reads it via `publicGql`
  (SSR); there is no WebSocket surface (the public-stats WS bootstrap carries
  only the per-stream snapshot).
- **Value shape** - `oldValue` / `newValue` are opaque JSON interpreted by
  `changeType`: a JSON **string** for `bio`, a JSON **array** of `{ url, label }`
  / `{ name, display_name }` for `link` / `team`. `null` on the old side marks
  the initial capture (no prior value); `null` on the `bio` new side marks a
  deletion.
- **No §5 minimisation, no time cap, no audit event.** Because these are public
  data, the history carries the full old→new values (no minimisation) and is kept
  **indefinitely** - the 90-day raw-sample retention (ZAF-689) does **not** apply.
  Writing these rows is crawler telemetry over public data, not a security- or
  lifecycle-relevant action, so it deliberately emits **no** audit event. The
  only erasure path is **opt-out** (below).

### Stream-metadata change history (ZAF-890)

A live broadcast's **title**, **category**, and **content tags** change during a
stream. Like the About box these are broadcaster-published, freely accessible
stream metadata - by founder ruling (ZAF-791 / ZAF-794) **not** personal data under
the §5 minimisation regime - so alongside the current values on the stream summary
the crawler keeps a **versioned change history** per broadcast: every time it
detects that the title, category, or tag set differs from the last recorded value,
it records one timeline entry with the **old value**, the **new value**, the
**change type** (`title` / `category` / `tags`), and the **detection time**. This
is the stream-scoped sibling of the
[About-box change history](#about-box-change-history-zaf-836), keyed by the
broadcast rather than the channel.

- **Read surface** - a paginated, most-recent-first timeline. GraphQL query
  `publicStreamMetadataHistory(platform, broadcastId, limit, offset)` (primary) and
  REST `GET /v1/public-stats/streams/{platform}/{broadcast_id}/metadata-history?limit=&offset=`
  return the identical field set (parity); `limit` defaults to 50 and is capped at
  200. It is gated exactly like the stream view - the `system:public_stats`
  kill-switch plus the opt-out check - so an opted-out or unknown stream returns
  GraphQL `null` / REST `404`.
- **Value shape** - `oldValue` / `newValue` are opaque JSON interpreted by
  `changeType`: a JSON **string** for `title` / `category`, a JSON **array** of tag
  strings for `tags`. `null` on the old side marks the initial capture (no prior
  value); `null` on the new side marks an emptied field (title/category cleared, or
  all tags removed).
- **Tags** are captured from Helix `Get Streams` `tags[]` (fail-open: an absent
  field reads as no tags) and stored in the broadcaster's configured order.
- **UI** - the stream page renders this timeline as a **change-history card**
  (mirroring the About-box card): each entry shows the change type, its detection
  time, and a before→after comparison - `title` / `category` as plain inert text,
  `tags` as non-interactive chips with added tags emphasised and removed tags
  struck through. A `null` fetch (opted out / unknown) or an empty history renders
  no card at all.
- **No §5 minimisation, no time cap, no audit event.** As public data the history
  carries the full old→new values and is kept **indefinitely** (the 90-day
  raw-sample retention, ZAF-689, does **not** apply); writing the rows is crawler
  telemetry over public data, so it deliberately emits **no** audit event. The only
  erasure path is **opt-out** (below).

### Channel trends - follower growth + average viewers over time (ZAF-891)

The channel page's **"Stats" tab** renders two dated, channel-scope time series
that the single-value aggregates (`avgViewers`, `peakViewers`, `followerCount`)
cannot express: a **follower-growth** line with a selectable
**30 / 90 / 180 / 365-day** window, and an **average-viewers-over-time** line.

- **Read surface** - GraphQL query
  `publicChannelTrends(platform, channel, range)` (primary) and REST
  `GET /v1/public-stats/channels/{platform}/{channel}/trends?range=` return the
  identical field set (parity), gated exactly like the channel view (the
  `system:public_stats` kill-switch plus the opt-out check) → an opted-out or
  unaddressable channel returns GraphQL `null` / REST `404`. `range` is one of
  `DAYS_30 | DAYS_90 | DAYS_180 | DAYS_365`; an unknown value → error / `400`. The
  result carries `followerSeries` (`{ date, followerCount }`) and `avgViewerSeries`
  (`{ date, avgViewers }`), each an **oldest-first** list of day points with `date`
  = `YYYY-MM-DD` (UTC). Either series is an **empty list** when the channel has no
  history in the window, so the frontend renders its existing "not enough history"
  state rather than a fabricated chart. Read via `publicGql` (SSR); no WebSocket
  surface.
- **Two sources, two mechanisms.** The **follower** series comes from dated
  snapshots the crawler writes into `public_channel_follower_history` - one row per
  detected follower-count change (it piggybacks the `public_channel_metrics`
  write-amplification guard, so an unchanged poll writes nothing), and the read
  returns the **last value per day**. The **average-viewers** series is a
  read-model-only projection of the existing `channel_history_stats_1h` continuous
  aggregate (ZAF-681), **day-bucketed** and scoped to the channel's own sessions
  (resolved via `channel_history_streams` - the aggregate itself is session-keyed);
  the per-day value is the exact sample-weighted mean. Because that aggregate is
  kept indefinitely (the privacy-promised viewer-count curve), the average-viewers
  line covers the full 365-day window even past the 90-day raw-sample retention.
- **Aggregate counts only, no viewer identities.** A follower total is a
  low-sensitivity, broadcaster-published aggregate; the viewer series carries only
  counts. Neither surfaces any viewer identity (aggregates-only privacy tripwire).
- **No §5 minimisation, no time cap, no audit event.** Like the sibling change
  timelines (About box, ad panels), the follower-growth snapshots are kept
  **indefinitely** - a growth chart aged out is pointless - with **opt-out** as the
  sole erasure path, and writing them emits **no** audit event (crawler telemetry
  over public data).

### Channel history - panel lifecycle + image-change history (ZAF-892)

The separate `/{channel}/history` page reads the full per-panel lifecycle and
**image-change history** to render an old→new artwork slideshow and badge a
removed placement. The indexable Placements tab shows only active panels with
current artwork.

- **Read surface** - GraphQL query `publicChannelPanelHistory(platform, channel)`
  (primary) and REST `GET /v1/public-stats/channels/{platform}/{channel}/panel-history`
  return the identical field set (parity), most-recently-active panel first. Gated
  exactly like the channel view - the `system:public_stats` kill-switch plus the
  opt-out check - so an opted-out or unaddressable channel returns GraphQL `null` /
  REST `404`, and a channel with no ad-marked panels returns an empty list `[]`
  (never an empty shell). The separate `/{channel}/history` page reads it via `publicGql` (SSR); there is
  no WebSocket surface.
- **Shape** - per panel: `panelId`, latest content (`title` / `description` /
  `imageUrl` / `linkUrl`), full observed span (`firstSeenAt` / `lastSeenAt`),
  lifecycle (`status` = `active`/`removed` + `removedAt`), and
  `images: [{ imageUrl, firstSeenAt, lastSeenAt }]` - the distinct image versions
  over time, oldest-first (the slideshow). The API returns the Twitch CDN URLs; the
  Stats page rewrites them to the image proxy.
- **Lifecycle detection** - the crawler emits the channel's **full** current
  ad-marked set on every valid observation (even empty), so the writer can mark a
  `panelId` `removed_at` when it disappears from the set (taken down, or edited so
  it is no longer ad-marked - the disclosure ended) and clear it on re-observation;
  the marker is kept coherent across a panel's versions. The image versions
  themselves are already persisted (a new artwork lands as a new `content_hash`
  version row), so no separate history table is needed.
- **No §5 minimisation, no time cap, no audit event** - same regime as the flat
  panel timeline: broadcaster-published sponsorship-disclosure data, kept
  indefinitely, opt-out as the only erasure path, and no audit event (crawler
  telemetry over public data).

### Opt-out enforcement

Opt-out is enforced **two-sided**. On the **read** side, a channel with
`is_public = false` in the registry is **not served** - the channel and stream
reads return nothing: GraphQL `null`, REST `404`, and no WS bootstrap. A channel
with no registry row is served (public-by-default) with its leaderboard hidden
(opt-in default).

On the **capture** side, the crawler also stops collecting the channel and erases
what it already collected: it drops the channel from its roster (no further JOIN,
poll, or write) and **deletes** that channel's already-captured
`source='external_crawler'` rows from the history tables, **every ad-marked
panel version row** (`public_channel_panels`), **its follower/subscriber
metrics row** (`public_channel_metrics`), **every follower-growth snapshot row**
(`public_channel_follower_history`), **its About-box profile row**
(`public_channel_profile`), **every About-box change-history row**
(`public_channel_profile_history`), **and every stream-metadata change-history
row** for its broadcasts (`public_stream_metadata_history`) - serviceable
deletion. These crawled data tables live in TimescaleDB (relocated from main
Postgres, or authored there directly for the change/history tables, per the founder
ruling ZAF-791/ZAF-843/ZAF-836/ZAF-890/ZAF-891); only the `public_channel_settings`
opt-out registry stays in the main DB. So opting out both hides the channel and
removes its crawled data —
see the
[crawler developer guide](../developer-guide/public-stats-crawler.md#opt-out-enforcement-two-sided).

**Ad-panel timeline retention.** Unlike the raw viewer/chat history (90-day
sample retention, ZAF-689), the ad-marked panel timeline (`public_channel_panels`)
is kept **indefinitely**: a sponsorship-disclosure record with no timeline is
pointless, and the data is broadcaster-published commercial disclosure. The
erasure path is **opt-out** (above) - an `is_public = false` deletes every
version row. A panel that changes content adds a new version row; an unchanged
panel on re-crawl only refreshes its `lastSeenAt` (guarded), so the table holds
roughly one row per real change, not one per crawl. The panel **lifecycle marker**
(`removed_at`, ZAF-892) is a column on the same table - it is set/cleared by the
crawler's per-observation reconciliation (a genuine change is a write; an unchanged
state is not) and erased with the row on opt-out, so it inherits the same
indefinite / opt-out-only retention and needs no separate store or enforcer step.

The **About-box change history** (`public_channel_profile_history`, ZAF-836) and
the **stream-metadata change history** (`public_stream_metadata_history`, ZAF-890)
follow the same retention model: kept **indefinitely** (public broadcaster-published
data, founder ruling ZAF-791 - no §5 minimisation and no 90-day cap), with
**opt-out** as the sole erasure path. Because a history row is written only when a
field actually changes (an unchanged re-crawl records nothing), the tables grow with
real edits, not with crawl frequency.

**GIF content data (Top GIFs) - 90-day retention, consent-gated display
(ZAF-965/968/969).** The **Top GIFs** capture is the exception to the
indefinite-retention model above: it stores a **content datum** (the GIPHY id +
image URL of the GIFs that appeared in a broadcast's public chat, with a frequency
count and **no sender reference** - no chatter, message, or identity), so by the
ZAF-965 founder decision it is bounded to a **90-day retention**, aligned with the
raw-sample window (ZAF-689), then auto-deleted, with opt-out as an additional
erasure path. Rendering the Top GIFs loads the image directly from `media*.giphy.com`
(the visitor's IP + user agent reach GIPHY, US); because the Stats app is public
(no contract with the visitor), the embed is **consent-gated** - it loads only after
the visitor grants the **Functional** consent category, honouring the `cookies.mdx`
"loads only after consent" promise. Before consent the Top-GIFs card renders a
**text-only** fallback (GIF name/id + occurrence count) and mounts no `<img>`,
preconnect, or preload against the GIPHY domain, so the gate is real and not
cosmetic; the GIF URL is then loaded **verbatim** (no proxy, no resize - Twitch
requirement ZAF-960 D2). Capture + retention are implemented in ZAF-968; the
privacy/cookies texts and the retention figure are governed by ZAF-969
(`apps/web/content/{de,en}/legal/privacy.mdx` content class **(D)** and
`…/cookies.mdx` §"Lumio Stats"); the consent-gated public display lands in ZAF-970
(`apps/stats` - the `gif_count` stat tile and the `TopGifs` card on the stream
page).

## Cross-channel browse & search (Form B)

Beyond the single-channel and single-stream reads above, the Stats app browses
and ranks **across all channels** - the top-bar metric nav (Watchtime, Viewers,
Follower Gain, Peak, Live), a **Games** directory, and channel search. Channels
are keyed by the frozen channel identity `(platform, platform_channel_id)` -
never by account - so first-party and crawled channels are indexed uniformly
(Form B).

The reads come from a **browse read model** in TimescaleDB, derived from
`channel_history_streams` (see the
[data design standard](../developer-guide/data-design.md#derived-read-models)):

| Table | Holds | Fresh within |
|---|---|---|
| `public_channel_browse` | per channel: totals over its **closed** streams, latest handle / display name / source / category | ~15 s after a stream closes |
| `public_channel_category_browse` | the same per (channel, category), for the category filter | ~15 s |
| `public_channel_browse_live`, `public_channel_category_browse_live` | channels with an open stream: closed + open totals, live state | 60 s |
| `public_category_browse` | the Games directory, opted-out channels excluded | 5 min, and right after an opt-out toggle |

Each sort has its own index, so a page is two index top-N reads (channels
without an open stream, and channels with one) merged in SQL. The cost follows
the page depth and the number of live channels, not the number of streams ever
recorded. A database trigger queues a channel whenever one of its closed stream
rows changes, and an API worker recomputes the queued channels. Until the
first backfill after deployment has been worked off, browse reads
`channel_history_streams` directly.

Two reads, exposed on **GraphQL + REST** with identical fields, filters,
pagination, and errors. WebSocket is deliberately omitted - a browse/search
directory has no live-push consumer (the same justified single-protocol omission
as the emote directory):

| Protocol | Channel browse | Games directory |
|----------|----------------|-----------------|
| **GraphQL** | `publicChannelBrowse(platform, category, metric, live, search, page, limit)` | `publicGames(platform, search, page, limit)` |
| **REST** | `GET /v1/public-stats/browse` | `GET /v1/public-stats/games` |

- **`metric`** ranks the channel list: `watchtime` (Σ avg-viewers·duration,
  the default), `viewers` (avg), `peak`, `follower_gain` (Σ new-followers),
  `messages`, or `recent`. `live` filters to channels streaming now; `category`
  filters to a game; `search` is a case-insensitive substring match on the
  channel's **current** handle + display name (the newest stream's). A renamed
  channel is found under its new name only, not under a name it used before.
  Pagination is page-based (`page` 1-based,
  `limit` clamped `1..=100`, plus `total` / `total_pages`).
- **Depth cap.** A browse pages at most **10 000** rows deep: `page` is clamped
  so the page starts before row 10 000, and `total` counts at most 10 000. When
  more rows match, `total_capped` (GraphQL `totalCapped`) is `true` and `total`
  is the cap - show it as "10 000+". Both endpoints are public, and the cap keeps
  a deep page or an exact count from growing with the channel count.
- **Watchtime of a live stream** counts up to its latest viewer sample, not up
  to the moment of the request. An open stream without a sample in the
  freshness window contributes nothing, so a stream that was never closed does
  not keep growing.
- **Live status** - `is_live`, the `live` filter, and the Games `live_stream_count`
  are derived from **observation freshness**, not `ended_at`: a stream counts as
  live only while it is still open **and** its most-recent `channel_history_stats`
  viewer sample is inside a 5-minute window. The Twitch crawler stops sampling as
  soon as the channel drops from the live sweep but only sets `ended_at` 10 minutes
  later, so an `ended_at`-only check would keep just-ended crawled streams in the
  `live` filter for that long. Freshness clears correctly for first-party and
  crawled channels alike, and keeps browse consistent with the channel-page live
  badge (ZAF-833).
- **Games** returns distinct categories with per-category channel count, stream
  count, live-stream count, peak viewers, and watchtime. The live-stream count
  is read per request; the other totals are as of the last Games rebuild.
- **Field set** is the public-safe browse subset only: identity, the `source`
  badge, viewer/watchtime/message aggregates, follower **gain**, category, and
  live status. Absolute follower **total** is intentionally not a browse metric —
  it lives only on the account-keyed viewer-curve samples, not on a Form-B /
  account-optional row, so ranking all channels by it would silently drop crawled
  channels; it can be added once a non-account-keyed follower count exists.
- **Opt-out** is enforced identically: a channel with `is_public = false` is
  excluded from the browse **and** from the Games counts. The opted-out identity
  set is read from the registry (main DB) on every request and excluded from the
  read model (TimescaleDB) - no cross-DB join. The Games totals cannot be
  corrected at read time (a peak cannot be subtracted), so an opt-out toggle
  triggers a Games rebuild without that channel. The crawler's opt-out erasure
  deletes the channel's read-model rows in the same transaction as its stream
  rows.
- The whole surface is gated by the same account-less `system:public_stats`
  kill-switch; the REST responses carry an edge-cache `Cache-Control` header.

## Cross-channel placements - advertisers (ZAF-1578)

The per-channel **Placements** tab has a cross-channel counterpart that backs the
Stats app's **Partners** surface (`/partners`): which advertiser runs placements
on how many channels. It reads the same broadcaster-marked ad panels
(`public_channel_panels`, classified crawler-side) and groups the **active** ones
of every public channel by **advertiser** - the host of the panel's link,
lower-cased with a leading `www.` stripped (`https://www.Brand.com/?ref=x` →
`brand.com`). Links are not followed or resolved, so a shortener host (e.g.
`bit.ly`) is its own advertiser.

| Protocol | Read |
|----------|------|
| **GraphQL** | `publicPlacementsBrowse(platform, domain, sort, after, limit, placementsLimit)` |
| **REST** | `GET /v1/public-stats/placements` |

- **Placement set** - only a panel's **latest** content version counts (older
  versions are its history, not a placement), only `active` panels (`removedAt`
  unset), only panels whose link is an `http(s)://` URL, and only channels that
  have an addressable Stats channel page, so every placement links to a page that
  resolves.
- **Per advertiser** - `domain`, `channelCount` (distinct channels),
  `placementCount`, `firstSeenAt` / `lastSeenAt`, and up to `placementsLimit`
  placements (default 10, max 50; most recently seen first). Each placement
  carries the channel's public identity (`channelLogin` from the latest stream;
  `channelDisplayName` + `avatarUrl` from the crawled profile, display name
  falling back to the stream's) plus the panel's `title`, `imageUrl` and
  `linkUrl`. `placementCount` above the embedded list size means the list was
  truncated - query with `domain` for the full set.
- **Sort + pagination** - `CHANNEL_COUNT` (default) or `LAST_SEEN`, ties by
  `domain`. **Keyset** pagination with an opaque cursor (`nextCursor` → `after`),
  `limit` 1-100 (default 25); a cursor from the other sort is rejected.
- **Filters** - `platform` defaults to `twitch`, the only platform with a panel
  capture today (anything else is a validation error); `domain` narrows to one
  advertiser.
- **Public-safety** - identical to the per-channel Placements tab: opted-out
  channels are excluded (the opted-out set is read from the main-DB registry and
  excluded from the TimescaleDB read - no cross-DB join), the API returns the
  Twitch CDN URLs of panel artwork and avatars (the Stats page shows them through
  the image proxy), and there is no viewer data. Gated by the `system:public_stats` kill-switch; the REST response
  is edge-cacheable.
- **No WebSocket** - the only `public-stats` WS channel is the per-broadcast live
  read. Like the other cross-channel reads, placements change per crawl, so there
  is no live-push consumer.

## Watchlist (per-user)

Signed-in visitors can **favourite channels** into a personal Watchlist. Unlike
the public read model, this is a **per-user, authenticated** surface: it is
scoped to the signed-in Lumio-ID viewer (the shared `lumio-token` session), holds
**no account/RBAC permission** (a favourite is a personal preference, like a
session or notification setting), and is **not cached** (per-user, session-bound).

Rows live in the **primary DB** table `stats_watchlist`, keyed by
`(user_id, platform, platform_channel_id)`. On add, the channel URL **handle** is
resolved to the stable `platform_channel_id` via the **same public read-model
resolution** the channel page uses, and `channel_login` / `channel_display_name`
are denormalized onto the row so the list renders without a per-item read-model
lookup.

Exposed on **GraphQL + REST** with identical fields, validation, and errors:

| Protocol | List | Add | Remove |
|----------|------|-----|--------|
| **GraphQL** | `myWatchlist` | `addToWatchlist(platform, channel)` | `removeFromWatchlist(platform, platformChannelId)` |
| **REST** | `GET /v1/watchlist` | `POST /v1/watchlist` `{ platform, channel }` | `DELETE /v1/watchlist` `{ platform, platform_channel_id }` |

Semantics:

- **Auth:** authenticated viewer only. Unauthenticated calls return
  `UNAUTHENTICATED` on GraphQL (the Stats frontend maps this to "signed out") and
  `401` on REST. There is **no plan gate** - it is a free logged-in feature.
- **Add** validates the platform (`Unsupported platform: …` → `400`), resolves the
  handle (unresolvable → `Channel not found` → `404`), then performs an
  **idempotent upsert** (re-adding refreshes the denormalized login/display name).
  A per-user cap of **500** channels is enforced; a new add past the cap returns a
  `400` "Watchlist limit reached" (an idempotent re-add of an already-present
  channel still succeeds at the cap).
- **Remove** is idempotent - it returns success (`true`) even when the row was
  already absent.
- **No WebSocket leg:** a watchlist is a single user's own list, mutated only by
  that user's own action, with no real-time push semantics - the three-protocol
  rule's WS leg is deliberately N/A here.
- **No audit event:** a favourite / unfavourite is personal bookkeeping with no
  security consequence.

## Permissions

| Permission | Grants | Default roles |
|-----------|--------|---------------|
| `public-stats:read` | View the account's channel publicness settings | Owner, Administrator, Moderator |
| `public-stats:edit` | Toggle publicness / leaderboard suppression | Owner, Administrator |

Gated behind the `feature:public_stats_page` feature flag (Free and Pro plans).
The flag is fail-closed: a plan with no paired `plan_features` row resolves to
disabled.

## Audit

Every **dashboard** publicness change emits an account-scoped audit event, chosen
from the resulting state:

- `public_stats:channel_opted_out` - a channel was hidden (`is_public → false`).
- `public_stats:channel_opted_in` - a channel was re-listed (`is_public → true`).

The channel identity and the resulting leaderboard-suppression state are recorded
in the event metadata.

The **`!optout` command path deliberately does not emit** these account-scoped
events - its actor is a Twitch platform user proven by a chat badge (no Lumio
`user_id`) and a crawled channel has no `account_id`, so an account-scoped event
has no valid keys. Provenance is recorded on the registry row instead
(`opted_out_via = 'crawler_command'`, `opted_out_by`, `updated_at`). A
system-scoped mirror event is a coordinated follow-up (it needs the audit emitter
extracted into a shared crate). See the
[crawler developer guide](../developer-guide/public-stats-crawler.md#broadcaster-optout-chat-command).

---

## Features / Rewards

Source: https://docs.lumio.vision/features/rewards

# Rewards

## Overview

The rewards module manages channel rewards (e.g., Twitch Channel Points) with full CRUD operations. Each reward is scoped to an account and platform, with an optional link to the platform's native reward ID. Rewards carry a configurable `action` JSONB field that defines what happens when the reward is redeemed.

The whole surface is gated on the `feature:rewards` feature flag **in addition to** the `rewards:*` permissions - every query and mutation chains `FeatureGuard::new("feature:rewards")` before the permission guard, and the dashboard route `/dashboard/rewards` is wrapped in a `FeatureRouteGate` for the same flag.

## Architecture

```
Dashboard UI (/dashboard/rewards)
    |
    v
Next.js API Proxy (/api/rewards, /api/rewards/[id])
    |
    v
GraphQL (RewardQuery / RewardMutation)
    |
    v
db::rewards (PostgreSQL)
```

Rewards are stored in the `channel_rewards` table and can be synced with external platform reward systems via the `platform_reward_id` field. The `action` JSONB field allows flexible behavior configuration without schema changes.

There is no automatic sync worker: `platform_reward_id` is a value the caller supplies at creation and it cannot be changed afterwards (`UpdateRewardInput` carries no `platformRewardId` field).

## API

### GraphQL Queries

| Query | Args | Returns | Guards |
|-------|------|---------|--------|
| `rewards` | -- | `[Reward!]!` | `feature:rewards` + `rewards:read` |
| `reward` | `id: UUID!` | `Reward` | `feature:rewards` + `rewards:read` |

- `rewards` returns all rewards for the active account, ordered by `created_at ASC`.
- `reward` returns a single reward by ID, filtered by account ownership.

### GraphQL Mutations

| Mutation | Args | Returns | Guards |
|----------|------|---------|--------|
| `createReward` | `input: CreateRewardInput!` | `Reward!` | `feature:rewards` + `rewards:create` |
| `updateReward` | `input: UpdateRewardInput!` | `Reward!` | `feature:rewards` + `rewards:edit` |
| `deleteReward` | `id: UUID!` | `DeleteRewardResult!` | `feature:rewards` + `rewards:delete` |

All mutations verify account ownership before proceeding. A reward owned by another account is reported as `Reward not found` rather than a distinct authorization error, so ownership is not leaked.

### GraphQL Types

```graphql
type Reward {
  id: UUID!
  accountId: UUID!
  platform: String!
  platformRewardId: String
  title: String!
  cost: Int
  enabled: Boolean!
  action: JSON!
  createdAt: String!
  updatedAt: String!
}

input CreateRewardInput {
  platform: String!
  platformRewardId: String
  title: String!
  cost: Int
  action: JSON
}

input UpdateRewardInput {
  id: UUID!
  title: String
  cost: Int
  enabled: Boolean
  action: JSON
}

type DeleteRewardResult {
  success: Boolean!
}
```

### REST Endpoints

Rewards have no REST resource - `/v1/rewards` does not exist and no rewards operation appears in `apps/api/openapi.json`. External scripts CRUD rewards through GraphQL (`POST /v1/gql`). This is a gap against the three-protocol rule, not a design choice.

### WebSocket

There is no rewards channel. `channel_gate_for` in `crates/lo-websocket/src/gate.rs` has no `rewards` arm, so a `rewards:{account_id}` subscription resolves to `ChannelGate::Unknown` and is rejected. Reward **redemptions** arrive as platform events on the `events:{account_id}` channel (e.g. Twitch's `channel.channel_points_custom_reward_redemption.add`), not as reward-object changes.

### Action JSONB

The `action` field is a flexible JSONB object that defines reward behavior. It defaults to `{}` if not provided during creation. The structure is application-defined and can vary per use case (e.g., trigger an overlay alert, play a sound, enable a chat mode).

## Permissions

| Permission | Description |
|------------|-------------|
| `rewards:read` | List and view rewards |
| `rewards:create` | Create new rewards |
| `rewards:edit` | Update existing rewards |
| `rewards:delete` | Delete rewards |

Default-role assignment (`ROLE_OWNER` / `ROLE_ADMIN` / `ROLE_MODERATOR` in `crates/lo-auth/src/rbac.rs`):

| Permission | Owner | Administrator | Moderator |
|------------|:-----:|:-------------:|:---------:|
| `rewards:read` | x | x | x |
| `rewards:create` | x | x | |
| `rewards:edit` | x | x | |
| `rewards:delete` | x | x | |

## Database

### Table: `channel_rewards`

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Reward ID |
| `account_id` | `UUID` (FK) | Owning account |
| `platform` | `TEXT` | Platform identifier (e.g., `twitch`) |
| `platform_reward_id` | `TEXT` | External platform reward ID (for sync) |
| `title` | `TEXT` | Reward display title |
| `cost` | `INT` | Point cost (nullable) |
| `enabled` | `BOOLEAN` | Whether the reward is active |
| `action` | `JSONB` | Configurable reward action payload |
| `created_at` | `TIMESTAMPTZ` | Creation timestamp |
| `updated_at` | `TIMESTAMPTZ` | Last update timestamp |

### DB Functions

| Function | Description |
|----------|-------------|
| `list_rewards` | List all rewards for an account, ordered by `created_at ASC` |
| `get_reward` | Get a single reward by ID |
| `create_reward` | Insert a new reward |
| `update_reward` | Partial update using `COALESCE` for optional fields |
| `delete_reward` | Delete by ID, returns whether a row was deleted |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/rewards.rs` | GraphQL queries, mutations, input/output types |
| `apps/api/src/db/rewards.rs` | Database CRUD operations |
| `crates/lo-auth/src/rbac.rs` | Permission constants (`rewards:read/create/edit/delete`) and default-role membership |
| `apps/web/src/app/(main)/(app)/dashboard/rewards/layout.tsx` | `FeatureRouteGate feature="feature:rewards"` on the whole segment |
| `apps/web/src/app/(main)/(app)/dashboard/rewards/rewards-list.tsx` | Dashboard rewards list |
| `apps/web/src/app/api/rewards/route.ts` | Next.js proxy → GraphQL (list / create) |
| `apps/web/src/app/api/rewards/[id]/route.ts` | Next.js proxy → GraphQL (update / delete) |

---

## Features / Notifications

Source: https://docs.lumio.vision/features/notifications

# Notifications

## Overview

The notification system delivers in-app notifications to users with read/unread tracking and actionable items. Notifications are user-scoped (not account-scoped), supporting typed messages with optional actions such as accepting or declining team invites.

Each newly created notification carries a `type`, a stable variant key in `data.key`, a stored `title`, an optional stored `message`, additional `data` (JSONB), and an optional `actions` array defining available user actions. Older unmatched rows can lack `data.key`. The stored title and message normally provide English fallbacks; messages containing user text or server-localized content retain that content. Notifications track both `read_at` and `acted_at` timestamps to distinguish between viewed and resolved states.

## Architecture

```
Dashboard UI
    |
    v
Next.js API Proxy (/api/notifications)
    |
    v
GraphQL (NotificationQuery / NotificationMutation)
    |
    v
db::notifications (PostgreSQL)
```

Notifications are created server-side (e.g., when a team invite is sent) and consumed by the frontend via GraphQL queries. The notification list includes an unread count (`unreadCount` on GraphQL, `_meta.unread_count` on REST) for badge display without fetching all items.

Every notification read/write path - GraphQL and REST alike - runs `require_first_party_user`. A popout, overlay, shared-overlay, widget, or extension token bound to the owner is rejected: a user's notifications are private to that user (ZAF-469).

Notifications have no WebSocket channel; `channel_gate_for` in `crates/lo-websocket/src/gate.rs` defines no `notifications` channel type. The bell polls the query instead.

### Read state and display text

The bell fetches the latest ten notifications when it opens with unread items, then calls the existing bulk read mutation for **all** of the user's unread notifications, including those outside the ten shown. The unread badge clears immediately. Items that were unread when the bell opened remain highlighted for that open session. Other mounted bells clear their badges through the `lumio:notifications-read` window event. A failed bulk read refetches the count; if that also fails, the count from opening is restored. Opening with no unread items sends no bulk read request. The per-item read endpoint remains available to API clients and the Ideas Hub view action; there is no per-item or bulk read button in the bell. Delete all remains available.

`type` names the notification category, while `data.key` identifies its text variant. For example, `security_mfa_changed` covers both `security_mfa_enabled` and `security_mfa_disabled`. `apps/api/src/services/notification_types.rs` defines the variant keys in `keys` and lists them in `ALL_IN_APP_KEYS`; this is separate from `notification_types::ALL`, the delivery-preference registry. `db::notifications::create_notification` requires a key and stores it in `data.key`. Every value interpolated into a title or message must also live in `data`, so the UI can render it in the selected language. The English `title` and `message` remain stored as fallbacks.

The bell resolves text in the **current UI language** through `apps/web/src/lib/notification-text.ts`: `notifications.types.<data.key>` first, `notifications.types.<type>` next, then the stored title and message. A missing translation or missing interpolation value falls back to the stored text for that field. Messages with user-written text or server-localized content can have no translated message template and pass through unchanged. Action labels use `notifications.actions.<action>`. This UI language lookup is independent of the recipient-language rules for email.

The notification variant-key migration fills `data.key` on existing rows that match a known type, English title, and data shape; it marks those rows with `data.key_source: "backfill"`. Unmatched rows keep their stored text. For each new in-app variant, define a new key in `ALL_IN_APP_KEYS`, supply English and German text under `notifications.types.<key>` in `apps/web/messages/{en,de}.json`, and include every interpolated value in `data`. The registry test checks that every listed key has a title translation in both languages.

### Actionable Notifications

Some notifications include an `actions` array in JSONB format:

```json
[
  { "action": "accept_invite", "label": "Accept" },
  { "action": "decline_invite", "label": "Decline" }
]
```

An action with a `url` opens a page from the bell. The bell marks an unread notification as read, then follows a same-origin path beginning with `/` or an absolute HTTP(S) URL. It ignores unsafe URLs, including protocol-relative `//` paths and non-HTTP schemes. It does not call `executeNotificationAction` for a navigation action. Navigation actions include `view_idea`, `view_developer_application`, `view_developer`, `view_extension`, and `install_extension`.

An action without a `url` is sent to the action endpoint. The server checks that the notification belongs to the caller, that the action appears on the notification, and that it has not already been handled. It dispatches four invite actions:

| Action | Effect |
|--------|--------|
| `accept_invite` | Adds the user to the invited account with the invite's role. The bell switches to that account and opens `/dashboard`. |
| `decline_invite` | Deletes the account invite. If it is already gone, the notification is still handled. |
| `accept_team_invite` | Adds the user to the developer team with the invite's role, subject to the extension-development plan gate, expiry, use limit, and membership checks. The team owner is notified; the bell opens `/dashboard/extensions/teams/{team_slug}`. |
| `decline_team_invite` | Deletes an unused single-use invite. A multi-use or already-used invite remains available; an invite that is already gone is a no-op. The inviter is not notified. |

A successful dispatched action sets `acted_at` and `read_at` if needed. Its buttons disappear immediately in the bell, and the list is refreshed. A failed action shows an error toast with the server message. The API rejects a navigation action sent to the action endpoint with `400 NOTIFICATION_ACTION_NAVIGATES`; see [REST errors](/api-reference/rest-api#notifications) and [GraphQL errors](/api-reference/graphql#notifications).

## Notification Preferences

Users configure per-type delivery under **Settings → Notifications** (`/dashboard/settings/notifications`). Preferences are stored in the `user_notification_preferences` table. REST and GraphQL read the same registry in `apps/api/src/services/notification_types.rs`, including its locked flag, default channel and owner-only flag.

### Email appearance and opt-out

Email uses the C · Brief layout: a light letter with a text wordmark, a colored category line, a heading, fine separators, and a clear action button. Supporting mail clients show Lumio's dark colors; Gmail's mobile apps normally keep the light letter unchanged when the `light only` color setting is honored. Each message also includes its own inbox preview and a plain-text part. Images such as the logo, platform marks, and stream chart are embedded in the message. The footer explains why the message arrived and uses the recipient's language for the legal links.

The **Manage notifications** footer link appears only on email for a configurable notification type. It opens **Settings → Notifications**, where the recipient can choose Off, In-App, Email, or In-App + Email. Required or security notices are locked and cannot be switched off; their footer has no manage link. Direct transactional mail without a notification preference has no manage link either. The same [notification registry](/developer-guide/email-templates#footer-and-notification-preferences) determines both the setting and the footer link.

### Channels

| Value | In-app notification | Email |
|-------|:-------------------:|:-----:|
| `off` | No | No |
| `in_app` | Yes | No |
| `email` | No | Yes |
| `in_app_email` | Yes | Yes |

When no preference row exists, a configurable type uses its registry default. Locked types always send in-app and email. An unrecognized stored value or preference lookup error fails open to both channels.

### Email language and timezone

Every email is written in the **recipient's** resolved language and renders dates in the **recipient's** resolved timezone - never the language of whoever triggered the notification. A broadcast (e.g. a developer-application email fanned out to several administrators) resolves **per recipient**, so each administrator gets their own language.

Resolution is one rule, applied server-side in `apps/api/src/user_preferences.rs` (`resolve_email_locale` / `resolve_email_timezone`):

- **Language** = the user's `locale` if set to a concrete value (`en` / `de`), else the last browser-observed locale (`detected_locale`), else English.
- **Timezone** = the user's `timezone` if set to a concrete IANA name, else the last browser-observed timezone (`detected_timezone`), else UTC.

The `auto` sentinel means "follow the browser". A server-side mailer (a cron summary, a worker) has no browser request, so `auto` cannot be answered from a cookie or `Accept-Language` header; `detected_locale` / `detected_timezone` are the last values the web app observed and persisted (on change only, ZAF-1386) precisely so those mailers still land in the right language. A user who never opened the app in a browser resolves `auto` to English / UTC. An unknown or malformed stored value falls back to English (there is no German fallback template) rather than failing the send.

Numeric dates follow the user's `date_format` preset; month and weekday names follow the language. The stream-summary heading uses the recipient's timezone and time format for its time range. The recipient is always a `users` row (`users.email`); for `stream_summary` and `reconnect_required` that is the **account owner** (`accounts.owner_id`), not the actor who triggered it.

`detected_locale` / `detected_timezone` are readable on `me` / `GET /v1/users/me` and writable via `updateMe` / `PATCH /v1/users/me`, but they are **not** shown in the settings UI - they are an observation, not a user-facing preference.

### System-critical types

Certain types are hardcoded to always deliver and cannot be configured by the user. `should_notify` short-circuits to `(true, true)` for these before any lookup.

| Type | Hardcoded behaviour |
|------|---------------------|
| `invite`, `security_*`, `data_export_ready`, `account_deletion_scheduled` | Always in-app + email |
| `billing_payment_failed`, `billing_cancellation_received` | Always in-app + email; visible only to the channel owner |

### Known types registry

`notification_types::ALL` is what both protocols enumerate. Only unlocked types can be written:

| Type | Configurable | Default | Description |
|------|:------------:|---------|-------------|
| `security_new_login`, `security_mfa_changed` (including an authenticator app or passkey added or removed), `security_recovery_code_used`, `security_recovery_codes_regenerated`, `security_password_changed`, `security_login_method_changed`, `security_failed_attempts` | No | in-app + email | Personal security notices |
| `invite` | No | in-app + email | Account invitation |
| `account_role_changed`, `account_member_removed`, `support_identity_checked` | Yes | in-app or both | Account and support notices |
| `data_export_ready`, `account_deletion_scheduled` | No | in-app + email | Required privacy notices |
| `stream_summary`, `connection_reconnect_required` | Yes | in-app + email | Stream and connection notices |
| `billing_invoice_paid`, `billing_plan_changed` | Yes; owner only | in-app + email | Billing notices |
| `billing_payment_failed`, `billing_cancellation_received` | No; owner only | in-app + email | Required billing notices |
| `idea_mention` | Yes | in-app + email | Ideas Hub mention |

Other notification types are emitted by the platform but are **not** in this registry, so they have no preference row and always deliver at the fail-open default: `developer_application`, `developer_team_invite`, `developer_team_member`, `extension_access`, `extension_lifecycle`, and `extension_tester`. `shopify_data_request` (in-app only, to the channel owner, variant keys `shopify_data_request` / `_partial` / `_none`; see [Shopify → Compliance webhooks](./shopify.md#compliance-webhooks)) is written directly too and cannot be switched off: the owner has to answer the customer.

### Database

**Table: `user_notification_preferences`**

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Row ID |
| `user_id` | `UUID` (FK) | Owning user |
| `notification_type` | `VARCHAR(50)` | Notification type key (e.g. `idea_mention`) |
| `channel` | `VARCHAR(20)` | Delivery channel; `CHECK` constrained to `off`, `in_app`, `email`, or `in_app_email` |
| `updated_at` | `TIMESTAMPTZ` | Last write |

`UNIQUE (user_id, notification_type)`; writes go through an upsert on that pair.

### API

**GraphQL:**

| Operation | Args | Returns | Permission |
|-----------|------|---------|------------|
| `notificationPreferences` | - | `[NotificationPreference!]!` | Auth only (first-party) |
| `updateNotificationPreference` | `notificationType: String!`, `channel: String!` | `NotificationPreference!` | Auth only (first-party) |

The read merges the registry with the user's stored rows, so it always returns one entry per known type - including `locked: true` for `invite`, which is reported as `in_app_email` regardless of any stored row.

**REST:**

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/notifications/preferences` | Auth | List one preference entry per known type for the current user |
| `PATCH` | `/v1/notifications/preferences/{notification_type}` | Auth | Set the delivery channel for a notification type |

`PATCH` body: `{ "channel": "off" | "in_app" | "email" | "in_app_email" }`. Both protocols apply the same three validations, in order, with identical messages:

1. a locked type → `"System notifications cannot be configured"`
2. any type outside the registry → `"Unknown notification type"`
3. any other channel value → `"Invalid channel. Must be one of: off, in_app, email, in_app_email"`

On REST these surface as `400`; on GraphQL as a resolver error.

## Notification types

### `invite`

Fired when a member invite is created with `invited_user_id` (user-search invite flow) in the members dashboard. The invitee gets the in-dashboard notification immediately; in addition, if the invitee has an email on record (`users.email IS NOT NULL`) the same `AccountInvite` transactional template that the email-invite branch uses is sent as a fire-and-forget side channel.

**`data` shape:**

```json
{ "key": "invite", "inviteId": "<uuid>", "accountId": "<uuid>", "account_id": "<uuid>", "inviter_name": "<name>", "account_name": "<name>", "role_name": "<role>" }
```

**`actions`:**

| `action`          | Effect                                                                  |
|-------------------|-------------------------------------------------------------------------|
| `accept_invite`   | Adds the user to the account with the invite's role; marks notification acted. |
| `decline_invite`  | Deletes the `account_invites` row (the invite is revoked); marks notification acted. |

If an account invite was removed before the recipient declines it, the decline still marks the notification handled and writes no decline audit event.

### `idea_mention`

Fired when another user @mentions the recipient in an Ideas Hub comment. Delivery channel is determined by the recipient's `idea_mention` preference row (fail-open default: in-app + email). Dispatched fire-and-forget from `apps/api/src/services/idea_mentions.rs`.

**`data` shape** (keys are snake_case as stored):

```json
{ "key": "idea_mention", "idea_id": "<uuid>", "author_name": "<display_name>", "idea_title": "<title>" }
```

**`actions`:** a single entry, `{ "label": "View", "action": "view_idea", "url": "/hub/ideas/<idea_id>" }`. The bell opens this page; the action endpoint does not dispatch it.

### `stream_summary`

Fired after a stream session ends, delivering the history summary to the account owner. Configurable via the `stream_summary` preference key. Emitted by `apps/api/src/services/history/summary_email.rs`.

### Types outside the preferences registry

These types are created by their respective subsystems, are not user-configurable, and always deliver at the fail-open default:

| Type | Emitted when |
|------|--------------|
| `developer_application` | A developer application is submitted, approved, or rejected |
| `developer_team_invite` | A developer-team invite is created or accepted |
| `developer_team_member` | A developer-team member is removed or has their role changed |
| `extension_lifecycle` | An extension is registered, a version is submitted/approved/rejected/published, or an extension is suspended |
| `extension_access` | Access to an extension is granted or revoked for a user |
| `extension_tester` | A tester is invited or removed, or tester feedback is submitted |

An addressed `developer_team_invite` notification contains `data.invite_id` and `data.team_slug` and offers `accept_team_invite` / `decline_team_invite`. Its invite code stays out of the notification. The emailed invite link opens `/invite/dev/{code}` on the configured web app origin, where the recipient can accept by code. Both acceptance paths apply the same plan and invite validity checks.

## API

### GraphQL Queries

| Query | Args | Returns | Permission |
|-------|------|---------|------------|
| `notifications` | `limit: Int`, `offset: Int` | `NotificationList!` | Auth only (first-party) |
| `unreadNotificationCount` | -- | `Int!` | Auth only (first-party) |
| `notificationPreferences` | -- | `[NotificationPreference!]!` | Auth only (first-party) |

**`NotificationList`** includes:
- `items: [Notification!]!` -- Paginated list ordered by `created_at DESC`
- `total: Int!` -- Total notification count for pagination
- `unreadCount: Int!` -- Count of unread notifications

Default `limit` is 25, capped at 100; `offset` defaults to 0.

### GraphQL Mutations

| Mutation | Args | Returns | Permission |
|----------|------|---------|------------|
| `markNotificationRead` | `id: UUID!` | `Notification!` | Auth only (first-party) |
| `markAllNotificationsRead` | -- | `MarkAllReadResult!` | Auth only (first-party) |
| `deleteAllNotifications` | -- | `MarkAllReadResult!` | Auth only (first-party) |
| `executeNotificationAction` | `id: UUID!`, `action: String!` | `Notification!` | Auth only (first-party) |
| `updateNotificationPreference` | `notificationType: String!`, `channel: String!` | `NotificationPreference!` | Auth only (first-party) |

All mutations verify user ownership -- a user can only interact with their own notifications. A notification belonging to another user is reported as not found, never as forbidden.

### REST Endpoints

All paths live under `/v1`. Notifications are user-scoped - authentication is enough, no `resource:action` guard.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/notifications` | Auth | Paginated list; query params are `page` (1-based) and `limit` (default 25, clamped 1–100) |
| `PATCH` | `/v1/notifications/{id}/read` | Auth | Mark a notification as read |
| `POST` | `/v1/notifications/{id}/action` | Auth | Execute `accept_invite`, `decline_invite`, `accept_team_invite`, or `decline_team_invite` |
| `POST` | `/v1/notifications/read-all` | Auth | Mark all notifications as read |
| `POST` | `/v1/notifications/delete-all` | Auth | Delete all of the current user's notifications |
| `GET` | `/v1/notifications/preferences` | Auth | List one preference entry per known type for the current user |
| `PATCH` | `/v1/notifications/preferences/{notification_type}` | Auth | Set the delivery channel for a notification type |

`GET /v1/notifications` is the one REST endpoint whose envelope differs from the GraphQL shape: it returns `{ "data": [ … ], "_meta": { "total", "unread_count", "page", "limit", "pages" } }`, where GraphQL nests the same values under `NotificationList`.

### GraphQL Types

```graphql
type Notification {
  id: UUID!
  userId: UUID!
  type: String!
  title: String!
  message: String
  data: JSON!
  actions: JSON
  readAt: String
  actedAt: String
  createdAt: String!
}

type NotificationList {
  items: [Notification!]!
  total: Int!
  unreadCount: Int!
}

type MarkAllReadResult {
  updated: Int!
}

type NotificationPreference {
  notificationType: String!
  channel: String!
  locked: Boolean!
}
```

## Permissions

Notifications require authentication only (no account-level permissions), and the identity must be first-party. Any logged-in user can view and manage their own notifications. Ownership is enforced by the resolvers and handlers (`user_id` check).

## Database

### Table: `notifications`

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Notification ID |
| `user_id` | `UUID` (FK, `ON DELETE CASCADE`) | Target user |
| `type` | `VARCHAR(50)` | Notification type (e.g., `invite`) |
| `title` | `VARCHAR(255)` | English fallback title |
| `message` | `TEXT` | Optional stored detail message; English fallback or pass-through content |
| `data` | `JSONB` (default `'{}'`) | Variant key in `key` plus interpolation and action data |
| `actions` | `JSONB` | Optional array of available actions |
| `read_at` | `TIMESTAMPTZ` | When marked as read |
| `acted_at` | `TIMESTAMPTZ` | When an action was executed |
| `created_at` | `TIMESTAMPTZ` | Creation timestamp |

A partial index `idx_notifications_user_unread` on `(user_id, created_at) WHERE read_at IS NULL` backs the unread-count badge.

### DB Functions

`apps/api/src/db/notifications.rs`:

| Function | Description |
|----------|-------------|
| `list_notifications` | Paginated list for a user, ordered by `created_at DESC` |
| `count_notifications` | Total count for a user |
| `count_unread` | Count where `read_at IS NULL` |
| `get_notification` | Single notification by ID |
| `mark_as_read` | Sets `read_at = now()` |
| `mark_all_read` | Bulk update all unread for a user |
| `delete_all` | Delete every notification for a user |
| `mark_acted` | Sets `acted_at = now()` and `read_at = COALESCE(read_at, now())` |
| `mark_revoked_by_invite_id` | Resolve outstanding invite notifications when the backing invite disappears |
| `create_notification` | Insert a new notification |
| `delete_notification` | Delete by ID |

`apps/api/src/db/notification_preferences.rs`:

| Function | Description |
|----------|-------------|
| `get_preferences` | All stored preference rows for a user, ordered by type |
| `get_preference` | One stored row for a `(user, type)` pair |
| `upsert_preference` | Insert or update the channel for a `(user, type)` pair |
| `should_notify` | Resolve `(send_in_app, send_email)` for a `(user, type)` pair; fail-open |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/notifications.rs` | GraphQL queries, mutations, preference operations, and action dispatch |
| `apps/api/src/routes/notifications.rs` | REST handlers, known-type registry, and action dispatch |
| `apps/api/src/db/notifications.rs` | Database CRUD operations for notifications |
| `apps/api/src/db/notification_preferences.rs` | Preference storage and the `should_notify` helper |
| `apps/api/src/services/invite_notifications.rs` | Creates the `invite` notification and its email side channel |
| `apps/api/src/services/idea_mentions.rs` | Creates `idea_mention` notifications and emails |
| `apps/web/src/app/(main)/(app)/notification-bell.tsx` | Notification bell and dropdown |
| `apps/web/src/app/api/notifications/` | Next.js proxy routes for notifications and preferences |
| `crates/lo-auth/src/rbac.rs` | Permission registry (notification permissions were dropped - auth only) |

---

## Features / StreamElements Tokens

Source: https://docs.lumio.vision/features/se-tokens

# StreamElements Tokens

## Overview

The SE Tokens module manages StreamElements JWT tokens used for receiving tip/donation events via the StreamElements WebSocket API. Tokens are stored encrypted at rest and scoped per account+platform. Each token runs its own StreamElements WebSocket worker (keyed by token id), so an account can receive tips from several platforms at once. Creating or re-saving a token replaces that token's worker; deleting a token stops only that token's worker and leaves the account's other SE workers running.

Supported platforms: **Twitch**, **YouTube**, **Kick**.

## Architecture

```
Dashboard UI
    |
    v
Next.js API Proxy (/api/se-tokens)
    |
    +---> REST API (GET/POST/DELETE /v1/se-tokens)
    |         |
    |         +--> WorkerManager (start/stop SE WebSocket worker)
    |
    +---> GraphQL (SeTokenQuery / SeTokenMutation)
    |
    v
db::se_tokens (PostgreSQL, encrypted token storage)
```

### Token Lifecycle

1. **Create** -- User provides their StreamElements JWT token and platform. The token is encrypted with AES using a derived key from `auth.token_encryption_key` and stored via upsert (one token per account+platform).
2. **Worker Start** -- The REST layer starts a `StreamElementsConfig` worker via `WorkerManager`, passing the unencrypted token and its `se_tokens` row id for the WebSocket connection. Workers are keyed by token id, so re-saving a token replaces its worker instead of spawning a duplicate, and workers for the account's other platforms are untouched.
3. **List** -- Returns tokens with masked hints (first 4 + last 4 chars, middle replaced with `***`). The actual token value is never returned.
4. **Delete** -- Removes the token and stops that token's worker via `WorkerManager.stop_se_worker` (addressed by token id). Other SE workers for the account keep running.
5. **Boot Recovery** -- `list_all_accounts_with_tokens` is used at server startup to auto-start SE workers for all accounts with stored tokens.

### Token Masking

Tokens returned to clients show only a hint: `eyJh***ab12`. If the token is 8 characters or shorter, or decryption fails, `****` is returned instead.

## API

### REST Endpoints

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/se-tokens` | List all SE tokens (masked) | `se-tokens:read` + `feature:streamelements` |
| `POST` | `/v1/se-tokens` | Create/update an SE token | `se-tokens:create` + `feature:streamelements` |
| `DELETE` | `/v1/se-tokens/{id}` | Delete an SE token | `se-tokens:delete` + `feature:streamelements` |

Admin-panel counterparts (admin-scoped permissions, checked with
`require_permission` against the admin role set):

| Method | Path | Description | Permission |
|--------|------|-------------|------------|
| `GET` | `/v1/admin/accounts/{id}/se-tokens` | List any account's SE tokens (masked) | `se-tokens:read` |
| `DELETE` | `/v1/admin/accounts/{id}/se-tokens/{token_id}` | Delete an SE token on any account | `se-tokens:delete` |

#### POST /v1/se-tokens

```json
{
  "platform": "twitch",
  "token": "eyJhbGciOiJI...",
  "label": "My SE Token"
}
```

**Validation:**
- `platform` must be one of: `twitch`, `youtube`, `kick`
- `token` must not be empty

**Response (201):** Returns the created token with masked hint and starts the SE worker.

### GraphQL Queries

| Query | Args | Returns | Permission |
|-------|------|---------|------------|
| `seTokens` | -- | `[SeToken!]!` | `se-tokens:read` + `feature:streamelements` |
| `adminSeTokens` | `accountId: UUID!` | `[AdminSeToken!]!` | admin `se-tokens:read` |

### GraphQL Mutations

| Mutation | Args | Returns | Permission |
|----------|------|---------|------------|
| `createSeToken` | `platform: String!`, `token: String!`, `label: String` | `SeToken!` | `se-tokens:create` + `feature:streamelements` |
| `deleteSeToken` | `id: UUID!` | `Boolean!` | `se-tokens:delete` + `feature:streamelements` |
| `adminDeleteSeToken` | `accountId: UUID!`, `tokenId: UUID!` | `Boolean!` | admin `se-tokens:delete` |

Both protocols compose the same two gates: the `feature:streamelements` plan flag
and the RBAC permission (`FeatureGuard::new("feature:streamelements").and(PermissionGuard::new(…))`
on GraphQL; `auth.require_permission(…)` + `require_feature(…)` on REST). An
account whose plan does not carry `feature:streamelements` cannot reach any of
these operations. The admin twins use `AdminPermissionGuard` / the admin
`require_permission` and carry no feature gate - they act across accounts.

Note: The GraphQL layer does not have access to `WorkerManager`, so worker lifecycle is handled exclusively by the REST endpoints. `createSeToken` and `deleteSeToken` on GraphQL write the encrypted row but do **not** start or stop the StreamElements WebSocket worker; use the REST endpoints when the worker must follow the change immediately. Boot recovery picks up GraphQL-created tokens on the next API start.

### GraphQL Types

```graphql
type SeToken {
  id: UUID!
  platform: String!
  tokenHint: String!
  label: String
  createdAt: String!
  updatedAt: String!
}

"""SE token (masked) in admin view — no updatedAt."""
type AdminSeToken {
  id: UUID!
  platform: String!
  tokenHint: String!
  label: String
  createdAt: String!
}
```

### WebSocket

SE tokens have no channel of their own. The tips/donations they unlock arrive on
the account's `events:{account_id}` stream (`events:read`, see
`crates/lo-websocket/src/gate.rs`) as normal platform events.

## Permissions

| Permission | Description |
|------------|-------------|
| `se-tokens:read` | List SE tokens |
| `se-tokens:create` | Create/update SE tokens |
| `se-tokens:delete` | Delete SE tokens |

Included in: Owner, Administrator roles. Moderator receives none of the three.

The same three keys double as **admin** permissions for the cross-account admin
surface (`adminSeTokens` / `adminDeleteSeToken` and their REST twins), where they
are resolved against the caller's admin roles rather than their account roles.

### Feature flag

Every account-scoped SE-token operation additionally requires the
`feature:streamelements` flag on the account's plan (category `feature`, label
"StreamElements"). Without it both protocols answer `FEATURE_DISABLED`.

## Database

### Table: `se_tokens`

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Token ID |
| `account_id` | `UUID` (FK) | Owning account |
| `platform` | `TEXT` | Platform identifier |
| `token` | `TEXT` | Encrypted JWT token |
| `label` | `TEXT` | Optional user label |
| `created_at` | `TIMESTAMPTZ` | Creation timestamp |
| `updated_at` | `TIMESTAMPTZ` | Last update timestamp |

**Unique constraint:** `(account_id, platform)` -- one token per platform per account.

### DB Functions

| Function | Description |
|----------|-------------|
| `list_tokens` | List all tokens for an account, ordered by platform |
| `upsert_token` | Insert or update on `(account_id, platform)` conflict |
| `delete_token` | Delete by ID with account ownership check |
| `has_tokens` | Check if an account has any tokens |
| `list_all_accounts_with_tokens` | Boot-time recovery: all accounts grouped with their tokens |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/se_tokens.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/se_tokens.rs` | REST endpoints with worker lifecycle management |
| `apps/api/src/db/se_tokens.rs` | Database CRUD operations |
| `crates/lo-auth/src/rbac.rs` | Permission constants (`se-tokens:read/create/delete`) |

---

## Features / Sessions

Source: https://docs.lumio.vision/features/sessions

# Sessions

## Overview

The sessions module provides user session management, allowing users to view their active sessions and revoke individual sessions or all other sessions. Sessions are created during OAuth login and are tied to refresh tokens via a SHA-256 token hash.

On **Security → Sessions** (`/dashboard/settings/security/sessions`) each session shows its device, sign-in method, whether 2FA was verified (including a passkey sign-in, which completes 2FA), approximate location, IP address, and last activity. A value Lumio cannot resolve is shown as **Unknown**. The current session is marked from `Session.isCurrent` and cannot be revoked from its own row. Other sessions can be revoked individually or selected together. The page can export session details as CSV or JSON. Popout tokens are separate credentials and do not appear in this table.

## Architecture

```
ID App (NextAuth) ──> OAuth Login
    |
    v
exchangeToken mutation
    |
    +--> create_session (DB)
    +--> cache_session (Redis)
    +--> Issue JWT with session_id claim
    |
    v
Dashboard UI
    |
    v
GraphQL (SessionQuery / SessionMutation)
    |
    v
db::auth (PostgreSQL sessions table)
```

### Session Lifecycle

1. **Creation** -- During `exchangeToken`, a session row is created with the user ID, active account ID, SHA-256 hash of the refresh token's `jti`, client IP, user agent, and expiry timestamp. The session is also cached in Redis for fast lookup. The **client IP and user agent are the end user's**, not the web server's: the login almost always reaches the API through a Next.js service (apps/id, web, admin), so both are resolved from what that first-party hop forwards -- `X-Lumio-Client-IP` (`lo_api::client_ip`, ZAF-1208) and `X-Lumio-Client-UA` (`lo_api::client_ua`, ZAF-1414), each honoured **only** for a caller holding the `X-Internal-Token` secret. Node's `fetch` sends `User-Agent: node`, so without the forwarded UA the device would read `node` for every web login. Both channels depend on `INTERNAL_TOKEN` being provisioned on the API and the matching secret on web/admin/id; if it is unset the hop is not trusted and the IP **and** UA fall back to the edge/server values. See [Audit events → How the client User-Agent is resolved](../developer-guide/audit-events.md#how-the-client-user-agent-is-resolved).
2. **JWT Embedding** -- The session ID is embedded in the JWT via `create_token_with_session`, allowing the API to identify which session corresponds to the current request.
3. **Refresh** -- During `refreshToken`, the session is looked up by token hash. A new JWT is issued with the same session ID. A new refresh token is issued with the remaining session lifetime, and the session's `token_hash` is rotated to invalidate the old refresh token.
4. **Account switch / create / dissolve** -- These paths (`updateMe` with `activeAccountId`/`clearActiveAccount`, `createAccount`, `dissolveAccount`, and their REST twins) rewrite `active_account_id` and hand back a **fresh JWT** so the cookie reflects the new account (GraphQL `dissolveAccount` returns no token; its REST twin does). A JWT is only minted for a caller that already holds an interactive session (ZAF-1922): the switch / clear itself is session-only, and `createAccount` returns `token: null` to a caller without one (`DELETE /v1/accounts/{id}` refuses such a caller: dissolving needs a step-up, which only a session can hold — ZAF-2052). The *switch* and *create* writes are scoped to the **caller's own session row only** (`WHERE id = <session_id>`, via `db::auth::set_session_active_account`): account selection is per-device, so switching on one device never re-points the user's other sessions (ZAF-1416). A session-less caller of `createAccount` (API-key auth) persists nothing, rather than falling back to a user-wide write. *Dissolve* is the deliberate exception — it clears `active_account_id` **account-wide** so no other device is left holding a deleted account. The replacement JWT is minted with `lo_auth::reissue_session_token` (a `create_token_with_session` wrapper that returns `None` for a caller without a `session_id`) and carries the **same `session_id`** as the incoming cookie - the session itself does not change, only which account it is acting on. Preserving the `session_id` here is what keeps the post-switch cookie (and any WebSocket token derived from it) subject to the revocation gate below (ZAF-908).
5. **Logout** -- `logout(refreshToken: String!)` deletes the session from both PostgreSQL and Redis by token hash. `logoutSession` does the same for the *current* session, identified from the `session_id` JWT claim, so no refresh token has to be handed back. REST twin: `POST /v1/auth/logout`.
6. **Revocation** -- Users can delete specific sessions or all sessions except the current one.

### Revocation gate

A signature-valid JWT is not sufficient to authorize a request: the auth middleware (`crates/lo-api/src/middleware/auth.rs`) additionally checks that the token's `session_id` still points at a live `sessions` row (`SELECT EXISTS(... WHERE id = $1 AND expires_at > now())`, a positive result cached for 60 s in Redis under `lumio:session_valid:{session_id}`). When the row is gone - logout, "revoke all other sessions", or expiry - the token stops working before its `exp`, and the request resolves to `Anonymous`. Every revoke path (REST and GraphQL logout, single-session revoke, revoke all other sessions, sign-out everywhere, user deletion) also deletes the cache entry, so a revoked session is rejected on its next request; the 60 s TTL only bounds a failed delete. Expiry is not evicted - a cached entry can outlive `expires_at` by up to 60 s.

This gate **only inspects tokens that carry a `session_id`**. That is why every session-cookie mint - login, refresh, and the account switch/create/dissolve re-mints - must go through `create_token_with_session` (the re-mints via `reissue_session_token`): a token minted without a `session_id` is structurally exempt from revocation and would survive a "log out everywhere" until its 24 h `exp`. For the same reason a user JWT without a `session_id` never counts as an interactive session: `AuthContext::session_user_id()` returns nothing for it, so it fails every [session-only gate](../api-reference/authentication.md#session-only-surfaces). (Refresh tokens, popout-session JWTs, and the reserved WS-scoped token legitimately carry no `session_id`; they are gated by other means - the `/auth/refresh`-only `typ` claim, the origin popout-token `revoked_at` check, etc.)

### Session Filtering

Only non-expired sessions are returned by `list_sessions_for_user` (filtered by `expires_at > now()`).

## API

### GraphQL Queries

| Query | Args | Returns | Permission |
|-------|------|---------|------------|
| `sessions` | -- | `[Session]` | Auth (first-party) |

Returns all active (non-expired) sessions for the current user, ordered by `created_at DESC`.

### GraphQL Mutations

| Mutation | Args | Returns | Permission |
|----------|------|---------|------------|
| `deleteSession` | `id: UUID` | `Boolean` | Auth (first-party) |
| `deleteAllOtherSessions` | -- | `Boolean` | Auth (first-party) |

- `deleteSession` verifies the session belongs to the current user before deletion.
- `deleteAllOtherSessions` uses the `session_id` from the JWT to identify the current session and deletes all others for the user.

### GraphQL Types

The response also carries `authMethod`, `mfaVerifiedAt`, `lastUsedAt`, `country` and `city` (`auth_method`, `mfa_verified_at`, `last_used_at`, `country`, `city` in REST). The location is optional GeoIP enrichment, and the last-activity timestamp advances on session refresh. The dashboard does not label popout tokens as sessions.

```graphql
type Session {
  id: UUID!
  userId: UUID!
  activeAccountId: UUID
  activeAccountName: String
  ipAddress: String
  userAgent: String
  expiresAt: String!
  createdAt: String!
  isCurrent: Boolean!
}
```

`isCurrent` is `true` when the row's id equals the `session_id` JWT claim of the request - parity with the REST `SessionResponse.is_current` (ZAF-1412). It is computed in the `sessions` resolver from the auth context, not stored; a non-session principal (e.g. a user API key) leaves every row `false`.

`activeAccountName` is the display name of the account the session currently has selected (`activeAccountId`), resolved by a `LEFT JOIN accounts` in `list_sessions_for_user` (ZAF-1418). It is `null` whenever `activeAccountId` is `null` - API-key or fresh sessions carry no selection, and account dissolution clears the column - and the LEFT JOIN keeps such rows in the list rather than dropping them. Parity with the REST `SessionResponse.active_account_name`.

Note: The `token_hash` field is present in the database row but is not exposed via GraphQL.

### REST Endpoints

Sessions are user-scoped; the REST handlers enforce ownership in code rather than via an RBAC permission string - identically to GraphQL. All paths live under `/v1/users/me/sessions`.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/users/me/sessions` | Auth | List active (non-expired) sessions for the current user |
| `DELETE` | `/v1/users/me/sessions/{id}` | Auth | Revoke one session (must belong to the current user) |
| `DELETE` | `/v1/users/me/sessions` | Auth | Revoke all other sessions (keeps the current one) |

Response bodies are snake_case. The REST `SessionResponse` carries the same
account-selection fields as the GraphQL `Session` type; the only remaining
difference is `user_id`, which REST leaves implicit (the endpoint is already
scoped to `/users/me`):

| Field | GraphQL `Session` | REST `SessionResponse` |
|-------|-------------------|------------------------|
| `id` | yes | yes |
| `userId` / `user_id` | yes | no |
| `activeAccountId` / `active_account_id` | yes | yes (ZAF-1418) |
| `activeAccountName` / `active_account_name` | yes (ZAF-1418) | yes (ZAF-1418) |
| `ipAddress` / `ip_address` | yes | yes |
| `userAgent` / `user_agent` | yes | yes |
| `expiresAt` / `expires_at` | yes | yes |
| `createdAt` / `created_at` | yes | yes |
| `isCurrent` / `is_current` | yes (ZAF-1412) | yes - `true` when the row's id equals the `session_id` JWT claim |

The `token_hash` column is exposed by neither protocol. Both protocols apply the
same first-party gate (`require_first_party_user`) and the same own-scoped row
selection, so authorization is at parity, and `active_account_id` /
`active_account_name` now carry identical values on both (ZAF-1418).

### WebSocket

There is no session channel: `crates/lo-websocket/src/gate.rs` maps no `sessions` channel type, so `channel_gate_for("sessions")` returns `ChannelGate::Unknown` and any subscription attempt is rejected. Session changes are polled through the query, not pushed.

## Permissions

Session read and revoke are **own-scoped, not account-scoped**: every endpoint and
resolver selects rows by the acting user's own id, so no RBAC grant gates them on
either protocol. Both surfaces require a **first-party** principal - a logged-in
session or the user's own API key; a popout / overlay / shared-overlay / widget /
extension token is rejected with `FORBIDDEN` (ZAF-469), even when bound to the
account owner.

This is why the session list works with **no active account selected** (the
personal profile in the account switcher): an account-scoped guard would see an
empty permission set there and hide the user's own sessions.

There is **no** account-role permission for session management. Session reads and
revokes are own-scoped: they select strictly by the acting user's id and gate only
on `AuthGuard` plus the first-party principal check. The former `sessions:read` /
`sessions:delete` account permissions were **removed** in ZAF-1094 - they were
assignable in the role editor but no handler ever enforced them, so granting or
withholding them changed nothing about who can see or revoke their own sessions.

## Database

### Table: `sessions`

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Session ID |
| `user_id` | `UUID` (FK) | Session owner |
| `active_account_id` | `UUID` (FK) | Currently selected account |
| `token_hash` | `TEXT` | SHA-256 hash of the refresh token's `jti` |
| `ip_address` | `INET` | Client IP address (stored as `inet`, returned via `host()`) |
| `user_agent` | `TEXT` | Client user agent string |
| `expires_at` | `TIMESTAMPTZ` | Session expiry |
| `created_at` | `TIMESTAMPTZ` | Creation timestamp |

### DB Functions

| Function | Description |
|----------|-------------|
| `create_session` | Insert a new session with token hash, IP, user agent, and expiry |
| `list_sessions_for_user` | List non-expired sessions ordered by `created_at DESC`, each enriched with the selected account's display name via `LEFT JOIN accounts` (returns `SessionListRow`, ZAF-1418) |
| `find_session_by_token_hash` | Lookup by token hash (used during refresh) |
| `rotate_session_token_hash` | Update token hash during refresh token rotation |
| `delete_session_by_id` | Delete a specific session with user ownership check |
| `set_session_active_account` | Set/clear `active_account_id` on the **caller's own** session row only (per-device selection, ZAF-1416); skips the write when there is no session |
| `delete_other_sessions` | Delete all sessions except the specified one |
| `delete_session` | Delete by token hash (used during logout) |
| `delete_all_sessions_for_user` | Delete all sessions (used for account dissolution) |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/sessions.rs` | GraphQL queries and mutations |
| `apps/api/src/graphql/auth.rs` | Token exchange and refresh (session creation) |
| `apps/api/src/db/auth.rs` | Session CRUD and token hash operations |
| `crates/lo-auth/src/jwt.rs` | JWT creation with embedded session ID |
| `crates/lo-auth/src/api_key.rs` | `hash_token` function (SHA-256 hashing) |

---

## Features / Audit Log

Source: https://docs.lumio.vision/features/audit-log

# Audit Log

## Overview

The personal log records email sign-in setup and confirmation, password changes and resets, 2FA activation/deactivation, authenticator app and passkey additions/removals, and recovery-code use, step-up confirmations, export requests/downloads and deletion scheduling/cancellation. Account events include member departure and subscription cancellation requests. The operator log records support-code reveal/check and manual 2FA reset. A code, password, link token or raw email address is never written to audit metadata.

The dashboard offers CSV/JSON export for the personal and account logs. The personal export is self-only; account export requires `audit-log:read`. A selected export accepts up to 1,000 event IDs. The regular GraphQL and REST readers remain paginated; file exports are REST-only.

The audit log is Lumio's tamper-evident record of security- and
administration-relevant actions. Every row in the `audit_events` table carries an
explicit **`scope`** column - `user`, `account`, or `system` - set by the writer
and never inferred at read time. Scope partitions the log into three audiences,
each with its own read surface, so a reader only ever sees the events meant for
them.

| Scope | Audience | Example events |
|-------|----------|----------------|
| `user` | The individual user, self-only | Personal-security rows keyed to the authenticated user |
| `account` | An account's members, gated to that account | Role/permission changes, member-role assignment, channel connections |
| `system` | Platform operators | Instructed GDPR chat erasures (one per instructing channel) and platform-operator rows |

**Scope isolation** is enforced by each reader: the user reader returns only the
caller's `scope=user` rows, the account reader returns only the caller's account's
`scope=account` rows, and system rows are only available through the
operator-only admin view.

**Overlap rule:** an account-context action that has an actor lives **only** in
the account log (where the actor is shown), never additionally in the user log;
personal-security events live **only** in the user log. An event is written to
exactly one scope.

## Permission

Reading a single account's audit log requires the account-scope
`audit-log:read` permission. In the default roles it is held by **Owner** and
**Administrator** only - **Moderator** does not carry it.

This account permission shares its string with an admin-scope `audit-log:read`
that gates the operator/system log, but the two are **distinct** grants enforced
by different guards (the account guard checks the account role; the admin guard
checks the admin role). Holding the account permission never unlocks the system
log, and vice-versa. The self-service user log needs no permission at all - only
a first-party session.

## Reading the log

### Your personal log (`user` scope)

Your own `scope=user` rows. This is **self-service** - it needs no RBAC
permission - but it does require a **first-party principal**: a logged-in session
or your own API key. A popout, overlay, widget, or extension token cannot read
it. Current writers record successful logins, failed login attempts tied to a
known user, OAuth grant consent, and your personal API-key
(`lm_usr_*`) create/rename/revoke/rotate.

- **GraphQL:** `myAuditLog(filter: AuditLogFilter!): AuditLogPage!`
- **REST:** `GET /v1/me/audit-log`

### Your account's log (`account` scope)

Tenant actions on the active account. Current emitters write role and permission
changes, member-role assignment, channel-connection add/remove rows,
account-scoped GDPR erasure rows, and account service-key (`lm_svc_*`) lifecycle
(create / rename / revoke / rotate). Requires the account-scope `audit-log:read`
permission (Owner and Administrator by default). Returns only the active
account's rows.

- **GraphQL:** `accountAuditLog(filter: AuditLogFilter!): AuditLogPage!`
- **REST:** `GET /v1/account/audit-log`

### Operator log (`system` scope)

Operator and cross-account rows. This is the admin surface, gated by the
admin-scope `audit-log:read`; see [Admin → Audit Log](../admin/audit-log.md).

- **GraphQL:** `adminAuditLog(filter)`
- **REST:** `GET /v1/admin/audit-log`

## Filtering and pagination

Both the user and account readers share the same filter and paginated response
shape, exposed identically on GraphQL and REST (same fields, permission,
validation and errors).

| REST query param | GraphQL filter field | Meaning |
|------------------|----------------------|---------|
| `page` | `page` | Page number (default 1). |
| `limit` | `limit` | Page size (REST default 50, clamped `1..=200`). |
| `type` | `eventType` | Exact event-type match. |
| `from` | `dateFrom` | Only events at/after this instant (RFC-3339; an unparseable value is ignored). |
| `to` | `dateTo` | Only events at/before this instant (RFC-3339; an unparseable value is ignored). |

A page (`AuditLogPage`) carries `items`, `total`, `page`, and `limit`; the REST
response additionally includes `total_pages`.

The account log's Type filter includes `account:discord_guild_connected`, `account:discord_guild_disconnected`, `account:discord_guild_bot_removed`, and `account:discord_guild_reconnected`. The admin log offers the same four account event types.

Each `AuditEvent` exposes `id`, `accountId`, `userId`, `eventType`, `scope`,
`ipAddress`, `userAgent`, `country`, `city`, `metadata` (a JSON string),
`createdAt`, and `resolvedNames`. The `country` / `city` fields are filled by the
optional GeoIP service and are empty when it is disabled or cannot resolve the
client IP. `userAgent` carries the raw request `User-Agent` string and is
populated on **every** event that originates from a client request - not just
`user:login*` (ZAF-1412); the dashboard and admin viewers parse it to show the
device, browser, and operating system. It is empty only for events with no
originating request (background workers, the Stripe webhook) and for rows past
their retention window (see [Retention](#retention), which nulls it in place).
Events written from the Shopify admin (`/v1/shopify/embedded/*`) carry the
user agent but never `ipAddress`, `country` or `city`: that hop is not trusted
to name a client IP, so `shopify_user_id` and `shop_host` in the metadata
identify who acted.

`resolvedNames` (REST `resolved_names`) is a read-time list of
`{ id, kind, displayName }` that resolves the entity UUIDs an event references —
the actor plus an allowlist of metadata ids (`target_user_id`, `member_id`,
`from_account_id`, `to_account_id`, `target_account_id`, `role_id`) - to their
display name (`kind` ∈ `user` | `account` | `role`). It is computed once per page
so the UI can show a name alongside every UUID, not just the actor. Deleted or
unknown entities are omitted from the list, so their raw UUID stays on the wire
and the UI falls back to it (ZAF-1233).

### In the dashboard and admin viewers

The dashboard viewers (**My activity**, **Account audit log**) and the admin
operator viewer render `resolvedNames` as **name + UUID together**, never one
instead of the other (ZAF-1234):

- **Actor column** (account + operator logs): the acting user's display name
  followed by the short UUID; the full UUID is on hover.
- **Device column:** the raw `userAgent` is parsed at render time into a compact
  device / browser / operating-system summary (e.g. "Chrome 141 · macOS"; text
  only in the dashboard tables, with a device icon in the admin operator log),
  alongside the existing **IP address** and **Location** columns. The parser never shows the raw value and never guesses: a user agent
  it cannot read at all — absent, a non-browser client (`node`, `undici`,
  `axios`), a legacy web-server string, or junk — renders as the localized
  **Unknown** ("Unbekannt" in German), and a missing IP renders the same way.
  Partial information is kept rather than dropped: a recognized browser with an
  unreadable OS shows "Chrome 141 · Unknown", and vice-versa. The full raw
  user-agent string remains available in the expanded row detail as the forensic
  source of truth.
- **Expanded row detail:** above the raw metadata JSON, a resolved-entities list
  annotates the actor and every allowlisted metadata id
  (`target_user_id`, `member_id`, `from_account_id`, `to_account_id`,
  `target_account_id`, `role_id` - e.g. the `from`/`to` accounts of an
  active-account switch) with its resolved name. The raw JSON block is kept
  intact underneath.
- **Deleted / unknown entity:** when an id is not in `resolvedNames` (the entity
  was deleted or is unresolvable), the viewer shows the short UUID plus a
  localized "deleted user / account / role" label - never a blank.

## Event catalog

Every audit event type is a wire string. Most catalog entries use
`scope:action` naming; the two GDPR erasure strings keep their historical
underscore names.

| Event type | Scope | Current writer |
|------------|-------|----------------|
| `chat_pii_erasure` | `account` / `system` | `account`: account dissolution and admin account delete; `system`: admin chat-subject or single-record erasure on one channel's instruction, and the Lumio-only erasure |
| `youtube_member_erasure` | `system` | Admin YouTube member-channel erasure on one channel's instruction |
| `account:role_created` | `account` | Role creation |
| `account:role_updated` | `account` | Role edits, including permission changes |
| `account:role_deleted` | `account` | Custom role deletion |
| `account:member_role_assigned` | `account` | Member role assignment. Metadata also counts the member's live personal API keys (`personal_keys_affected`) and popout tokens (`popout_tokens_affected`), which follow the new role from the next request; `null` when the count could not be read |
| `account:member_removed` | `account` | A member was removed from the account (target user in metadata) |
| `account:member_left` | `account` | A member left their own account; actor is that member. Metadata: `membership_id` |
| `account:invite_created` | `account` | An account invite was created (invite `email` and `code` are never stored in metadata) |
| `account:invite_revoked` | `account` | An account invite was revoked/deleted |
| `account:invite_accepted` | `account` | An invite was accepted; actor is the joining user, scoped to the account joined. Bell acceptance records `source: "notification"` with `membership_id`, `invite_id`, and `role_id`; never the invite code or email |
| `account:invite_declined` | `account` | The invitee declined from the bell and the account invite was deleted. Actor is the invitee; metadata `invite_id`, `role_id`, `source: "notification"`. A missing invite is a no-op and writes no event |
| `account:subscription_cancel_requested` | `account` | An account member requested cancellation of a subscription. Metadata: `plan`, `period_end`, cancellation `kind`, and `has_reason`; the reason itself is not stored |
| `account:dissolved` | `account` | An account was irreversibly dissolved (CASCADE delete); actor is the owner. Metadata `via`: `"immediate"` (the owner dissolved without a grace period, `graceDays: 0` included) or `"scheduled"` (the account security worker at the end of the grace period; actor is the owner who scheduled it), plus `deleted_history_row_count` (stream-history rows deleted) and `deleted_object_count` / `pending_object_count` (stored files deleted / left queued for retry) |
| `account:dissolution_scheduled` | `account` | The owner scheduled the account's dissolution (`scheduleAccountDissolution` / `POST /v1/accounts/{id}/dissolution`); actor is the owner. Metadata: `grace_days`, `scheduled_for` |
| `account:dissolution_cancelled` | `account` | The owner cancelled a scheduled dissolution (`cancelAccountDissolution` / `DELETE /v1/accounts/{id}/dissolution`); actor is the owner. Metadata: `scheduled_for` (the cancelled date) |
| `account:identity_changed` | `account` | The channel's name/picture source, own name or own picture changed (`setAccountIdentitySource` / `PUT /v1/accounts/{id}/identity-source`, `updateAccountName` / `updateAccount` / `PATCH /v1/accounts/{id}/name`, `POST /v1/accounts/{id}/avatar`, `removeAccountAvatar` / `DELETE /v1/accounts/{id}/avatar`); actor is the caller. Metadata: `changed` (list of `source`, `name`, `avatar`; `["source", "avatar"]` when switching back to a connection deleted an upload), `source_kind`, `source_platform` - never a name or URL. Not written when nothing changed |
| `account:connection_added` | `account` | Channel OAuth completion on first connect and reconnect. Metadata: `platform`, `credential_source`, and, for a platform with optional channel scopes, `optional_scopes_granted` (the granted optional scope names, possibly `[]`) — never tokens or the full grant |
| `account:connection_removed` | `account` | Channel disconnect |
| `account:integration_connected` | `account` | A Shopify store was linked: confirmed in Lumio (actor = that member) and completed in the Shopify admin. Metadata `platform`, `shop_host`, `scopes`, `source` (`shopify_admin`), `shopify_user_id` |
| `account:integration_disconnected` | `account` | A Shopify store connection was removed: by a member (`disconnectShopify` / `DELETE /v1/connections/shopify`), from the Shopify admin (no actor, + `shopify_user_id`) or by Shopify's `app/uninstalled` webhook (no actor). Metadata `platform`, `shop_host`, `reason` (`user` / `shopify_admin` / `app_uninstalled`) |
| `account:shopify_settings_updated` | `account` | A Shopify setting (`customer_display`, `show_items` or `show_price`; one event per changed value) changed: from Lumio (actor = the member, `source: lumio`) or from the Shopify admin (no actor, `source: shopify_admin` + `shopify_user_id`). Metadata `platform`, `shop_host`, `setting`, `from`, `to`, `source` |
| `account:shopify_order_name_hidden` | `account` | A member hid the buyer name of one Shopify order (both of its events). Metadata `platform`, `event_id`; never the name |
| `account:shopify_data_request` | `account` | Shopify forwarded a customer's data request for the account's store; the owner got an in-app notice (no actor). Metadata `platform`, `shop_host`, `orders_requested`, `orders_found`, `orders_with_label` (counts only) |
| `account:shopify_customer_redacted` | `account` | The listed orders' events were deleted (`customers/redact`, no actor), after the second pass. Metadata `platform`, `shop_host`, `orders` (count) |
| `account:shopify_shop_redacted` | `account` | The store's events were deleted up to the uninstall (`shop/redact`, no actor), after the second pass. Metadata `platform`, `shop_host` |
| `account:youtube_revenue_data_deleted` | `account` | Stored YouTube Analytics revenue rows were erased after disconnect, scope loss, revocation, an unconfirmed authorization, a deleted video, a deleted stream report or account deletion. Metadata: `platform: "youtube"`, `reason`, `rows` (deleted row count); never an amount |
| `account:discord_guild_connected` | `account` | A Discord server was connected to the account through the verified invite of the Lumio bot (*Connections → Discord*). Actor = the inviting member. Also written for the new account when it takes over a server whose bot had been removed from another account (`reason: taken_over`). Metadata: `guild_id`, `guild_name` - never the invite's user token |
| `account:discord_guild_disconnected` | `account` | A Discord server was disconnected (`disconnectDiscordGuild` / `DELETE /v1/discord-guilds/{guild_id}`, `bot-connections:delete`). Also written, without an actor, for the previous account of a takeover (`reason: taken_over`). Metadata: `guild_id`, `guild_name` |
| `account:discord_guild_bot_removed` | `account` | The Lumio bot was removed from a connected Discord server on Discord's side. No actor. The connection is marked, not deleted, and keeps its settings until a reconnect or the 90-day cleanup. Metadata: `guild_id`, `guild_name` |
| `account:discord_guild_reconnected` | `account` | A Discord server already connected to the account was invited again (after the bot was removed, or to grant missing permissions); its settings stay. Actor = the inviting member. Metadata: `guild_id`, `guild_name` |
| `account:extension_kill_switch_set` | `account` | The extension kill switch was set or cleared (`POST /v1/bot-modules/kill` / `setBotModuleKillSwitch`, `bot-modules:edit`). Metadata: `killed` only |
| `account:extension_moderation` | `account` | An installed extension deleted a chat message, or banned, unbanned or timed out a chat user: a widget or app through `useLumioAction` (`chat:delete` / `chat:ban` / `chat:unban` / `chat:timeout`, REST `POST /v1/extension-installs/{install_id}/actions/{action}` or GraphQL `executeExtensionAction`), or a bot module through its handler actions or moderation decisions (`chat:ban` / `chat:unban` / `chat:timeout`; a bot module's message deletions are recorded in its install log only, not here). The account's bot carried it out; written only when the platform applied it. No actor user; no origin for bot modules. Metadata: `source` (`extension` or `bot_module`), `extension_id`, `install_id`, `action`, `platform`, `target_user_id` (none for delete), `duration_secs` (timeout only) - never the reason text |
| `account:extension_uninstalled` | `account` | An extension was uninstalled (`DELETE /v1/extension-installs/{id}` / `uninstallExtension`, `extension-store:uninstall`). Metadata: `extension_id`, `install_id`, `delete_data_immediately` (`true` = the account's extension data was deleted at once, `false` = 30-day retention) |
| `account:connection_reconnect_required` | `account` | A channel/bot token is dead: a refresh failed terminally (Token Refresh Worker), or a platform worker's forced refresh after an HTTP 401 could not produce an accepted token (Twitch EventSub, Kick subscriptions); the connection was auto-flagged `reconnect_required` |
| `account:connection_credentials_upserted` | `account` | Per-account OAuth app credentials (client_id/secret) created/updated via `saveAppCredentials` / `PUT /v1/connections/credentials/{platform}` (`connections:create`); the **credential** level, distinct from `account:connection_added` (token level). Metadata: `platform`, `credentials_id`, `updated` - never the client_id/client_secret |
| `account:connection_credentials_deleted` | `account` | Per-account OAuth app credentials removed via `deleteAppCredentials` / `DELETE /v1/connections/credentials/{platform}` (`connections:delete`); the DELETE counterpart of `account:connection_credentials_upserted`. The same call also disconnects the channel, which emits `account:connection_removed`. Fires only on a real removal. Metadata: `platform` only - never the client_id/client_secret |
| `account:webhook_target_blocked` | `account` | A manual automation run (`executeAutomation` / `POST /v1/automations/{id}/execute`, `automations:execute`) reached a `webhook_call` node whose target the [webhook target filter](./automations.md#webhook-call-targets) refused. Actor = the member who ran it. Metadata: `automation_id`, `reason` (`invalid_url`, `scheme_not_allowed`, `private_target`), `scheme` - never the host, path or query. Event- and timer-triggered runs do not write it |
| `public_stats:channel_opted_out` | `account` | Broadcaster hides a channel from the public Stats app (`is_public → false`) |
| `public_stats:channel_opted_in` | `account` | Broadcaster re-lists a channel on the public Stats app (`is_public → true`) |
| `billing:withdrawal_declared` / `billing:cancellation_declared` | `system` for public; `account` or `user` for signed-in withdrawal | A declaration was stored. Public cases have no authenticated actor. Signed-in withdrawal uses account scope with an active channel, user scope otherwise. Cancellation of a selected plan or extension uses its subscription-specific request event. |
| `account:subscription_cancel_requested` / `extension:subscription_cancel_requested` | `account` | A signed-in member requested cancellation of a plan or paid extension subscription; actor and declaration ID are recorded without the free-text reason. |
| `billing:withdrawal_processed` / `billing:cancellation_processed` | `system` | An operator closed a declaration as processed or rejected. The event records the decision and case ID, not the declarant's personal details. |
| `billing:declaration_matched` / `billing:declaration_retention_extended` | `system` | An operator matched a public case to a contract or extended its retention date. |
| `billing:withdrawal_waiver_accepted` | `account` | A paid Stripe checkout (plan or extension) completed after the buyer ticked the withdrawal-waiver declaration ([Billing](./billing.md#withdrawal-waiver-and-order-confirmation)). Actor = the buyer. Written once per checkout session by the Stripe webhooks. Metadata: `kind` (`plan`, `extension_payment`, `extension_subscription`), `text_version`, `accepted_at`, `checkout_session_id`, `plan_id` or `extension_id` |
| `account:popout_token_created` / `account:popout_token_updated` / `account:popout_token_deleted` | `account` | Popout-token lifecycle (create / update / delete). A soft-revoke via update carries `"revoked":true`; an update that sets or changes the user binding carries `bound_user_id` (opaque uuid, ZAF-1922). Otherwise metadata is the non-secret `token_id` + `lm_pop_*` prefix only |
| `account:overlay_token_rotated` / `account:overlay_token_revoked` | `account` | Overlay access-token rotate / revoke. Metadata carries `overlay_id` + token ids + the `lm_overlay_*` prefix; never the token string |
| `account:shared_link_created` / `account:shared_link_revoked` / `account:shared_link_extended` | `account` | Shared-overlay link (`lm_share_*`) lifecycle; create/revoke carry the `lm_share_*` prefix, extend carries the new expiry. Never the token string/hash |
| `account:widget_token_created` / `account:widget_token_rotated` / `account:widget_token_revoked` | `account` | Widget access-token lifecycle (create / duplicate / rotate / revoke). Metadata is `widget_id` only - the token id/prefix are not surfaced by the helpers and the full token is never stored |
| `account:overlay_access_granted` / `account:overlay_access_revoked` | `account` | Per-overlay access grant (upsert - resulting `role` in metadata) / revoke; `target_user_id` in metadata |
| `account:widget_access_granted` / `account:widget_access_revoked` | `account` | Per-widget access grant (upsert - resulting `role` in metadata) / revoke; `target_user_id` in metadata |
| `account:history_shared_link_created` / `account:history_shared_link_revoked` / `account:history_shared_link_extended` | `account` | Stream-history report share link (`lm_share_*`) lifecycle; create/revoke carry the `lm_share_*` prefix, extend carries the new expiry. Metadata includes `session_id`, `link_id`, and effective non-secret `options` (legacy links identify their legacy view); never the token string/hash or the argon2 `password_hash` |
| `account:bot_list_updated` | `account` | A platform account was marked or unmarked as a bot through GraphQL or REST. Metadata: `action` (`added`/`removed`), `platform`, `platform_user_id`, `display_name`, `source`. Duplicate adds and missing removals emit nothing. |
| `account:history_keywords_updated` | `account` | A tracked keyword was added, changed or removed through GraphQL or REST. Metadata: `action` (`added`/`changed`/`removed`), `keyword_id`, `keyword`, `match`, `case_insensitive`. Unchanged writes emit nothing. |
| `account:history_revenue_settings_updated` | `account` | Revenue assumptions changed through GraphQL or REST; actor is the user. Metadata lists the changed field names (`changed_fields`), never their values; any added, removed or repriced YouTube membership level appears as `youtube_member_levels`. Reordering levels alone and unchanged writes emit no event; fixed USD values are never edited |
| `account:history_session_deleted` | `account` | A stored stream-history session is deleted (GDPR Art. 17) via `deleteChannelHistory` / `DELETE /v1/history/reports/{id}`; `session_id` in metadata |
| `account:setting_preset_shared` / `account:setting_preset_unshared` | `account` | A user shares/un-shares one of their setting presets with an account (`shareSettingPreset` / `unshareSettingPreset` + `POST` / `DELETE /v1/setting-presets/{id}/share`, `presets:share`). Shared keys the account it is shared into; un-shared keys the account it was shared into (fires only on a real removal). Metadata `preset_id`, `kind`, `name` - never the preset payload (it can hold viewer names) |
| `account:login_connection_assigned` | `account` | An account member's login connection was routed to the account for a provider (`assignLoginConnection` / `POST /v1/accounts/login-assignments`, `login-assignments:create` on the cross-user path); `provider` + `target_user_id` + `connection_id` in metadata |
| `account:login_connection_removed` | `account` | An account member's login assignment was removed for a provider (`removeLoginAssignment` / `DELETE /v1/accounts/login-assignments/{provider}`, `login-assignments:delete`); `provider` + `target_user_id` in metadata |
| `account:extension_access_granted` / `account:extension_access_revoked` | `account` | An extension owner grants/revokes another account's direct access to their extension (`grantExtensionAccess` / `revokeExtensionAccess` + `POST` / `DELETE /v1/developer/extensions/{id}/access[/{grant_id}]`, `extension-dev:edit` + ownership). Row `account_id` = the extension-owner (acting) account; `extension_id`, `target_account_id`, `grant_type`, `grant_id` in metadata |
| `account:extension_access_invite_created` / `account:extension_access_invite_revoked` / `account:extension_access_invite_accepted` | `account` | Extension-access invite lifecycle (`{create,delete}ExtensionAccessInvite` / `acceptExtensionAccessInvite` + `POST` / `DELETE` / `.../accept` REST). Metadata `extension_id`, `invite_id`, `grant_type`, `grant_id`, `max_uses`, `expires_at` - never the `invite_code`/`code` |
| `account:obs_config_saved` / `account:obs_config_deleted` | `account` | The OBS WebSocket config is saved (created or changed) or removed (`saveObsConfig` / `deleteObsConfig` + `PUT` / `DELETE /v1/integrations/obs`, `obs:{edit,delete}` + `feature:obs_remote` + `integration:obs_websocket`); `deleted` is written only when a config was actually removed. Metadata `mode` (`local` / `remote`), `remote_host`, `port`, `has_password` - never the password or its ciphertext |
| `account:se_token_created` / `account:se_token_deleted` | `account` | A StreamElements token is created/upserted or deleted (`createSeToken` / `deleteSeToken` + `POST` / `DELETE /v1/se-tokens[/{id}]`, `se-tokens:{create,delete}` + `feature:streamelements`); metadata `token_id`, `platform`, `label` - never the JWT, its ciphertext, or the masked `token_hint` |
| `account:service_key_created` / `account:service_key_updated` / `account:service_key_revoked` / `account:service_key_rotated` | `account` | An account service key (`lm_svc_*`) is minted, renamed, revoked, or rotated by an account member (`createAccountServiceKey`/`updateAccountServiceKey`/`deleteAccountServiceKey`/`rotateAccountServiceKey` + REST `POST`/`PATCH`/`DELETE /v1/service-keys` / `POST /v1/service-keys/{id}/rotate`, `apikeys:*` + `feature:apikeys`). Account-scoped because the key is a tenant credential that outlives its creator; metadata `service_key_id` + `key_prefix` (or `old_key_prefix`+`new_key_prefix` on rotate) - never the key or its hash |
| `user:api_key_created` / `user:api_key_updated` / `user:api_key_revoked` / `user:api_key_rotated` | `user` | A member mints, renames, revokes, or rotates the secret of a personal `lm_usr_*` API key; emitted by GraphQL `createUserApiKey`/`updateUserApiKey`/`deleteUserApiKey`/`rotateUserApiKey` and REST `POST`/`PATCH`/`DELETE /v1/api-keys` / `POST /v1/api-keys/{id}/rotate` (metadata is `api_key_id` + `key_prefix`, or `old_key_prefix`+`new_key_prefix` on rotate - never the key or its hash) |
| `user:developer_api_key_created` / `user:developer_api_key_updated` / `user:developer_api_key_revoked` | `user` | A developer mints, renames, or revokes a `lm_dev_*` developer API key; emitted by GraphQL `createDeveloperApiKey`/`updateDeveloperApiKey`/`revokeDeveloperApiKey` and REST `POST`/`PATCH`/`DELETE /v1/developer/api-keys`. The **acting developer** is the subject - the key is bound to a developer profile/team that has no account, so this is a `user`-scope event (there is no account log to mirror it into). Metadata carries the non-secret `developer_api_key_id` + `key_prefix` (and owning developer/team id), never the key or its hash |
| `user:login` | `user` | Successful login - native (PKCE) redemption emits in-process from the Rust `/auth/token/exchange` handler (`method: pkce`) and the GraphQL `exchangeToken` mutation emits inline (`method: graphql_exchange`, its only success writer - no first-party caller for apps/id ingest to cover); the web flow is emitted by apps/id via audit-ingest |
| `user:login_failed` | `user` | Rejected login - the Rust REST `/auth` handlers and the GraphQL `exchangeToken` mutation (at parity) emit on failed provider-token validation or a PKCE mismatch; the subject is the resolved user, or NULL when the credential maps to no known Lumio user |
| `user:oauth_granted` | `user` | Provider link/reconnect consent by an authenticated user (emitted by apps/id via audit-ingest) |
| `user:login_reconnect_required` | `user` | A login-connection token refresh failed terminally; the Token Refresh Worker auto-flagged `reconnect_required` |
| `user:active_account_switched` | `user` | The user switched or cleared their session's active account (`updateMe` / `PATCH /v1/users/me`); from/to account ids in `metadata`, `account_id` NULL so it stays out of the target account's tenant log |
| `user:logout` | `user` | The user ended their own session - GraphQL `logout` / `logoutSession`, REST `POST /v1/auth/logout`. Metadata: ended `session_id` (when known) + `method` (`refresh_token` / `session`) |
| `user:session_revoked` | `user` | The user revoked session(s) from session management - GraphQL `deleteSession` / `deleteAllOtherSessions`, REST `DELETE /v1/users/me/sessions/{id}` / `/sessions`. Metadata distinguishes single (`session_id`, `revoked_all:false`) from bulk (`count`, `revoked_all:true`) |
| `user:email_login_requested` | `user` | A user requested or resent an email sign-in verification link. Metadata: `purpose` and `resend`, never the address or link |
| `user:email_login_added` | `user` | Email sign-in was enabled after registration or dashboard setup. Metadata: `via` (`register` or `dashboard`) |
| `user:email_login_changed` | `user` | A user completed an email sign-in address change; metadata is empty |
| `user:email_login_cancelled` | `user` | A user cancelled pending email sign-in setup or change; metadata is empty |
| `user:email_verified` | `user` | An email address was verified during registration, sign-in setup or address change. Metadata: `purpose` (`register`, `add` or `change`), never the address |
| `user:login_method_removed` | `user` | A user removed email sign-in. Metadata: `method` (`email`) |
| `user:password_changed` | `user` | A user changed their password; metadata is empty |
| `user:password_reset_requested` | `user` | A password reset was requested for a resolved user; metadata is empty |
| `user:password_reset_completed` | `user` | A user completed a password reset; metadata is empty |
| `user:email_changed` | `user` | The acting user's profile email changed - through setting up or removing the email sign-in, or removing a platform address - an account-takeover vector; `metadata` carries only `had_previous_email` and the source or `cleared` flag, never the address itself |
| `user:profile_identity_changed` | `user` | The user changed their own profile identity (ZAF-2096): switched the name/picture source between a sign-in connection and their own details (GraphQL `setNameSourceConnection`, REST `PUT /v1/users/me/name-source-connection`), changed the own display name (`updateDisplayName` / `PATCH /v1/users/me/display-name`), uploaded an own picture (REST-only `POST /v1/users/me/avatar`) or removed it (`removeAvatar` / `DELETE /v1/users/me/avatar`). Metadata: `changed` (list of `source`, `display_name`, `avatar`) and, for a source switch, `source` = `own` / `connection` - never a name or picture URL. Choosing among one's own connections is not audited |
| `user:data_export_requested` | `user` | A user requested their own data export. Metadata: `export_id`, export `model`, `account_ids`, and `include_chat`; never export contents |
| `user:data_export_downloaded` | `user` | A user downloaded their own export. Metadata: `export_id` and `model`; never export contents |
| `user:deletion_scheduled` | `user` | A user scheduled deletion of their own profile. Metadata: `grace_days` and `scheduled_for` |
| `user:deletion_cancelled` | `user` | A user cancelled their scheduled profile deletion; metadata is empty |
| `user:data_export_cancelled` | `user` | The user cancelled one of their own data exports while it was still `pending` or `running` - GraphQL `cancelDataExport`, REST `POST /v1/users/me/data-exports/{id}/cancel`. Metadata: `export_id` + `model`, never export contents |
| `user:login_connection_removed` | `user` | A user removed one of their own login connections (`disconnectLoginConnection` / `DELETE /v1/login-connections/{id}`, first-party gated ZAF-469); `provider` + `connection_id` in metadata |
| `developer:verification_submitted` | `user` | An approved developer submitted or resubmitted their own KYC verification (`submitDeveloperVerification` / `POST /v1/developer/verification`, first-party gated ZAF-469); `verification_id`, `developer_id`, `developer_type`, `status`, `resubmission` in metadata - never the submitted KYC/PII fields |
| `developer:tax_details_updated` | `user` | A developer set the tax details of their own verification (Steuernummer, USt-IdNr., § 19 UStG answer; `updateDeveloperTaxDetails` / `PUT /v1/developer/verification/tax-details`). Metadata says which details are present, never their values |
| `developer:payout_requested` | `user` | A developer requested a payout of their balance (`requestPayout` / `POST /v1/developer/payouts/request`), or the closing payout of their profile deletion was created; `source` `request` \| `closing`. Metadata: payout id, method, amount, status and the masked destination - never the full PayPal e-mail or IBAN |
| `developer:extension_secret_set` | `user` | A developer created or replaced an extension secret (`setExtensionSecret` / `PUT /v1/developer/extensions/{id}/secrets/{key}`). `extension_id` and the secret's `key` name in metadata, never the value; `developer_key_id` instead of an actor for a developer key |
| `developer:extension_secret_deleted` | `user` | A developer deleted an extension secret (`deleteExtensionSecret` / `DELETE …/secrets/{key}`); only when a secret was actually removed. Same metadata as `developer:extension_secret_set` |
| `developer:extension_visibility_changed` | `user` | A developer changed their extension's store visibility (`updateExtension` / `PATCH /v1/developer/extensions/{id}`); emits only on a real change. `extension_id`, `from`, `to` in metadata; a change made with a developer key (`lm_dev_*`) has no actor and carries `developer_key_id` instead |
| `developer:team_created` / `developer:team_deleted` | `user` | A developer creates/deletes their own extension-developer team (`create`/`deleteDeveloperTeam` + `POST` / `DELETE /v1/developer/teams[/{id}]`). Self-only (`myAuditLog`); `team_id` (+ `slug` on create) in metadata - never the team name PII |
| `developer:team_role_created` / `developer:team_role_updated` / `developer:team_role_deleted` | `user` | Developer-team custom-role lifecycle (`{create,update,delete}DeveloperTeamRole` + `POST` / `PATCH` / `DELETE /v1/developer/teams/{id}/roles[/{rid}]`, `team-settings:edit`); `team_id`, `role_id`, `role_slug`, `permissions`, `changed_fields` in metadata |
| `developer:team_member_role_changed` / `developer:team_member_removed` | `user` | A developer changes a team member's role or removes them (`updateDeveloperTeamMemberRole` / `removeDeveloperTeamMember` + REST twins, `team-members:{edit,remove}`); `team_id`, `member_id`, `target_user_id`, `role_id` in metadata. The acting developer's self-only log records it (§A.1) |
| `developer:team_invite_created` / `developer:team_invite_revoked` / `developer:team_invite_accepted` | `user` | Developer-team invite lifecycle. Acceptance by code or from the bell records `team_id`, `invite_id`, `role_id`, `member_id`; bell acceptance also records `source: "notification"`. Creation and revocation record their applicable IDs, `max_uses`, and `expires_at`. Never the invite email or code |
| `developer:team_invite_declined` | `user` | The invitee declined a developer-team invite from the bell. Metadata `team_id`, `invite_id`, `invite_deleted` and `source: "notification"`. An unused single-use invite is deleted; a shared or used invite remains. A missing invite writes no event |
| `user:mfa_enabled` / `user:mfa_disabled` | `user` | A user enabled or disabled two-factor authentication. Metadata names the method (`totp` or `passkey`); the first method emits `user:mfa_enabled` |
| `user:mfa_factor_added` / `user:mfa_factor_removed` | `user` | A further authenticator app or passkey was added, or a method was removed while another remains. Metadata contains `method`, `factor_id` and the resulting `factor_count`; additions may include `aaguid`, removals `trusted_devices_revoked`. The user-chosen label is excluded. |
| `user:mfa_challenge_failed` | `user` | A two-factor challenge failed. Metadata: challenge `context` |
| `user:mfa_recovery_code_used` | `user` | A recovery code was used. Metadata: `context` and codes `remaining` |
| `user:mfa_recovery_codes_regenerated` | `user` | A user regenerated their recovery codes; metadata is empty |
| `user:mfa_trusted_device_revoked` | `user` | A user revoked one or all trusted devices. Metadata: `device_id`, `all`, and affected `count` |
| `user:step_up_verified` | `user` | A user confirmed a sensitive action with step-up authentication. Metadata: verification `method` |
| `crawler:scope_changed` | `system` | A platform operator changes the crawler scope |
| `crawler:watchlist_added` | `system` | A platform operator adds a channel to the crawler watchlist |
| `crawler:watchlist_removed` | `system` | A platform operator removes a channel from the crawler watchlist |
| `copyright:moderation_approved` / `copyright:moderation_dismissed` | `system` | A platform operator (`copyright:moderate`) approves a community candidate into the global safe or blocked list, or dismisses a report. REST vote-candidate actions and GraphQL `approveReport` / `dismissReport` emit the same types after a real decision. Metadata: `spotify_track_id`, `list` (`blocked`, `safe`, or null), `source`, `decision` (`approved` or `dismissed`); no song title, artist, or reporter identity. Dismissal emits only when a report was dismissed |
| `system:support_code_viewed` | `system` | A platform operator revealed a user's support code. Metadata: `target_user_id`, never the code |
| `system:support_code_checked` | `system` | A platform operator checked a user's support code. Metadata: `target_user_id` and `result` (`match` or `no_match`), never the code |
| `system:user_mfa_reset` | `system` | A platform operator reset a user's two-factor authentication. Metadata: `target_user_id` and required operator `reason` |
| `system:feature_flag_updated` | `system` | Admin global feature-flag toggles and platform provider kill-switches |
| `system:plan_created` / `system:plan_updated` / `system:plan_deleted` | `system` | Admin plan lifecycle (create / edit / delete) |
| `system:plan_feature_updated` | `system` | Admin plan↔feature mapping changes |
| `system:account_plan_changed` | `system` | An account's plan changed - an admin reassignment (operator path), or a Stripe webhook (`checkout.session.completed` / `customer.subscription.updated` / `customer.subscription.deleted`, discriminated by `"via":"stripe"` in metadata, actor NULL) |
| `system:account_feature_override` | `system` | Admin sets or clears a per-account feature override |
| `system:account_limits_updated` | `system` | A platform operator changes an account's numeric limit overrides (`account_limits`), incl. the setting-preset quota, via either write path (`adminUpsertAccountLimits` / `PUT /v1/admin/accounts/{id}/limits`, or `adminSetAccountLimits` / `PUT /v1/admin/accounts/{id}/resolved-limits`, `accounts:edit`); `account_id`, a `path` discriminator (`upsert`\|`resolved`) and the submitted limit fields in metadata - never the free-text `notes` |
| `system:user_setting_preset_deleted` | `system` | A platform operator deletes one of a user's setting presets (`adminDeleteUserSettingPreset` / `DELETE /v1/admin/setting-presets/{id}`, `users:edit`); `target_user_id`, `preset_id`, `kind` in metadata - never the preset payload; only on a real deletion |
| `system:account_deleted` | `system` | A platform operator deleted an account (`DELETE /v1/admin/accounts/{id}` / `adminDeleteAccount`); the deleted account id, `"reason":"operator_delete"`, `deleted_history_row_count` (stream-history rows deleted) and `deleted_object_count` / `pending_object_count` (stored files deleted / left queued for retry) ride in metadata. System-scoped because the CASCADE leaves no account member to read an account-scoped row (owner self-service dissolve stays `account:dissolved`) |
| `system:orphaned_storage_swept` | `system` | A platform operator applied the orphaned extension upload sweep (`POST /v1/admin/storage/orphaned-extension-uploads/sweep` / `adminSweepOrphanedExtensionUploads`, `apply: true`, `admin:privacy-erase`): extension upload files no row references were queued for deletion; `kind`, `orphaned_object_count`, `queued_object_count` in metadata. A dry run is not recorded |
| `extension:purchase_auto_refunded` | `system` | The Stripe `checkout.session.completed` webhook refunded a paid extension checkout in full because it cannot be delivered: the extension or its version was deleted or unpublished while the checkout was open (`cause: "detached"`), or the account can no longer install it (`cause: "not_installable"`). No actor. `purchase_id`, `cause`, `amount`, `currency` and `stripe_refund_id` in metadata - no buyer data. Recorded only when Stripe accepted the refund |
| `privacy:chatter_objection_added` | `system` | A platform operator records a chatter's GDPR Art. 21 objection (`POST /v1/admin/privacy/chat/objections` / `addChatterObjection`, `admin:privacy-objection-create`); `platform`, `"reason":"objection"` and `already_erased` in metadata - never the user id or login |
| `privacy:chatter_objection_removed` | `system` | A platform operator lifts a chatter objection (`DELETE /v1/admin/privacy/chat/objections/{platform}/{user_id}` / `removeChatterObjection`, `admin:privacy-objection-delete`); same metadata shape. A failed lift records nothing |
| `privacy:channel_suppression_withdrawn` | `system` | A platform operator withdraws a channel's erasure instruction for one chatter (`POST /v1/admin/privacy/chat/erase/withdraw` / `withdrawChannelChatterSuppression`, `admin:privacy-erase-withdraw`); `target: "account"`, the `account_id`, the `instruction_reference` and the `platform` ride in metadata, never the user id or login. A failed withdrawal (no entry, unknown account, or a 409 for an erasure the person asked for) records nothing |
| `system:system_key_created` | `system` | Admin mints a system API key (`is_system=true`); the permission set is registry-validated and a bounded `expires_at` is enforced |
| `system:system_key_revoked` | `system` | Admin revokes a system API key (only the key id in metadata; never `full_key`/`key_hash`) |
| `system:connection_upserted` | `system` | Admin creates/updates a system OAuth (login-provider) connection; the raw `client_secret` and its AES-256-GCM ciphertext are never stored |
| `system:connection_deleted` | `system` | Admin deletes a system OAuth connection |
| `system:user_role_created` / `system:user_role_updated` / `system:user_role_deleted` | `system` | Admin cross-account user-role lifecycle (create / edit / delete) |
| `system:user_role_assigned` / `system:user_role_unassigned` | `system` | Admin assigns/removes a cross-account user role for a user (target user in metadata) |
| `system:user_permission_override_set` / `system:user_permission_override_removed` | `system` | Admin sets/removes a per-user permission override (target user in metadata) |
| `system:account_permission_override_set` / `system:account_permission_override_removed` | `system` | A platform operator (`accounts:overrides-edit`) sets/removes an account-level permission override (`PUT` / `DELETE /v1/admin/accounts/{id}/permission-overrides` / `adminSetAccountPermissionOverride` / `adminRemoveAccountPermissionOverride`); target `account_id` + `permission` (+ `granted`/`reason` on set) in metadata |
| `oauth_client:created` / `oauth_client:updated` / `oauth_client:deleted` | `system` | Operator developer-application OAuth client lifecycle (`oauth-clients:{create,edit,delete}`); metadata `client_id_ref` (DB row id, not the OAuth `client_id` string), `name`, `redirect_uris`, `scopes`, `changed_fields` (update) - never the OAuth `client_id`/`client_secret` |
| `admin_role:created` / `admin_role:updated` / `admin_role:deleted` | `system` | Operator admin-RBAC role lifecycle (`admin-roles:{create,edit,delete}`) on the `admin_roles` table (distinct from `user_roles`); metadata `role_id`, `role_name`, `permissions`, `changed_fields` (update) |
| `admin_role:assigned` / `admin_role:unassigned` | `system` | Operator assigns/removes an admin role for a user (`admin-roles:edit`); metadata `role_id` + `target_user_id`. Emits only on a real (non-idempotent) change |
| `system:global_bot_connection_upserted` / `system:global_bot_connection_deleted` | `system` | Global (nil-UUID) bot connection lifecycle (`bot-connections:{create,delete}`): OAuth exchange upsert and delete. Metadata `platform`, `connection_id`, `bot_username`, `source` (`oauth_exchange`) - never the access/refresh token. The OAuth-exchange path is REST-only |
| `system:user_deleted` | `system` | A platform operator deleted a user and all their data (`users:delete`, `DELETE /v1/admin/users/{id}` / `adminDeleteUser`); `target_user_id` in metadata |
| `system:user_login_connection_deleted` | `system` | A platform operator removed one of a user's login identities (`adminDeleteUserLoginConnection` / `DELETE /v1/admin/users/{id}/login-connections/{provider}`); `target_user_id` + `provider` in metadata |
| `developer:funds_deletion_released` | `system` | A platform operator released a developer balance Lumio could not pay out (no payout method, identity not verified) as a liability and deleted the user or profile (`adminReleaseFundsAndDeleteUser` / `adminReleaseFundsAndDeleteDeveloper` + `POST /v1/admin/{users,developers}/{id}/release-funds-delete`, `developer-funds:release-deletion`); `released_balance_id`, `amount`, `currency`, `release_case` in metadata, never the claim code, reason or request reference |
| `developer:funds_released_claim_started` | `system` | A platform operator recorded that a person presented the claim code of a released developer balance (`adminStartReleasedBalanceClaim` + `POST /v1/admin/released-balances/claim`, `developer-funds:settle`); emitted once per record; `released_balance_id`, `amount`, `currency` in metadata, never the claim code |
| `developer:funds_released_settled` | `system` | A platform operator credited a released developer balance to the person's new, verified developer profile (`adminSettleReleasedBalance` + `POST /v1/admin/released-balances/settle`, `developer-funds:settle`); `released_balance_id`, `developer_id` (the new profile), `amount`, `currency` in metadata, never the claim code |
| `system:developer_deleted` / `system:developer_team_deleted` | `system` | A platform operator deletes a developer or a developer team (`adminDeleteDeveloper` / `adminDeleteDeveloperTeam` + `DELETE /v1/admin/developers/{id}` / `DELETE /v1/admin/developer-teams/{id}`, `developer-verification:edit` / `developer-limits:edit`); `developer_id` / `team_id` in metadata |
| `system:developer_team_member_added` / `system:developer_team_member_removed` / `system:developer_team_member_role_changed` | `system` | Operator developer-team membership admin (`admin{Add,Remove}TeamMember` / `adminUpdateTeamMemberRole` + REST twins, `developer-limits:edit`); `team_id`, `member_id`/`target_user_id`, `role_id` in metadata |
| `system:developer_revenue_split_set` | `system` | A platform operator sets a developer's revenue split (`setDeveloperRevenueSplit` / `PATCH /v1/admin/developers/{id}/revenue-split`, `developer-limits:edit`); `developer_id` + `split` in metadata |
| `system:developer_limits_updated` | `system` | A platform operator updates a developer OR extension limit - one merged event discriminated by `limit_scope` (`"developer"` \| `"extension"`) in metadata (`adminSetDeveloperLimit` / `adminSetExtensionLimits` + `PUT /v1/admin/developers/{id}/limits` / `PATCH /v1/admin/extensions/{id}/limits`, `developer-limits:edit`); `developer_id`/`extension_id`, `limit_key`/`limit_value` or `changed_fields` in metadata |
| `system:developer_limit_request_reviewed` | `system` | A platform operator reviews (approve/deny) a developer limit request (`adminReviewLimitRequest` / `PUT /v1/admin/limit-requests/{id}`, `developer-limits:edit`); `request_id`, `status`, `developer_id`, `extension_id`, `limit_key`, `has_review_notes` (flag) in metadata - never the free-text `review_notes` |
| `system:user_email_changed` | `system` | A platform operator changes a user's email (`adminUpdateUser` / `PATCH /v1/admin/users/{id}`, `users:edit`); emitted only when the stored email actually changed; `target_user_id` + `had_previous_email` (flag) in metadata - never the address. Distinct from the user-self `user:email_changed` |
| `system:user_account_creation_override_set` | `system` | A platform operator sets a user's account-creation override (`adminUpdateUserAccountCreationOverride` / `PATCH /v1/admin/users/{id}`, `users:edit`); `target_user_id` + `override` (`allow`\|`deny`\|`default`) in metadata |
| `system:user_max_accounts_override_set` | `system` | A platform operator sets a user's max-accounts override (`adminUpdateUserMaxAccountsOverride`, `users:edit`) - **GraphQL-only** (no REST twin accepts `max_accounts`); `target_user_id` + `max_accounts` (int\|null) in metadata |
| `system:account_connection_deleted` / `system:account_bot_connection_deleted` | `system` | A platform operator deletes an account's channel / bot connection (`adminDeleteAccountChannelConnection` / `_bot_connection` + `DELETE /v1/admin/accounts/{id}/connections/{platform}` / `.../bot-connections/{platform}`, `accounts:edit`); `target_account_id` + `platform` in metadata; only on a real deletion. `adminDeleteDiscordGuild` / `DELETE /v1/admin/discord-guilds/{guild_id}` (`discord-guilds:delete`) writes `system:account_bot_connection_deleted` with `platform: discord` + `guild_id` |
| `system:account_login_connection_deleted` | `system` | A platform operator deletes an account's login (identity) connection (`adminDeleteAccountLoginConnection`, `accounts:edit`) - **GraphQL-only** (no REST twin for the account-level delete); `target_account_id` + `provider` in metadata; only on a real deletion |
| `system:account_member_added` / `system:account_member_removed` | `system` | A platform operator adds a user to / removes a member from an account (`adminAddAccountMember` / `adminRemoveAccountMember` + `POST /v1/admin/accounts/{id}/members` / `DELETE /v1/admin/accounts/{id}/members/{user_id}`, `accounts:edit`); `target_account_id`, `target_user_id` (+ `role_id` on add) in metadata; add only on a real insert (re-adding an existing member emits nothing), remove only on a real removal. Distinct from the tenant `account:member_removed` |
| `system:coupon_created` / `system:coupon_updated` / `system:coupon_deactivated` | `system` | A platform operator creates, updates or deactivates a coupon (`adminCreateCoupon` / `adminUpdateCoupon` / `adminDeactivateCoupon` + `POST` / `PUT` / `DELETE /v1/admin/coupons[/{id}]`, `coupons:{create,edit}`); `coupon_id` + `discount_type` (create) or `changed_fields` (update, names only) in metadata - never the redeemable `code`; deactivate only on a real deactivation |
| `system:account_se_token_deleted` | `system` | A platform operator deletes an account's StreamElements token (`adminDeleteSeToken` / `DELETE /v1/admin/accounts/{id}/se-tokens/{token_id}`, `se-tokens:delete`); `target_account_id` + `token_id` in metadata - never the JWT or its hint. Distinct from the tenant `account:se_token_deleted` |
| `system:developer_verification_approved` / `system:developer_verification_rejected` | `system` | A platform operator approves or rejects a developer KYC verification (`approveDeveloperVerification` / `rejectDeveloperVerification` + `POST /v1/admin/developer-verifications/{id}/{approve,reject}`, `developer-verification:edit`); `verification_id` (+ `target_account_id` on approve) in metadata - never the free-text rejection reason |
| `system:developer_credit_note_cancelled` | `system` | A platform operator records a developer's objection to a self-billed credit note or corrects it (`cancelCreditNote` / `POST /v1/admin/credit-notes/{id}/cancel`, `billing:edit`). Metadata: note and cancellation ids and numbers, reason, developer id, re-issued note - never the supplier's details |
| `system:developer_payout_scheduled` / `system:developer_payout_sent` / `system:developer_payout_completed` / `system:developer_payout_failed` | `system` | The developer payout lifecycle (ZAF-1257): the monthly cycle created a payout, the cycle handed it to Stripe/PayPal, it reached the developer (operator `completeDeveloperPayout` / `POST /v1/admin/developer-payouts/{id}/complete`, `billing:edit`, or the PayPal webhook), or it failed (provider refusal, operator `failDeveloperPayout` / `…/fail`, or the PayPal webhook; balance credited back). `user_id` is the operator, none for the cycle and the webhook; `source` names the path. Metadata as for `developer:payout_requested`, plus provider ids and, on failure, `refunded` and `cancellation_number` |
| `system:extension_version_approved` / `system:extension_version_rejected` | `system` | A platform operator approves or rejects an extension version in review (`approveExtensionVersion` / `rejectExtensionVersion` + `POST /v1/extensions/reviews/{id}/{approve,reject}`, `extension-review:edit`); `version_id`, `extension_id` (+ `new_status` `testing`\|`published` on approve) in metadata - never the review notes or reason |
| `system:user_extension_dev_mode_set` | `system` | A platform operator toggles a user's extension dev mode (`setExtensionDevMode` / `POST /v1/admin/users/{id}/extension-dev-mode`, `developer-limits:edit`); `target_user_id` + `enabled` in metadata |
| `system:api_key_updated` / `system:api_key_rotated` / `system:api_key_revoked` | `system` | A platform operator edits (label + scopes), rotates the secret of, or revokes **any** account's/user's API key from the admin app (`adminUpdateApiKey`/`adminRotateApiKey`/`adminDeleteApiKey` + REST `PATCH` / `POST .../rotate` / `DELETE /v1/admin/api-keys/{kind}/{id}`, `account-apikeys:{edit,rotate,delete}`). Operator is the actor; metadata `kind` (`personal`\|`service`), `api_key_id`, target `account_id`, target `user_id` (personal only), plus `permissions` (update) or `old_key_prefix`+`new_key_prefix` (rotate) - never the key. Never surfaces in the target account's/user's own log |

> **apps/id-emitted rows require the ingest key:**
> The two rows the ID app contributes over `POST /v1/internal/audit-ingest` - the
> **web-flow** `user:login` and `user:oauth_granted` - are written once
> `LUMIO_AUDIT_INGEST_KEY` holds an `lm_sys_*` System key carrying the
> `audit:ingest` grant. That key is mintable from the admin app (**System →
> System-API-Schlüssel**), since `audit:ingest` is part of the System-key
> assignable-scope registry. Without the key the web-login and OAuth-consent rows
> are absent, while the native/PKCE and GraphQL `user:login` writers are
> unaffected. See
> [Audit Events → Events that originate outside the API](../developer-guide/audit-events.md#events-that-originate-outside-the-api-appsid-ingest).

## Storage

Audit events are persisted in TimescaleDB. The [event catalog](#event-catalog)
above lists every recorded type. See [Admin → Audit Log](../admin/audit-log.md)
for the operator view, a selection of operator-relevant events, and GeoIP
location enrichment.

For the web dashboard surfaces, see [Audit Log](../user-guide/audit-log.md).

## Retention

Audit events follow a fixed, three-step window, counted from `created_at`:

| Age | What is kept |
|-----|--------------|
| 0–12 months | the full row |
| 12–24 months | the row without its network fields - `ip_address`, `user_agent`, `country` and `city` are nulled in place; `account_id`, `user_id`, `type`, `metadata`, `scope` and `created_at` remain |
| after 24 months | nothing - the row is deleted |

The erasure-proof types `youtube_member_erasure` and `chat_pii_erasure` are the
exception: they prove that a GDPR erasure was carried out, so they are deleted
after **36 months** instead of 24. They carry no network fields, so the
12-month step changes nothing for them.

Both steps are native TimescaleDB scheduled jobs that run daily, always on and
not gated behind a feature flag: `anonymise_old_audit_events` nulls the network
fields, `purge_old_audit_events` deletes the rows. A deleted row is gone from
every read surface and export.

---

## Features / Accounts

Source: https://docs.lumio.vision/features/accounts

# Accounts

## Overview

The accounts module manages the full account lifecycle: creation (with automatic JWT re-issue), name editing, account dissolution (immediately or after a 7- or 30-day grace period, with the channel suspended in between), and leaving accounts as a non-owner member. Lumio supports multi-account switching -- a user can own multiple accounts and be a member of others.

## Multi-Account Ownership

Users can own multiple Lumio accounts. This is controlled by two mechanisms:

1. **Feature flag** -- the `feature:multi_account` flag must be enabled for the user's best account (the account whose plan has the highest `max_accounts` value).
2. **Plan-based limit** -- each plan defines a `max_accounts` field that caps how many accounts the user can own:
   - Free: 1 account
   - Pro: 3 accounts

The effective limit is derived from the user's best plan: `MAX(plans.max_accounts)` across all accounts they own. Admins can override this per-user via `max_accounts_override` on the user record; when set, the override replaces the plan-derived limit entirely.

### Account Creation Wizard

The dashboard presents a 3-step account creation wizard:

1. **Name & Description** -- enter the account name and optional description.
2. **Assign Login Connections** -- select which of the user's login connections to assign to the new account.
3. **Confirm** -- review and create the account.

## Channel name and picture

A channel's name and picture come from one chosen **source**:

- **`connection`** -- one of the channel's own channel connections on Twitch, YouTube or Kick (never Spotify). The name is the connection's channel name, the picture is the platform profile picture (Twitch `profile_image_url`, YouTube channel thumbnail, Kick profile picture). The picture is stored in `channel_connections.channel_avatar_url`, filled on connect, on reconnect and by a boot-time sync (`sync_channel_identities`). Only hosts already allowed by the web CSP are kept (`static-cdn.jtvnw.net`, `yt3.ggpht.com`, `lh3.googleusercontent.com`, `files.kick.com`); any other URL is dropped and the initial is shown. While a connection is the source, `accounts.name` mirrors its channel name, so search, the admin app and mails show the same name.
- **`own`** -- an editable name (`accounts.name`) and an optional uploaded picture (`accounts.avatar_storage_key`, stored in lo-storage under `accounts/{id}/avatar/`). Without an upload the initial is shown.

New channels start with `own`. A channel whose source connection is deleted is treated as `own`.

The one read point is the database view `account_identities` (`account_id`, `source_kind`, `source_connection_id`, `source_platform`, `name`, `connection_avatar_url`, `avatar_storage_key`). Every reader joins it; nothing resolves the source by hand. The API exposes the result as `identity` (`source_kind`, `source_connection_id`, `source_platform`, `name`, `avatar_url`) on the account (`Account.identity`, `GET /v1/accounts/{id}`, `POST /v1/accounts`) and on every membership (`me.accounts[].identity`, `GET /v1/users/me` `accounts[].identity`). The membership's `account_name` is the same resolved name. `owner_avatar_url` / `ownerAvatarUrl` is deprecated and equals `identity.avatar_url`; there is no fallback to the owner's profile picture. The `avatar_url` of an uploaded picture is `{storage.public_url}/accounts/{id}/avatar/{uuid}-512.webp`, served by the API at `GET /v1/uploads/file/accounts/{id}/avatar/{file}` when `storage.public_url` is the default `{api}/v1/uploads/file`.

In the dashboard the source, the own name and the own picture are set in a tab of the channel settings.

### Rules

- **Switch source** -- `kind` is `connection` (with `connection_id`) or `own` (without one). A Spotify connection, an unknown kind, `connection` without an id or `own` with an id fail with `400 INVALID_SOURCE`; a connection of another channel or an unknown id fails with `404 Connection not found`. Switching to `own` keeps the current name as starting value and shows the initial. Switching back to a connection deletes an uploaded picture.
- **Own name** -- only with `own`, otherwise `409 SOURCE_NOT_OWN`. Trimmed, NFC-normalised, 2-50 characters, no control or invisible characters (`400 NAME_TOO_SHORT` / `NAME_TOO_LONG` / `NAME_INVALID_CHARACTERS`).
- **Own picture** -- only with `own` (`409 SOURCE_NOT_OWN`). Same pipeline as the profile picture: at most 5 MB (`413 AVATAR_TOO_LARGE`), PNG, JPEG or WebP by magic bytes (`415 AVATAR_UNSUPPORTED_TYPE`), at most 16 megapixels (`400 AVATAR_TOO_MANY_PIXELS`), `400 AVATAR_MISSING` / `AVATAR_UNREADABLE`; re-encoded as 512 px and 128 px WebP without metadata. 10 uploads per channel per hour, counted before the body is read (`429 RATE_LIMITED`); `503 AVATAR_UNAVAILABLE` without storage; `503 AVATAR_BUSY` with `Retry-After` while the two decode slots shared with profile pictures are taken. A new upload or a removal deletes the old files.
- **Guard** -- all four mutations need `account:edit` (owner and administrator by default), an interactive sign-in session (a user API key or popout token is refused with `403 This action requires an interactive sign-in session`), and the `{id}` / `accountId` must be the session's active channel (`403 Account id does not match the active account`). During a dissolution grace period the refusal is `403 CHANNEL_DISSOLVING`.
- **Disconnect** -- disconnecting the channel connection that is the source (`DELETE /v1/connections/channel/{platform}` / `disconnectChannel`, or the admin `DELETE /v1/admin/accounts/{id}/connections/{platform}` / `adminDeleteAccountChannelConnection`) switches the channel to `own` with the connection's last channel name and the initial. The owner gets an in-app notification (type `channel_identity_source_removed`, link `/dashboard/settings/channel/general`).
- **Delete** -- dissolving a channel (immediately, with grace 0, or by the scheduled job) and admin account deletion delete the uploaded picture files, through the channel's stored-file erasure (see [Account Dissolution Flow](#account-dissolution-flow), step 5).
- **Audit** -- every effective change writes `account:identity_changed` (scope `account`, actor = caller) with metadata `changed` (a list of `source`, `name`, `avatar`), `source_kind` and `source_platform`; never a name or URL. Switching back to a connection that deleted an upload writes `changed: ["source", "avatar"]`. Nothing is written when nothing changed.

### API

| Protocol | Endpoint | Description |
|----------|----------|-------------|
| REST | `PUT /v1/accounts/{id}/identity-source` | Choose the source (`{kind, connection_id?}`) |
| REST | `PATCH /v1/accounts/{id}/name` | Set the own name (`{name}`) |
| REST | `POST /v1/accounts/{id}/avatar` | Upload the own picture (multipart field `file`; REST only) |
| REST | `DELETE /v1/accounts/{id}/avatar` | Remove the own picture |
| REST | `GET /v1/uploads/file/accounts/{id}/avatar/{file}` | Serve the current uploaded picture (public, not audited) |
| GraphQL | `setAccountIdentitySource(accountId, kind, connectionId)` | Choose the source |
| GraphQL | `updateAccountName(accountId, name)` | Set the own name |
| GraphQL | `removeAccountAvatar(accountId)` | Remove the own picture |

The three GraphQL mutations return `AccountIdentity!`. See [REST API › Channel name and picture](../api-reference/rest-api.md#channel-name-and-picture).

## Architecture

```
Dashboard UI / ID App
    |
    v
Next.js API Proxy (/api/accounts)
    |
    +---> REST API (POST/GET/DELETE /v1/accounts, POST /v1/accounts/{id}/leave)
    |         |
    |         +--> JWT re-issue on create/dissolve
    |
    +---> GraphQL (AccountQuery / AccountMutation)
    |
    v
db::overlays, db::auth, db::members, db::roles (PostgreSQL)
```

### Account Creation Flow

1. User calls `POST /v1/accounts` or the `createAccount` mutation. `CreateAccountInput` carries an optional `name` (defaults to the user's display name) and an optional `planId` (defaults to the Free plan).
2. The system checks `feature:multi_account` is enabled and the user has not exceeded their `max_accounts` limit.
3. The account is created with the user's display name and the specified `plan_id`.
4. Default roles (Owner, Administrator, Moderator) are created via `db::roles::create_default_roles`.
5. The user is added as a member with the Owner role.
6. The **caller's own session** is switched to the new account (`active_account_id` updated on that one session row only, via `db::auth::set_session_active_account`). Account selection is per-device (ZAF-1416): creating an account on one device does not re-point the user's other devices. A session-less caller (API-key auth) persists nothing here.
7. For a caller with an interactive session, a fresh JWT bound to that session is issued containing the new `account_id` and returned alongside the account data. A caller without one (e.g. a user API key) gets `token: null` (GraphQL `CreateAccountResult.token` is a nullable `String`) - a JWT is only minted for a session caller (ZAF-1922).

### Account Dissolution Flow

1. User (must be owner, holding `account:delete`) calls `DELETE /v1/accounts/{id}` or `dissolveAccount` mutation with `confirm_name` matching the account name exactly. The REST path `{id}` must be the caller's **active-session account** - both protocols operate on the session account, and both require the `account:delete` permission (ZAF-450 S2).
   After these checks the calling session needs a step-up in the last 10 minutes (ZAF-2052); otherwise both protocols answer `403` / `STEP_UP_REQUIRED` ("Please confirm that it's you first") and nothing is deleted. Only an interactive sign-in session can hold a step-up, so a user API key, service key or popout token is refused even with `account:delete`.
2. All sessions referencing this account have `active_account_id` set to `NULL`. This clear is deliberately **account-wide** (`WHERE active_account_id = $1`), unlike the per-device account *switch* (ZAF-1416): narrowing it to the caller's session would leave the user's other devices holding a dangling, now-deleted account in their token.
3. The account's **chatter PII** is erased before the account row is removed: chat messages and platform events (TimescaleDB) and the chatter profiles, moderator notes and moderation log (`platform_users`, `platform_user_notes`, `platform_moderation_log` - no foreign key to `accounts`). The CASCADE reaches none of them. The operator delete (`DELETE /v1/admin/accounts/{id}`) runs the same erasure. See [Chat › Erasure (GDPR Art. 17)](./chat.md#erasure-gdpr-art-17).
4. The channel's platform workers are stopped and its **stream history is deleted**: every `channel_history`, `channel_history_streams`, `channel_history_stats` and `channel_history_milestones` row of the account, an open (live) session included, and the account's rows of the viewer-curve rollups `channel_history_stats_5m` / `_1h` (`db::channel_history::delete_all_account_history`, one transaction). The stream reports belong to the channel and go with it (founder ruling ZAF-2626). The workers stop first, so no stream-online hook opens a new session for the account. With a grace period of 7 or 30 days this happens only when the job dissolves the channel at the end of it; scheduling deletes nothing, and a cancel keeps the history. The step is fatal and runs before the account row is deleted, so a failure leaves the account in place and the dissolution retryable. Deleting the streams queues their platform channels for the [Lumio Stats](./public-stats.md) browse aggregates, which are recomputed without them; the crawler's own capture of the same platform channel is not the account's and stays. The operator delete (`DELETE /v1/admin/accounts/{id}` / `adminDeleteAccount`) runs the same step. The audit event carries `deleted_history_row_count`.
5. The account is deleted (CASCADE handles related tables: memberships, roles, overlays, etc.) together with its **stored files** (`services::storage_erasure::delete_account`). In the same transaction, before the `DELETE`, every object key the account owns is copied into `storage_deletion_queue`: generic uploads, the account's own sounds, extension uploads no other account references (they are content-addressed per extension and shared), and the uploaded channel picture. Extension-bundled sounds are the extension's files and stay. After the commit the files are deleted; a file whose delete fails stays queued and the hourly account security worker retries it until it is gone. The operator delete (`DELETE /v1/admin/accounts/{id}` / `adminDeleteAccount`) uses the same path. The audit event carries `deleted_object_count` (files deleted) and `pending_object_count` (files left queued for the retry). After the commit, the bot-module `ctx.cache` hash of each extension install the CASCADE removed (`lumio:ext:cache:{install_id}`) is deleted at once instead of expiring with its field TTLs. This step is best-effort: a Redis failure is logged and the TTLs still bound the data to 24 hours.
6. REST returns a fresh JWT without `account_id`, bound to the caller's session, so the user stays authenticated but can select another account (ZAF-1922). GraphQL `dissolveAccount` returns `{ success }` only, no token.

Since an active Stripe subscription would keep billing a deleted account, both protocols refuse the dissolution with `409` / `ACTIVE_SUBSCRIPTION` while a subscription is running and not set to cancel at period end ("Cancel it in the billing settings first"). This check runs before the step-up.

### Scheduled Dissolution (grace period)

The owner can also schedule the dissolution with `POST /v1/accounts/{id}/dissolution` or `scheduleAccountDissolution(accountId, graceDays)`, guarded by `account:delete`. `grace_days` is `0`, `7` or `30` (default `30`); any other value fails with `400` / `INVALID_GRACE`. Both protocols run the same checks in the same order: first-party user (popout tokens refused), `INVALID_GRACE`, the id is the active account (`403`), owner only (`403` "Only the account owner can dissolve an account"), `409 DISSOLUTION_ALREADY_SCHEDULED`, `409 ACTIVE_SUBSCRIPTION`, then a fresh step-up (`403 STEP_UP_REQUIRED`; a user API key cannot hold one).

- `grace_days: 0` dissolves the account at once through the immediate flow above and returns `{ dissolution_scheduled_for: null, dissolved: true }`.
- `7` or `30` sets `accounts.dissolution_scheduled_for` (plus `dissolution_requested_at`, `dissolution_requested_by`, `dissolution_grace_days`) and returns the date with `dissolved: false`. The owner gets a confirmation mail, every other member a mail naming the channel and the date. Both are delivered as the locked notification type `account_deletion_scheduled` (in-app and email, English and German). The event `account:dissolution_scheduled` is written.
- The account security worker reminds the owner 7 days before the end of a 30-day period and 1 day before the end of a 7-day period (`dissolution_reminded_at`), then dissolves due accounts through the same path as the immediate flow (`account:dissolved` with `via: "scheduled"`). The job claims each due channel right before its first write and acts only while the dissolution is still scheduled and due; its final `DELETE` repeats that condition. A cancel confirmed before the date therefore always wins.

`DELETE /v1/accounts/{id}/dissolution` / `cancelAccountDissolution(accountId)` cancels it. Owner only, interactive session only (no API key, no popout token), no step-up because cancelling is the safe direction. It works while the account is suspended, up to the end of the grace period. It fails with `409 PROFILE_DELETION_SCHEDULED` while the owner's own profile is scheduled for deletion (cancel that first), with `409 DISSOLUTION_IN_PROGRESS` ("The dissolution is already running") once the date has passed - the job owns the channel then - and with `409 NO_DISSOLUTION_SCHEDULED` when nothing is scheduled. The owner and the members are mailed, and `account:dissolution_cancelled` is written.

`dissolution_scheduled_for` is exposed on `Account` / `GET /v1/accounts/{id}` and on every membership in `me.accounts[]` / `GET /v1/users/me` `accounts[]`. The dashboard reads the membership value to show the dissolution banner and the label in the account switcher.

A profile whose owner still owns channels can be scheduled for deletion only when every owned channel is scheduled for dissolution on or before the profile deletion date; otherwise `409 OWNS_CHANNELS`. The daily job dissolves due channels first and deletes due profiles in the same run. Like the channel, a profile deletion can be cancelled only before its date (`DELETE /v1/users/me/deletion` / `cancelProfileDeletion`); afterwards both protocols answer `409 DELETION_IN_PROGRESS` ("The deletion is already running"), and the job deletes a profile only while its deletion is still scheduled and due.

What a deleted profile leaves in other channels is fixed by each foreign key's `ON DELETE` action. Nothing in a channel the profile does not own blocks the deletion:

- **Kept, authorship cleared (`SET NULL`):** records that belong to a channel or to the platform and only name their author. Examples are files and sounds the member uploaded (`uploaded_by`), invites they sent (`invited_by`), access they granted to overlays, widgets and extensions (`granted_by`), and admin or reviewer fields such as `updated_by`, `reviewed_by` and `resolved_by`. API fields that show these ids are nullable and read `null` afterwards.
- **Deleted with the profile (`CASCADE`):** rows the user owns or that only make sense with them. Examples are memberships, sessions, notifications, popout tokens bound to the member, invites addressed to them, overlay and history shared links they created, and their copyright reports and confirmations.
- **Extensions the profile publishes (`CASCADE`, torn down):** the extensions of the user's developer profile and of every developer team they own go with the profile, and so do the installs of those extensions on **every** channel. The same happens when an operator deletes a developer profile (`DELETE /v1/admin/developers/{id}` / `adminDeleteDeveloper`) or a team (`DELETE /v1/admin/developer-teams/{id}` / `adminDeleteDeveloperTeam`), or a team owner deletes their team (`DELETE /v1/developer/teams/{id}` / `deleteDeveloperTeam`). Nothing of those extensions outlives the delete: in the delete transaction the extension rows are locked and every stored file of the extension is queued in `storage_deletion_queue` (version files, bundles, icon, screenshots and every channel's extension uploads), and the installs' extension-bundled sounds are deleted. After the commit, each extension's `ext_{extension_id}` data schema on the extensions database is dropped, the removed installs' `ctx.cache` hashes are purged, and the queued files are deleted; a failed file delete stays queued for the hourly retry (`services::storage_erasure::finish_extension_teardown`). A draft extension delete runs the same teardown. The purchases made of those extensions are the exception: they are the buyers' and the accounting records, so they stay with their amounts, status and Stripe Checkout Session, and only their `extension_id` and `version_id` become `null` (the product reference stays with the Stripe session). A channel that bought a deleted extension no longer owns it.
- **Developer payouts (`SET NULL`):** a payout is a booking record and stays for 8 calendar years after the year of its last status change, with a copy of the verified payee name, address and tax id; only its `developer_id` becomes `null`.
- **Blocking on purpose (`RESTRICT`):** `accounts.owner_id`. An owned channel must be dissolved first (`409 OWNS_CHANNELS` above).
- **Blocked while Lumio owes the developer money:** a developer profile with a revenue balance above 0 or a payout that is `pending` or `processing` is not deleted, on any path: profile deletion (the daily job holds a due deletion and retries it every run once the profile is paid out; held profiles do not take a place in its batch), `DELETE /v1/admin/users/{id}` / `adminDeleteUser` and `DELETE /v1/admin/developers/{id}` / `adminDeleteDeveloper`. A trigger on `developer_profiles` enforces it, so the user cascade cannot bypass it.
- **Unpayable balance released as a liability (ZAF-2831):** when the balance cannot be paid out (no payout method, or no verified identity) and the person asks for the deletion, an operator releases it (`adminReleaseFundsAndDeleteUser` / `adminReleaseFundsAndDeleteDeveloper`, REST `POST /v1/admin/{users,developers}/{id}/release-funds-delete`). In the delete transaction the balance moves to a `developer_released_balances` row (balance → 0), so the trigger lets the delete through. The row holds no former user or developer id and no personal data; the person gets a 128-bit claim code by e-mail, stored only as a SHA-256 hash. Unsettled rows are deleted from 1 January (Europe/Berlin) of the release year + 4; a started claim holds the row; a settled row is deleted 8 years after the settlement year. When the person returns, an operator with `developer-funds:settle` records the presented code (`claim_started_at`, `adminStartReleasedBalanceClaim` / `POST /v1/admin/released-balances/claim`) and credits the amount to the person's new, verified developer profile in one transaction (`adminSettleReleasedBalance` / `POST /v1/admin/released-balances/settle`); the normal payout pays it out. The settled row is part of that profile's data export (`developer.json` → `settled_released_balances`); an unsettled row is linked to nobody and is in no export. A refund of a sale made before the release finds no developer to debit, so the released amount stays overstated by that share — accepted, the release is not held for the refund window.
- **Closing payout (ZAF-2825):** scheduling a profile deletion with a grace period of 7 or 30 days pays the whole developer balance out as one `pending` payout, even below the minimum payout amount (same path as a manual payout: verified payee snapshot and self-billed credit note, one transaction), and returns the amount as `closing_payout_cents` / `closingPayoutCents`. Scheduling still fails with `409 DEVELOPER_FUNDS_OUTSTANDING` when a payout is in flight, with `grace_days: 0` while any money is owed, and when the balance cannot be paid out (no payout method, no verified identity); incomplete tax details refuse it with `422 TAX_DETAILS_REQUIRED` (see [Developer Credit Notes](./developer-credit-notes.md)). Revenue that arrives later, while the deletion is scheduled (grace period running or held by the job), is paid out with `POST /v1/developer/payouts/request` `{ "closing": true }` / `requestPayout(closing: true)`, which skips the minimum only then (`409 CLOSING_PAYOUT_REQUIRES_DELETION` otherwise).

A dissolved channel keeps the extension purchases it made: `extension_purchases.account_id` becomes `null`, so the developer's revenue records stay complete. Sessions that had the channel active lose `active_account_id`.

### Suspension while a dissolution is scheduled

While `dissolution_scheduled_for` is set, one check in the API auth middleware (right after credential resolution) suspends the account:

- **Channel-bound credentials** - user API keys (`lm_usr_`), service keys (`lm_svc_`), popout tokens, overlay (`lm_overlay_`), shared overlay (`lm_share_`), widget (`lm_widget_`) and extension (`lm_ext_`) tokens - are refused with `403` `CHANNEL_DISSOLVING` (message "This channel is being dissolved. Only cancelling the dissolution is possible", `details.dissolution_scheduled_for`). They are not revoked and work again after a cancel.
- **Member sessions** keep their identity but lose every account permission. Permission-gated REST routes answer `403 CHANNEL_DISSOLVING`; GraphQL errors carry `extensions.code = "CHANNEL_DISSOLVING"` and `extensions.dissolutionScheduledFor`. User-level routes keep working: the profile, `me` with the account list, switching and leaving accounts, and the owner's cancel.
- **WebSocket** - the `/v1/ws` upgrade is refused with `403 CHANNEL_DISSOLVING` for any credential of the account; open sockets are closed with `CHANNEL_DISSOLVING` on the 30-second re-validation tick.
- **Feature flags** all resolve off (`FeatureService`), which stops automations, feature-gated routes and the WebSocket feature gate.
- **Bots** - the account drops out of `botChannels` (Twitch, YouTube, Kick) and `discordBotGuilds`; bots leave on their next poll and rejoin by themselves after a cancel. Bot-module and automation-node handler feeds report the account's installs as disabled, and the bot-module trigger feed omits them.
- **Webhook ingest** (YouTube PubSubHubbub, Kick) drops deliveries for the account.
- **Platform workers** - scheduling the dissolution stops every worker of the account in the API process (Twitch EventSub, YouTube InnerTube polling, Kick, Spotify, StreamElements, OBS Remote, automation), so no chat or events of the channel are fetched or stored during the grace period. The replica that handles the request stops them at once and tells the others over Redis (`lumio:account_workers`); every replica also stops the workers of all dissolving accounts when it (re)subscribes and once a minute, in case a message was lost. The boot auto-start, the Spotify start on going live, the OBS reconcile loop and the Twitch IRC, Kick chat-moderation and 7TV rosters leave the account out. A cancel starts the workers again on the replica that handled it (like a new connection); the dissolution itself stops them before the account is deleted. Code: `apps/api/src/workers/account_workers.rs`.
- **Checkout** - `createCheckout` / `POST /v1/billing/checkout` is refused with `403 CHANNEL_DISSOLVING`.

### Leave Account Flow

1. Non-owner members can call `POST /v1/accounts/{id}/leave` or `leaveAccount` mutation.
2. Ownership check prevents the owner from leaving (they must dissolve instead).
3. The user's membership row is deleted.

## API

### REST Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `POST` | `/v1/accounts` | Create a new account | Authenticated |
| `GET` | `/v1/accounts/{id}` | Get account details | `account:read`; active account must match (same guard as GraphQL `account`) |
| `DELETE` | `/v1/accounts/{id}` | Dissolve account | `account:delete` + owner + confirm_name + path id = active account |
| `POST` | `/v1/accounts/{id}/dissolution` | Schedule dissolution (`grace_days` 0, 7 or 30; 0 dissolves at once) | `account:delete` + owner + path id = active account + step-up |
| `DELETE` | `/v1/accounts/{id}/dissolution` | Cancel a scheduled dissolution | Owner, interactive session, no step-up |
| `POST` | `/v1/accounts/{id}/leave` | Leave an account | Authenticated member |
| `GET` | `/v1/accounts/{id}/enabled-features` | Enabled feature keys for the account | Authenticated (own account) |
| `GET` | `/v1/accounts/{id}/feature-statuses` | Per-feature resolution detail (global / plan / override) | Authenticated (own account) |
| `GET` | `/v1/accounts/login-assignments` | List login-connection assignments on the account | `login-assignments:read` (own assignments always visible) |
| `POST` | `/v1/accounts/login-assignments` | Assign a login connection to the account (`account_id` defaults to the active account; own connections may target any account the caller is a member of) | `login-assignments:create` (own always allowed) |
| `DELETE` | `/v1/accounts/login-assignments/{provider}` | Remove a login assignment (same `account_id` rule) | `login-assignments:delete` (own always allowed) |
| `PUT` | `/v1/accounts/{id}/identity-source` | Choose the channel's name/picture source | `account:edit` + interactive session + path id = active account |
| `PATCH` | `/v1/accounts/{id}/name` | Set the own channel name (source `own`) | `account:edit` + interactive session + path id = active account |
| `POST` | `/v1/accounts/{id}/avatar` | Upload the own channel picture (source `own`) | `account:edit` + interactive session + path id = active account |
| `DELETE` | `/v1/accounts/{id}/avatar` | Remove the own channel picture | `account:edit` + interactive session + path id = active account |
| `GET` | `/v1/uploads/file/accounts/{id}/avatar/{file}` | Current uploaded channel picture | Public |

Member management (`GET /v1/accounts/{id}/members`,
`DELETE /v1/accounts/{id}/members/{membership_id}`,
`PATCH /v1/accounts/{id}/members/{membership_id}/role`) is documented under
[Members](/features/members).

#### POST /v1/accounts

```json
{
  "plan_id": "uuid-of-plan"
}
```

When `plan_id` is omitted, the account is created on the Free plan.

**Response (201):**
```json
{
  "data": { "id": "...", "name": "...", "plan_id": "...", ... },
  "token": "lm_eyJ..."
}
```

**Response (403) - account creation disabled:**
```json
{
  "error": "Account creation is currently disabled",
  "error_code": "account_creation_disabled"
}
```

Account creation can be disabled globally by an administrator via the `system:account_creation` feature flag, or for a specific user via the per-user override on the user's admin detail page. The equivalent GraphQL error is `extensions.code: "ACCOUNT_CREATION_DISABLED"`. See [Feature Flags](../developer-guide/feature-flags.md) for the resolution chain.

#### DELETE /v1/accounts/{id}

Requires the `account:delete` permission and account ownership; the path `{id}` must equal the caller's active-session account (mirrors GraphQL `dissolveAccount`, which operates on the session account). Returns `403` when the permission is missing or the id does not match the active account. This destructive action - like `POST /v1/accounts/{id}/leave` - additionally requires a **first-party logged-in user session**: a popout/overlay/widget/extension token is rejected with `403`, so the owner authorization runs against the real session principal, not a popout-bound identity (ZAF-469). After the permission, owner, active-account and name checks the session needs a step-up in the last 10 minutes, otherwise `403` with code `STEP_UP_REQUIRED` (ZAF-2052); a user API key is refused here because it cannot hold a step-up.

```json
{
  "confirm_name": "My Account Name"
}
```

### GraphQL Queries

| Query | Args | Returns | Permission |
|-------|------|---------|------------|
| `account` | `id: UUID!` | `Account?` | `account:read` |
| `accountFeatures` | -- | `AccountFeatureQuery!` | `AuthGuard` (works with popout-token auth) |

Users can only query their own active account. `accountFeatures` is a namespaced
query object exposing `enabledFeatures: [String!]!` and
`featureStatuses: [AccountFeatureDetail!]!`; it deliberately needs no
`account:read` so popout tokens can resolve their own feature set. The account is
always taken from the auth context, never from a client parameter.

`Account.plan` is the plan **slug** (`"free"`, `"pro"`), not the plan UUID.
`Account.identity` is the channel's resolved name and picture (see
[Channel name and picture](#channel-name-and-picture)).

### GraphQL Mutations

| Mutation | Args | Returns | Permission |
|----------|------|---------|------------|
| `createAccount` | `input: CreateAccountInput!` | `CreateAccountResult!` | `AuthGuard` (any authenticated) |
| `updateAccount` (deprecated) | `id: UUID!`, `name: String!` | `Account!` | `account:edit` |
| `setAccountIdentitySource` | `accountId: UUID!`, `kind: String!`, `connectionId: UUID` | `AccountIdentity!` | `account:edit` + interactive session |
| `updateAccountName` | `accountId: UUID!`, `name: String!` | `AccountIdentity!` | `account:edit` + interactive session |
| `removeAccountAvatar` | `accountId: UUID!` | `AccountIdentity!` | `account:edit` + interactive session |
| `dissolveAccount` | `confirmName: String!` | `DissolveAccountResult!` | `account:delete` |
| `scheduleAccountDissolution` | `accountId: UUID!`, `graceDays: Int` | `AccountDissolution!` | `account:delete` |
| `cancelAccountDissolution` | `accountId: UUID!` | `AccountDissolution!` | `AuthGuard` + owner + interactive session |
| `leaveAccount` | -- | `LeaveAccountResult!` | `AuthGuard` (any authenticated) |

- `createAccount` returns error extension `{ "code": "ACCOUNT_CREATION_DISABLED" }` with message `"Account creation is currently disabled"` if the `system:account_creation` flag is globally off or the user has a `deny` override.
- `updateAccount` is deprecated and follows exactly the `updateAccountName` rules: source `own` only (`SOURCE_NOT_OWN`), 2-50 characters, interactive session only, target account = active account, audited as `account:identity_changed`.
- `setAccountIdentitySource`, `updateAccountName` and `removeAccountAvatar` follow [Channel name and picture](#channel-name-and-picture).
- `dissolveAccount` requires exact name confirmation, owner status, no active subscription (`ACTIVE_SUBSCRIPTION`) and a step-up on the session in the last 10 minutes (`STEP_UP_REQUIRED`, same as REST).
- `scheduleAccountDissolution` and `cancelAccountDissolution` follow [Scheduled Dissolution](#scheduled-dissolution-grace-period).
- `leaveAccount` has no permission guard beyond authentication -- any member can leave.

### GraphQL Types

```graphql
type Account {
  id: UUID!
  ownerId: UUID
  name: String!
  plan: String!
  createdAt: String!
  updatedAt: String!
  dissolutionScheduledFor: String
  identity: AccountIdentity!
}

type AccountIdentity {
  sourceKind: String!          # "connection" | "own"
  sourceConnectionId: UUID
  sourcePlatform: String       # "twitch" | "youtube" | "kick"
  name: String!
  avatarUrl: String
}

type DissolveAccountResult {
  success: Boolean!
}

type AccountDissolution {
  dissolutionScheduledFor: String
  dissolved: Boolean!
}

type LeaveAccountResult {
  success: Boolean!
}
```

## Permissions

| Permission | Description |
|------------|-------------|
| `account:read` | View account details |
| `account:edit` | Edit the channel's name/picture source, own name and own picture |
| `account:delete` | Dissolve account (also requires owner check) |

Included in: Owner role has all three. Administrator has `account:read` and `account:edit`. The `leaveAccount` mutation bypasses permission guards (only requires authentication).

## Database

### Table: `accounts`

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Account ID |
| `owner_id` | `UUID` (FK) | Account owner user ID |
| `name` | `TEXT` | Account display name; with source `connection` it mirrors the connection's channel name |
| `plan_id` | `UUID` (FK) | References the `plans` table |
| `identity_source_kind` | `TEXT` | Name/picture source: `connection` or `own` (default `own`) |
| `identity_source_connection_id` | `UUID` (FK, nullable) | Channel connection used as the source (only with `connection`). `ON DELETE SET NULL`; a missing connection reads as `own`. |
| `avatar_storage_key` | `TEXT` (nullable) | lo-storage key prefix of the uploaded picture (`accounts/{id}/avatar/{uuid}`), only with `own` |
| `created_at` | `TIMESTAMPTZ` | Creation timestamp |
| `updated_at` | `TIMESTAMPTZ` | Last update timestamp |
| `dissolution_scheduled_for` | `TIMESTAMPTZ` (nullable) | Date of a scheduled dissolution; while set the account is suspended |
| `dissolution_requested_at` / `dissolution_requested_by` | `TIMESTAMPTZ` / `UUID` (nullable) | When and by whom it was scheduled (`ON DELETE SET NULL`) |
| `dissolution_grace_days` | `SMALLINT` (nullable) | Chosen grace period (7 or 30) |
| `dissolution_reminded_at` | `TIMESTAMPTZ` (nullable) | When the owner reminder was sent |

The view `account_identities` resolves the source into `source_kind`, `source_connection_id`, `source_platform`, `name`, `connection_avatar_url` and `avatar_storage_key`; it is the only read point for a channel's name and picture.

Related tables (CASCADE delete):
- `account_memberships` -- User-account membership with role
- `account_roles` -- Custom roles for the account
- `account_role_permissions` -- Permissions assigned to roles
- `overlays`, `channel_rewards`, `se_tokens`, `integration_configs`, etc.

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/accounts.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/accounts.rs` | REST endpoints with JWT re-issue |
| `apps/api/src/services/account_dissolution.rs` | Shared schedule / cancel / dissolve logic for both protocols |
| `apps/api/src/db/account_dissolution.rs` | Dissolution columns and due-account queries |
| `apps/api/src/services/account_identity.rs` | Channel name/picture source, own name, own picture (both protocols) |
| `apps/api/src/db/account_identity.rs` | `account_identities` view reads and source writes |
| `crates/lo-auth/src/dissolution.rs` | `CHANNEL_DISSOLVING` suspension check |
| `apps/api/src/workers/account_security.rs` | Reminder and due dissolution job |
| `apps/api/src/db/auth.rs` | User lookup, session management |
| `apps/api/src/db/roles.rs` | Default role creation |
| `apps/api/src/db/members.rs` | Membership management |
| `crates/lo-auth/src/rbac.rs` | Permission constants (`account:read/edit/delete`) |

---

## Features / Integrations

Source: https://docs.lumio.vision/features/integrations

# Integrations

## Overview

The integrations module provides a generic configuration framework for platform-specific integrations (e.g., OBS, Discord bots). Each integration is scoped to an account with a platform identifier, a human-readable label, an enable/disable toggle, and a flexible JSONB `config` field for platform-specific settings.

The **generic** integration surface exposes read, update and toggle only - it has no create or delete operation. Rows in `integration_configs` are written by the feature that owns the integration: system connections (`db::system_connections`), the Kick worker, and the OBS integration all insert and delete their own row. OBS additionally has its own dedicated REST and GraphQL surface with full create/delete semantics; see [OBS](./obs.md).

## Architecture

```
Dashboard UI
    |
    v
Next.js API Proxy (/api/integrations)
    |
    v
GraphQL (IntegrationQuery / IntegrationMutation)
    |
    v
db::integrations (PostgreSQL)
```

The `config` JSONB field stores platform-specific configuration. For example, an OBS integration might store WebSocket connection details, scene mappings, or source configurations. The API layer is agnostic to the config structure -- validation is handled by the consuming service.

### Secrets in `config`

Credentials inside `config` are encrypted at rest and never returned to a client. The rules live in `apps/api/src/services/integration_secrets.rs`:

- **Encrypted at rest.** Secrets are stored as AES-256-GCM ciphertext (`crypto::encrypt_versioned`, the same key as every other credential), never as plaintext. The Shopify offline access and refresh tokens are written by ID-token exchange when a link completes or access is renewed, as `access_token_encrypted` / `refresh_token_encrypted` (see [Shopify](./shopify.md#token-storage-and-refresh)). The OBS `password` is encrypted by the OBS surface itself.
- **Never returned.** Every `Integration.config` that the API returns (`integrations`, `integration`, and both mutation results) has its secrets removed. Each removed secret is replaced by a `has_<name>` boolean, for example `has_access_token`, `has_refresh_token` or `has_password`. A key counts as a secret when its name is `password`, `secret`, `token` or `api_key`, or ends in `_secret`, `_token`, `_password`, `_api_key` or `_encrypted`. Shopify configs always carry both `has_access_token` and `has_refresh_token`.
- **Dedicated surfaces.** OBS and Shopify rows are written only through their own surfaces ([OBS](./obs.md), [Shopify](./shopify.md)), never through `updateIntegration`.

### Shopify customer label (`customer_display`)

A Shopify order event never contains the customer's full name or contact data. The Shopify `config` key `customer_display`, set with `updateShopifySettings` / `PUT /v1/connections/shopify/settings` (see [Shopify](./shopify.md#settings)), decides how much of the name an order event carries:

| Value | Label for "Alex Miller" |
|-------|-------------------------|
| `none` (default) | no label |
| `first_name` | `Alex` |
| `first_initial` | `A.` |
| `first_name_last_initial` | `Alex M.` |
| `custom_name` | the name the buyer typed for the stream (sanitized), never the real name |

- **Fail-closed.** A missing key or any other stored value is read as `none`. The settings surface rejects an unknown value with `BAD_REQUEST` (`Config field 'customer_display' must be one of: none, first_name, first_initial, first_name_last_initial, custom_name`).
- **Only with the buyer's consent.** The cart and checkout blocks write two private cart attributes to the order: `__lumio_name_consent` (the consent record `"<form>:<text version>:<scope>"`, e.g. `first_initial:2:i`; `0` or missing = no consent) and `__lumio_stream_name` (the typed name). `lo_shopify::Order` keeps only these two of the order's `note_attributes`; every other attribute is dropped when the payload is parsed, and neither is stored in the event or logged. The record names the form the block showed, the consent-text version (only `2` is accepted; version `1` never shipped) and the order details the text named: `o` (order only), `i` (items), `p` (price), `ip` (items and price), from the store's [`show_items` / `show_price`](./shopify.md#order-details). Every form except `none` needs a record:
  - **Scope.** The recorded scope must cover the current details, one switch at a time: a buyer who agreed to "with the items" gets no label once the streamer turns the price on; a buyer who agreed to "items and price" still gets one when the price is turned off.
  - **Real-name forms** need a record with one of the three real-name forms and are shown in the **less revealing** of the consented and the current form (`first_initial` < `first_name` < `first_name_last_initial`): consent to `Alex M.` covers `A.`, consent to `A.` never covers `Alex`.
  - **`custom_name`** needs a `custom_name` record next to the typed name.
  - A typed name under a real-name form, or a checkbox record under `custom_name`, is a mismatch and shows no label.
- **Typed names (`custom_name`)** go through `lo_shopify::sanitize_stream_name`: NFKC; whitespace collapsed; control, format and default-ignorable characters removed; a bidi control drops the name. Then only letters, marks, numbers, space, `-`, `'`, `.` and `_` are allowed, the first character must be a letter or number, and the result must have at most 25 grapheme clusters and 100 UTF-8 bytes. Anything else shows no label (never a truncated or stripped one). The name must also pass the account's [word filter](./bot-modules.md): the config of its enabled `system-word-filter` install (`bannedWords`, `useWildcards`, `bannedPatterns`; `lo_shopify::WordFilter`), read on every such order without a cache, so a new word applies to the next order. Without an enabled install no word is filtered. If the lookup fails, the order shows no label.
- **Shopify's protected customer data.** Name fields reach Lumio only if Shopify approved the app for *protected customer data* Level 2 (name). Without that approval Shopify redacts the name in the order webhook, and every real-name form yields no label.
- **No first name, no label.** Without a customer first name every real-name form yields no label. The label never falls back to the last name or the email address. Without a last name, `first_name_last_initial` gives the first name alone.
- **Initials** are the first character (grapheme) of the name, uppercased, followed by `.`, so `Łukasz` gives `Ł.`. A multi-word first name is kept whole (`Mary Ann`).

The label is built by `lo_shopify::order_customer_label` when the webhook arrives; see [Webhooks → Shopify](./webhooks.md#shopify) for what an order event stores.

## API

### GraphQL Queries

All four operations are gated by `FeatureGuard::new("feature:integrations").and(PermissionGuard::new(<permission>))`, so an account whose plan lacks `feature:integrations` gets `FEATURE_DISABLED` before the permission is even considered.

| Query | Args | Returns | Feature | Permission |
|-------|------|---------|---------|------------|
| `integrations` | -- | `[Integration!]!` | `feature:integrations` | `settings:read` |
| `integration` | `id: UUID!` | `Integration` | `feature:integrations` | `settings:read` |

- `integrations` returns all configs for the active account, ordered by platform.
- `integration` returns a single config by ID, filtered by account ownership.

### GraphQL Mutations

| Mutation | Args | Returns | Feature | Permission |
|----------|------|---------|---------|------------|
| `updateIntegration` | `input: UpdateIntegrationInput!` | `Integration!` | `feature:integrations` | `settings:edit` |
| `toggleIntegration` | `id: UUID!` | `Integration!` | `feature:integrations` | `settings:edit` |

- `updateIntegration` supports partial updates via `COALESCE` -- only provided fields are changed.
- `updateIntegration` replaces `config` as a whole when it is sent.
- `updateIntegration` refuses a `config` for an OBS row with `BAD_REQUEST` (`The OBS config can only be changed in the OBS settings`) and leaves the row unchanged. OBS config is written only through the [OBS](./obs.md) surface, which validates `remote_host` against SSRF and encrypts `password`. `enabled` and `label` can still be changed here.
- `updateIntegration` refuses a `config` for a Shopify row the same way (`The Shopify connection can only be changed in the Shopify settings`). Only the [Shopify](./shopify.md) link completion and token renewal write the tokens and shop identity; the dedicated Shopify settings write `customer_display`, `show_items` and `show_price`. A generic `settings:edit` member cannot point the row at another shop.
- `toggleIntegration` flips the `enabled` boolean without requiring the caller to know the current state.

Both mutations verify account ownership before proceeding.

### REST Endpoints

The generic integration surface is **GraphQL-only** - there is no `/v1/integrations`
REST resource for listing, updating or toggling an arbitrary integration. The
paths that do exist under `/v1/integrations/` all belong to the OBS integration
and are documented in [OBS](./obs.md):

| Method | Path |
|--------|------|
| `GET` / `PUT` / `DELETE` | `/v1/integrations/obs` |
| `GET` | `/v1/integrations/obs/credentials` |
| `GET` | `/v1/integrations/obs/status` |
| `POST` | `/v1/integrations/obs/test` |

The web dashboard reaches the generic surface through its Next.js proxy routes
(`/api/integrations`, `/api/integrations/[id]`), which execute the GraphQL
operations server-side.

### WebSocket

There is no integration channel. `channel_gate_for` in
`crates/lo-websocket/src/gate.rs` maps no `integrations` channel type, so a
subscription attempt is rejected as `Unknown`. Integrations that stream data do
so on their own channels - OBS through its status polling, Discord through
`events:{account_id}`.

### GraphQL Types

```graphql
type Integration {
  id: UUID!
  accountId: UUID!
  platform: String!
  label: String!
  enabled: Boolean!
  config: JSON!
  createdAt: String!
  updatedAt: String!
}

input UpdateIntegrationInput {
  id: UUID!
  label: String
  enabled: Boolean
  config: JSON
}
```

## Permissions

| Permission | Description |
|------------|-------------|
| `settings:read` | View integration configurations |
| `settings:edit` | Update integration configurations |

Integrations share the `settings:*` permission namespace. Included in: Owner, Administrator roles.

Beyond the permission, every operation requires the `feature:integrations` flag on the account's plan.

## Database

### Table: `integration_configs`

| Column | Type | Description |
|--------|------|-------------|
| `id` | `UUID` (PK) | Integration config ID |
| `account_id` | `UUID` (FK) | Owning account |
| `platform` | `TEXT` | Platform identifier (e.g., `obs`, `discord`) |
| `label` | `TEXT` | Human-readable label |
| `enabled` | `BOOLEAN` | Whether the integration is active |
| `config` | `JSONB` | Platform-specific configuration |
| `created_at` | `TIMESTAMPTZ` | Creation timestamp |
| `updated_at` | `TIMESTAMPTZ` | Last update timestamp |

### DB Functions

| Function | Description |
|----------|-------------|
| `list_integrations` | List all configs for an account, ordered by `platform ASC` |
| `get_integration` | Get a single config by ID |
| `update_integration` | Partial update using `COALESCE` for label, enabled, config |
| `toggle_integration` | Flip `enabled` to `NOT enabled` |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/integrations.rs` | GraphQL queries, mutations, input/output types |
| `apps/api/src/db/integrations.rs` | Database CRUD operations |
| `crates/lo-auth/src/rbac.rs` | Permission constants (`settings:read`, `settings:edit`) |

---

## Features / Shopify

Source: https://docs.lumio.vision/features/shopify

# Shopify

Lumio is a public app in the Shopify App Store. A merchant installs it on their store; the store's orders and new products then reach the account as `shopify:order`, `shopify:order_paid` and `shopify:product` events (see [Webhooks → Shopify](./webhooks.md#shopify)). The integration is gated by the plan flag `integration:shopify`.

## Merchant setup

Install Lumio from the Shopify App Store, open **Apps › Lumio** in the Shopify admin, and start **Connect Lumio account**. In the Lumio tab, choose the account and confirm the connection. Return to Shopify and confirm the named Lumio account there to finish. The link expires after ten minutes; an expired link starts again from Shopify. See [Connections › Shopify](/user-guide/connections#shopify) for the controls and permissions.

In the embedded app, choose how buyers may be named and which order details reach Lumio. For a buyer name to appear, place the **Name on livestream** app block on the cart page, or, on Shopify Plus, place the checkout block. The three real-name forms use an unticked consent checkbox; **Your own name** (`custom_name`) uses an optional text field. Buyers who skip the cart through an accelerated checkout and do not see an eligible block have no name on their order event. You can hide one stored order's buyer label later from the Lumio Events feed. The order-details switches apply only to orders received after the change.

The code lives in `apps/api/src/services/shopify.rs` (shared by both protocols and the embedded routes), `apps/api/src/services/shopify_link.rs` (the link handle), `apps/api/src/db/shopify.rs`, `apps/api/src/graphql/shopify.rs`, `apps/api/src/routes/shopify.rs`, `apps/api/src/routes/shopify_embedded.rs`, the `lo-shopify` crate (GraphQL Admin API client, ID-token verification, token exchange) and the embedded admin page `apps/shopify` (Next.js, see [Embedded page](#embedded-page-appsshopify)).

## Install and link

Lumio is an **embedded** app: its page runs inside the Shopify admin, and Shopify installs the app itself (Shopify-managed install). Scopes, the app URL and the webhook subscriptions are declared in `apps/shopify/shopify.app.<env>.toml`, not requested by Lumio. There is no OAuth authorization-code round and no OAuth callback. Every request from the embedded page carries an App Bridge **ID token** ([REST → Embedded app](../api-reference/rest-api.md#embedded-app-v1shopifyembedded)); the backend gets the store's token by **token exchange** with that ID token.

Installing alone connects nothing. A store is bound to a Lumio account by a **link**, which needs both sides, because the embedded page has an ID token but no Lumio session, and the Lumio tab has a session but no ID token:

1. **Start (Shopify admin).** The embedded page calls `POST /v1/shopify/embedded/link`. The API mints a link handle bound to the store (the token's `dest`) and the staff member (`sub`) and returns the Lumio page `{web.public_url}/dashboard/settings/channel/connections/shopify#link=<handle>`. The handle is in the URL fragment, so it never reaches a server, a log or a `Referer`.
2. **Confirm (Lumio).** In the Lumio tab, a member with `connections:create`, `integration:shopify` and an interactive sign-in session sees the store (`shopifyLinkRequest` / `POST /v1/connections/shopify/link/inspect`) and confirms it for the active account (`shopifyLinkConfirm` / `POST /v1/connections/shopify/link/confirm`). Confirm re-checks [one store, one account](#one-shop-one-account) and refuses a browser request whose `Sec-Fetch-Site` is not `same-origin`. No token is written here.
3. **Complete (Shopify admin).** The embedded page reads the handle (`GET /v1/shopify/embedded/link/{handle}`), shows the confirmed account's name and, after the staff member clicks, calls `POST /v1/shopify/embedded/link/complete` with a fresh ID token. Only the staff member who started the link can complete it. The API re-checks the account, the plan flag and one store, one account, runs the token exchange, checks the granted scopes, reads the store name and stores the connection. It emits `account:integration_connected` and sends an in-app notice (`shopify_linked`) to the account owner and the confirming member.

**The handle** lives in Redis under `shopify:link:{handle}` (a hash; `shopify:link_shop:{store}` points to the store's open handle), 10 minutes from the start, not extended. Its states are `pending` → `confirmed` → `completing`; every change is one Lua compare-and-set, so a double click, two tabs or two staff members cannot both win. A second start replaces the store's open handle; `DELETE /v1/shopify/embedded/link/{handle}` cancels it. A failed completion (an expired ID token, Shopify unreachable) puts the handle back to `confirmed`, so App Bridge's retry works without starting over. After a successful completion the handle is deleted. A handle of another store reads as expired.

**A contested handle is burned.** Two parties holding one handle means it leaked. If a `confirmed` handle is confirmed for a second account, or another Lumio user than the one who confirmed it opens it on the confirm screen (`shopifyLinkRequest` / `link/inspect`), the API deletes the handle and the store's pointer and answers `409` with the contested message below. This guards against a look-alike account name: whoever confirmed first chooses the name the Shopify admin shows next. The confirm screen then shows its expired view, and the embedded page's completion reads the handle as expired and offers a fresh start. A double click and the confirmer's own reload keep the handle. So the request read has a deliberate side effect, on both protocols. The OAuth handles (`oauth:handle:`) are a separate keyspace: the OAuth exchange can never consume a link handle.

**Rate limits:** 5 link starts per store in 10 minutes, 10 confirms (and request reads) per Lumio user in 10 minutes, 10 completions per store per minute, 120 other embedded requests per store per minute. A burst is logged: it is the signal of a consent-phishing attempt.

### Web routes and dashboard

The settings window's Services area loads the status (`shopifyConnection`, only with `connections:read` and `integration:shopify`); the short link `/dashboard/settings/channel/connections/shopify` opens it at its Shopify section. Settings and disconnect go through `PUT /api/connections/shopify/settings` (`updateShopifySettings`, any of `customer_display`, `show_items`, `show_price`) and `DELETE /api/connections/shopify` (`disconnectShopify`). "Open in Shopify" opens `https://admin.shopify.com/store/<store>/apps/<handle>`, where `<handle>` is the app handle from `apps/shopify/shopify.app.<env>.toml` (web env var `LUMIO_SHOPIFY_APP_HANDLE`, default `lumio`); opening the page there also renews an expired access by token exchange.

**The link-confirm screen** is the same path with `#link=<handle>`, a standalone page (route group `(shopify-link)`, no dashboard shell):

- The page takes the handle from the fragment and removes it from the address at once (`history.replaceState`). It never confirms on load.
- Signed out (the edge lets this one path through without a session and renews an expired one), it keeps the handle in `sessionStorage` (`lumio-shopify-link`, deleted when read) and sends the browser to the ID app; back on the page it reads the handle from there.
- Without a handle it is the card's short link and opens the settings window.
- It names the store by the `*.myshopify.com` host from `shopifyLinkRequest` (never from the URL), the account the link goes to (picker, preselected: the active account, or the first one the member may link) and the warning line above the button. **The warning names only that host, never the store display name:** a display name is owner-controlled and is not known until the token exchange during `link/complete`. The picker knows the active account's permissions; for the others the default roles decide (Owner and Administrator may, Moderator may not) and the API's answer decides for a custom role. Picking another account switches the active account before the confirm.
- The browser calls `POST /api/connections/shopify/link/inspect` and `POST /api/connections/shopify/link/confirm` with `{ "handle": … }` in the body. Both refuse with `403` unless `Sec-Fetch-Site` is `same-origin`, or it is absent and `Origin` equals the web public origin (`LUMIO_APP_URL`); a same-site sibling such as the embedded host is refused.
- `apps/web/src/proxy.ts` sends an enforced `Content-Security-Policy: frame-ancestors 'none'`, `X-Frame-Options: DENY` and `Referrer-Policy: no-referrer` on exactly this path, next to the global report-only policy.

The events feed and the chat read `raw.customer_display` as the buyer's name (plain text, no user card) and render the order details of [Order details](#order-details): up to three items `{qty}× {title}`, then `+N more`, the unit price after an item (`(je 12,50 €)` for more than one), and the total as a chip. Prices are formatted with `raw.currency`; without one they are bare numbers. In streamer mode the total is masked (`SensitiveAmount`) and item prices read `••••••`. "Hide name" in the feed calls `POST /api/connections/shopify/events/{event_id}/hide-name` (`hideShopifyOrderName`); pop-out sessions do not offer it.

### Shopify Dev Dashboard settings

| Setting | Value |
|---|---|
| Distribution | Public (App Store) |
| Install | Shopify-managed; scopes, app URL, redirect URL and webhook subscriptions in `apps/shopify/shopify.app.<env>.toml` |
| Scopes | `read_orders,read_products,read_legal_policies` (the backend checks the token's scope readback against `[shopify] scopes`) |
| Embedded in Shopify admin | Yes (App Bridge ID tokens + token exchange) |
| Protected customer data | Level 1 for order webhooks; add the *Name* field (Level 2) only if merchants should be able to use a customer label |
| Compliance webhooks (`compliance_topics`) | `customers/data_request`, `customers/redact`, `shop/redact` → `{server.public_url}/v1/webhooks/shopify/compliance` |


### Embedded page (`apps/shopify`)

The page the merchant sees under **Apps › Lumio** in the Shopify admin is its own Next.js app, `apps/shopify` (package `@lumio/shopify`), on its own origin (the app URL in `shopify.app.<env>.toml`). It is built from Shopify's **Polaris web components** (`polaris.js`) and **App Bridge** (`app-bridge.js`), both from `cdn.shopify.com`; it uses no `@lumio/ui`, no seasonal look and no Lumio session. Texts are `en` and `de` (`apps/shopify/messages/`), chosen from Shopify's `locale` launch parameter (`en` for any other language).

**States:** loading (a skeleton in the shape of the page plus the admin's loading bar) · not linked (one button, "Mit Lumio-Konto verbinden") · pending (the Lumio tab is open; "Ich habe bestätigt", "Lumio-Tab erneut öffnen", "Abbrechen") · second confirmation ("Mit dem Lumio-Konto „{name}“ verbinden?", from `GET …/link/{handle}`; only the click on "Verbinden" calls `link/complete`, "Abbrechen" calls `DELETE …/link/{handle}`) · link expired or used ("Neu starten") · linked · invalid session. While a link is pending, the page re-reads the link state when the tab gets focus or becomes visible again; reading never completes it.

**Linked:** the connection (account name, connected since, "In Lumio öffnen", "Trennen" with an `s-modal` confirmation → `POST …/disconnect`), the buyer name form (an `s-choice-list` with the five forms), the order details (`s-switch` *Artikel anzeigen* / *Preis anzeigen*), the setup guide and the merchant's legal notes. Every setting saves at once through `PUT …/settings` and confirms with an App Bridge toast; a refused save restores the previous value.

**Setup guide** (only while the form is not `none`):

| Step | Data source | Action |
|---|---|---|
| 1. Cart block placed / missing | `shopify.app.extensions()`: block `name-consent` of `name-consent-cart` with `status: "active"` on the published theme | Theme editor deep link `shopify://admin/themes/current/editor?template=cart&addAppBlockId={client_id}/name-consent&target=newAppsSection` (the handle is the block's file name) |
| 2. Checkout (Shopify Plus) | `shop.plan.shopifyPlus` through Direct API access (`fetch("shopify:admin/api/graphql.json")`, `[access.admin]` in the app configuration, online mode) | Written steps and a link to the checkout settings; Lumio cannot see whether the checkout block is placed |
| 3. Privacy policy present / missing | `shop.shopPolicies` (`type` + `body`, scope `read_legal_policies`): present = a `PRIVACY_POLICY` with a non-empty body | Present: link to `shopify://admin/settings/legal`. Missing: a critical banner above the steps ("Dein Shop hat keine Datenschutzerklärung", button "Datenschutzerklärung anlegen" → the same link); the step itself then has only a short pointer to that button |

A value the page cannot read shows the step without a status badge instead of guessing.

**Legal notes** (texts from Legal, verbatim): with a name form other than `none`, "Rechtliche Hinweise zur Namensanzeige" (responsibility, privacy policy with both legal bases, cookie overview for *Eigener Name*, sensitive products while *Artikel anzeigen* is on, record, withdrawal). With `none` and at least one of the two switches on, "Rechtliche Hinweise zu Bestelldetails im Stream": the privacy policy bullet for order details without a name (legitimate interest, right to object) and, while *Artikel anzeigen* is on, the sensitive products bullet. With `none` and both switches off nothing about a buyer reaches the stream, so the page shows no legal notes.

**Requests:** the browser calls only the app's own route handlers (`/api/status`, `/api/link`, `/api/link/{handle}`, `/api/link/complete`, `/api/settings`, `/api/disconnect`), each with a fresh App Bridge ID token as `Authorization: Bearer`. The handlers forward that header (and the browser's user agent, but no client IP header) to [`/v1/shopify/embedded/*`](../api-reference/rest-api.md#embedded-app-v1shopifyembedded) and nothing else: no cookie, no Lumio token. A `401` with `X-Shopify-Retry-Invalid-Session-Request: 1` is retried once with a new token; a second one shows the invalid-session state.

**Headers** (`apps/shopify/src/proxy.ts`, on every response):

- `Content-Security-Policy` (enforced): `default-src 'self'`; `script-src 'self' 'nonce-…' https://cdn.shopify.com`; `connect-src 'self' https://cdn.shopify.com/shopifycloud/admin-ui-foundations/` (the path Polaris loads its icons from); `object-src 'none'`; `base-uri 'none'`; `form-action 'self'`; and `frame-ancestors https://{shop} https://admin.shopify.com`. The shop comes only from Shopify's launch query after its `hmac` verifies with the client secret (or the previous one), and only if it is a `{store}.myshopify.com` host. Otherwise `frame-ancestors 'none'`. Never a wildcard.
- `Cache-Control: private, no-store`, because the header differs per shop. Every route is dynamic.
- No `X-Frame-Options`: it cannot allow a list of origins.
- The `Cookie` request header is dropped before any handler runs, and the app sets no cookie.

`app-bridge.js` is the first script tag the layout renders, right after `<meta name="shopify-api-key">`. Next.js still puts its own `async` chunk scripts ahead of it in `<head>`, so the page waits for the parsed document and `shopify.ready` before its first App Bridge call.

## API

| GraphQL | REST | Permission | Feature |
|---|---|---|---|
| `shopifyConnection` | `GET /v1/connections/shopify` | `connections:read` | `integration:shopify` |
| `shopifyLinkRequest(handle: String!)` | `POST /v1/connections/shopify/link/inspect` | `connections:create` + interactive session | `integration:shopify` |
| `shopifyLinkConfirm(handle: String!)` | `POST /v1/connections/shopify/link/confirm` | `connections:create` + interactive session, not cross-site | `integration:shopify` |
| `updateShopifySettings(customerDisplay: String, showItems: Boolean, showPrice: Boolean)` | `PUT /v1/connections/shopify/settings` | `connections:edit` | `integration:shopify` |
| `disconnectShopify` | `DELETE /v1/connections/shopify` | `connections:delete` | `integration:shopify` |
| `hideShopifyOrderName(eventId: UUID!, createdAt: String!)` | `POST /v1/connections/shopify/events/{event_id}/hide-name` | `events:edit` | none (see [Hide a buyer name](#hide-a-buyer-name)) |
| *(REST only)* | `/v1/shopify/embedded/*` (status, link, link/`{handle}`, link/complete, settings, disconnect) | Shopify ID token of a staff member; no Lumio permission | `integration:shopify` checked at link completion |

The embedded routes are REST-only on purpose: their caller is a Shopify staff member, not a Lumio principal, and their own principal type (`routes::shopify_embedded::ShopifyEmbeddedPrincipal`) has no conversion to the Lumio auth context. They are mounted outside and before the `/v1` scope (`routes::configure_v1_scopes`, which `main.rs` and the mount test both call, so a Lumio token on `/v1/shopify/embedded/*` always gets the embedded `401`), accept no Lumio token, and act only on the Shopify connection of the account the store is linked to. A settings change or disconnect from the Shopify admin is also pinned to the token's store: the write needs the account's row to still hold that store, so if the account was relinked to another store in between, the answer is `404` (`Shopify is not connected`) and the other store's row stays untouched.

The status (`ShopifyConnectionStatus` / `ShopifyStatusResponse`) has `configured` (the app credentials are set), `app_store_url` (the listing to install from, from `[shopify] app_store_url`) and `connection` (`null` when no store is connected). A connection has `shop_host`, `shop_name`, `status` (`connected` or `needs_reconnect`), `customer_display`, `show_items`, `show_price`, `scopes`, `enabled` and `connected_at`. No token, secret or `has_*` flag is ever part of it. The embedded status (`GET /v1/shopify/embedded/status`) has `linked`, `account_name` (the only account data the store sees) and the same `connection`.

No WebSocket channel is added: Shopify events reach the account through the existing event channels.

### Errors

Both protocols return the same messages:

| Message | Status | When |
|---|---|---|
| `Shopify is not configured: set [shopify].client_id and [shopify].client_secret (…)` | 422 | No app credentials on this deployment |
| `This Shopify store is already connected to another Lumio account.` | 409 | Another account holds the store |
| `This account is already connected to another Shopify store. Disconnect it first.` | 409 | The account holds a different store |
| `This Shopify store is already connected to a Lumio account.` | 409 | Link start for a store that is linked |
| `This Shopify link request has expired. Start the connection again in your Shopify admin.` | 422 | Unknown, expired or cancelled handle, or another store's |
| `This Shopify link request was cancelled because someone else had confirmed it. Start the connection again in your Shopify admin.` | 409 | A confirmed handle confirmed for a second account, or read by another user than its confirmer; the handle is deleted |
| `This Shopify link request was already confirmed for another Lumio account.` | 409 | Confirm while the handle is being completed |
| `The link has not been confirmed in Lumio yet. Confirm it in the Lumio tab first.` | 409 | Completion before the confirm |
| `This link request is being completed. Please wait a moment.` | 409 | A second completion or a cancel while one runs |
| `This link request was started by another Shopify staff member.` | 403 | Completion by another staff member |
| `This request must come from the Lumio app itself.` | 403 | Confirm with `Sec-Fetch-Site` other than `same-origin` |
| `invalid session` | 401 + `X-Shopify-Retry-Invalid-Session-Request: 1` | Any refused ID token, or Shopify refused it at the token exchange (embedded routes only) |
| `Shopify did not grant the required access: …` | 422 | A required scope is missing from the token's readback |
| `Shopify could not be reached. Please try again.` | 500 | Token exchange failed in transit |
| `Shopify is not connected` | 404 | Settings or disconnect without a connection |
| `Nothing to update: set at least one of customer_display, show_items, show_price.` | 400 | A settings update without any field |
| `Shopify order event not found` | 404 | Hide for an event that is not a Shopify order event of the account, or a `created_at` more than 1 s off |
| `created_at must be an RFC 3339 timestamp` | 400 | Hide with an unreadable `created_at` |

## One shop, one account

A store can belong to one Lumio account at a time, and an account holds at most one store:

- `integration_configs.shop_host` is a real column, written only by the link completion, with a `CHECK` on the `{store}.myshopify.com` shape and the partial unique index `uq_integration_configs_shopify_shop_host` (`WHERE platform = 'shopify'`).
- The completion inserts on `(account_id, platform)` only. A unique violation on the shop index is the *another account* error; an existing row with a different shop is the *disconnect first* error.
- The same checks run at confirm and again before the token exchange (`services::shopify::ensure_installable`), so a refused link makes no Shopify call.

## Token storage and refresh

New public apps get **expiring offline tokens**: the access token lives one hour, the refresh token 90 days and is replaced on every refresh. `integration_configs.config` of a Shopify row holds:

| Key | Content |
|---|---|
| `access_token_encrypted`, `refresh_token_encrypted` | AES-256-GCM ciphertext (`crypto::encrypt_versioned`) |
| `access_token_expires_at`, `refresh_token_expires_at` | RFC 3339 |
| `scopes` | The scope readback of the last exchange or refresh |
| `scopes_requested` | The configured scopes at the last exchange (sorted); stops a re-exchange loop while the merchant has not approved new scopes |
| `shop_name`, `connected_at` | From the link |
| `customer_display`, `show_items`, `show_price` | See [settings](#settings) |
| `customer_display_synced` | What the storefront metafields last confirmed: `<form>:<scope>`, e.g. `first_initial:i` |

**Token exchange** (`oauth::token_exchange`, ID token → expiring offline token) retires every other refresh token of the app on the store. So it never runs concurrently with a refresh: every exchange takes `pg_advisory_xact_lock` on `shopify_token:{store}` and then the row `FOR UPDATE`, in one transaction. On the first link the row is inserted inside that transaction. On a linked store, the embedded status re-exchanges only when the stored access token is missing or unreadable, the grant is dead, or the configured scopes are newer than the last exchange; it then writes the token keys only (no new `connected_at`, no audit event).

**Refresh:** `services::shopify::fresh_access_token` is the only refresh path. It locks the row (`SELECT … FOR UPDATE`) for the whole refresh, refreshes only when the access token expires within five minutes and writes every token key in one update. Shopify rotates the refresh token, so a second concurrent refresh would store a dead one. When Shopify rejects the refresh token, the row records the grant as expired; the status then reads `needs_reconnect`, and the next time a staff member opens the app in the Shopify admin the token exchange heals it.

## Settings

`updateShopifySettings` / `PUT /v1/connections/shopify/settings` and, from the Shopify admin, `PUT /v1/shopify/embedded/settings` set three values. Every field is optional; a request without any is `400` (`Nothing to update: …`), and an omitted field keeps its value.

| Field | Values | Default |
|---|---|---|
| `customer_display` | `none`, `first_name`, `first_initial`, `first_name_last_initial`, `custom_name`; see [Integrations → Shopify customer label](./integrations.md#shopify-customer-label-customer_display). Any other value is `400` with `Config field 'customer_display' must be one of: …` | `none` |
| `show_items` | Boolean: order events carry the line items (title, quantity) | `true` |
| `show_price` | Boolean: order events carry the total with its currency, plus each item's price when items are shown | `false` |

A missing or non-boolean `show_items` / `show_price` in a stored config reads as its default. Setting the current values changes nothing. The settings apply to orders that arrive afterwards; stored events keep what they had.

Each changed value emits one `account:shopify_settings_updated` (`setting`, `from`, `to`; actor = the member from Lumio, none from Shopify with `shopify_user_id`). A change made in the Shopify admin also sends the account owner an in-app notice (`shopify_settings_changed`): these settings decide which buyer names and order details reach the stream.

All three values are written to the metafields the [storefront blocks](#storefront-blocks) read, as two copies in one `metafieldsSet` (all six or none): `customer_display` (text) and the booleans `show_items` / `show_price` on the **app installation** (app-data metafields, namespace `lumio`, read by the cart block) and on the **shop** (app-reserved namespace `$app:lumio`, read by the checkout block, which cannot read app-data metafields). The write runs under the row lock, after a fresh token, and is recorded in `customer_display_synced` on success; a disconnect deletes both copies. A block picks its consent text by them and renders nothing without them. If Shopify fails, the Lumio value still changes (it is the only source of truth; the webhook never reads the metafields), and the embedded status or the next link completion pushes it again.

### Order details

`show_items` and `show_price` act when the order webhook arrives: what is off is never stored (see [Webhooks → Shopify](./webhooks.md#shopify)). Items off means no `line_items`; price off means no `total_price`, no `currency` and no item `price`. Together with the name form they give every combination: name only, name with items, items only, prices. The buyer's consent record carries the details its text named, and a label is shown only while the current details are covered (see [Integrations → Shopify customer label](./integrations.md#shopify-customer-label-customer_display)).

### Hide a buyer name

`hideShopifyOrderName(eventId, createdAt)` / `POST /v1/connections/shopify/events/{event_id}/hide-name` (body `{ "created_at": "<RFC 3339>" }`) removes the buyer label from one order. It needs `events:edit` (Owner and Administrator by default). It is not gated on `integration:shopify`, so a stored name can still be hidden after the plan loses Shopify.

- `created_at` is the event's timestamp from the feed and must match within 1 s. The `customer_display` key is removed (not blanked) from that event **and** from the other event of the same order (`order:{id}` / `order_paid:{id}`) within 7 days of it. Each update touches only the compressed batch that holds the row.
- The events themselves stay, so a redelivery from Shopify cannot bring the name back.
- The answer is `true` when a name was removed and `false` when there was none left (no audit event then). An event that is not a Shopify order event of the account is `404`.
- The name is hidden **in Lumio**: what was already shown on the overlay, sent to an automation or to a widget is not recalled.

A hide emits `account:shopify_order_name_hidden` (`platform`, `event_id`; never the name).

## Storefront blocks

The buyer's consent for a name on the stream comes from two blocks of the Shopify app project `apps/shopify/` (Shopify CLI). Both write the same two **private** cart attributes, which reach the order's `note_attributes` and show on the order in the Shopify admin (the consent record), but not on the storefront or the checkout: `__lumio_name_consent` and `__lumio_stream_name` (see [Integrations → Shopify customer label](./integrations.md#shopify-customer-label-customer_display)).

| | Cart block | Checkout block |
|---|---|---|
| Extension | Theme app extension `extensions/name-consent-cart`, app block `name-consent` (theme editor name "Name on livestream" / „Name im Livestream“) | Checkout UI extension `extensions/name-consent-checkout`, target `purchase.checkout.block.render`, default placement `INFORMATION2` |
| Shops | Every plan with an Online Store 2.0 theme; only on the cart template | Shopify Plus only |
| Reads | `app.metafields.lumio.*` (Liquid) | `$app:lumio` shop metafields (`owner_type = "SHOP"`) |
| Writes | `POST /cart/update.js` | `applyAttributeChange` (extension `api_version = "2026-10"`) |
| Renders nothing when | form `none`/missing, a flag missing, the shop has no privacy policy, the cart is empty | form `none`/missing, a flag missing, `canUpdateAttributes` false, an accelerated checkout (Apple Pay, Google Pay), a failed write |

- **Forms `first_initial`, `first_name`, `first_name_last_initial`:** an unticked checkbox. Unticked writes `__lumio_name_consent = "0"` (also on render), ticked writes `<form>:2:<scope>` for the text on screen. **Form `custom_name`:** an optional text field with a `n/25` counter. A valid name writes `__lumio_stream_name` and `__lumio_name_consent = custom_name:2:<scope>`; an empty, too long or disallowed name writes `"0"` and an empty name and shows why. The block checks the name like the server does (NFKC, letters/marks/digits, space, `- ' . _`, at most 25 characters); the server check stays authoritative.
- **Texts** are fixed (no theme-editor setting) and come from the extensions' `locales/` (`en` and `de`; every other storefront language gets English). The explanation names the form and the order details from the store's `show_items` / `show_price`. No app name appears in either block; each links the shop's privacy policy (cart: `shop.privacy_policy.url`, checkout: `{storefront}/policies/privacy-policy`).
- **`sessionStorage`** (cart block, `custom_name` only): key `lumio_stream_name` holds the typed name, written on input, removed when the field is cleared, so the field survives a reload. Nothing else is stored in the browser.
- **Network:** the cart block calls only the shop's `cart/update.js`, the checkout block makes no request. The app configuration declares `[network_access]` with empty `allowed_sources` and `allowed_navigation_hosts`.

### App configuration

`apps/shopify/shopify.app.staging.toml` and `shopify.app.production.toml` hold one Shopify app per environment. They set `embedded = true`, the app URL (`https://lumio.shopify.staging.zaflun.dev` / `https://shopify.lumio.vision`), `scopes = "read_orders,read_products,read_legal_policies"` (must equal `[shopify] scopes`), one never-called redirect URL, the webhook subscriptions (`orders/create` + `orders/paid` and `products/create` with `include_fields` limited to what `lo_shopify::Order` / `Product` parse, `app/uninstalled`, the compliance topics) on `api_version = "2026-10"`, `[access.admin]` (Direct API access in online mode, for the embedded page's Plus check) and `[network_access]`. `client_id` is a placeholder until the app exists in the Dev Dashboard; it must equal `[shopify] client_id` of that environment.

Build and check locally from `apps/shopify`: `npx @shopify/cli@5.0.0 app build --config staging` (bundles both extensions and runs theme check). Release: `shopify app deploy --config staging|production` creates and releases an app version with the configuration and both extensions; it does not deploy the embedded web page.

### Embedded page image

The embedded web page ships as the container image `ghcr.io/zaflun/lumio/shopify`, built from `docker/shopify.Dockerfile` (Next.js standalone output, port `4004`, health check `GET /api/health`) by `release-images.yml` for a release tagged `shopify@{version}` (also part of `all-web` and `all`), signed and attested like the other web images ([Deployment](../developer-guide/deployment.md)). CI's *Next Build* job builds `apps/shopify` whenever it changes. Runtime environment variables, all read at request time:

| Variable | Purpose |
|---|---|
| `LUMIO_API_URL` | Lumio API base including `/v1` (e.g. `https://api.lumio.vision/v1`); the route handlers forward to `/v1/shopify/embedded/*` |
| `LUMIO_WEB_URL` (fallback `NEXT_PUBLIC_WEB_URL`) | Web app origin for "In Lumio öffnen" and the link tab |
| `LUMIO__SHOPIFY__CLIENT_ID` | The app's client id, same value as the API's `[shopify] client_id` |
| `LUMIO__SHOPIFY__CLIENT_SECRET` | Client secret for the launch `hmac` check (secret, ENV only) |
| `LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS` | Previous client secret during a rotation (optional, secret) |
| `SENTRY_DSN` (fallbacks `LUMIO_PUBLIC_SENTRY_DSN`, `NEXT_PUBLIC_SENTRY_DSN`) | Optional. Server-side error reports to Sentry; without a DSN Sentry stays off. No browser SDK, see [Error Tracking](../developer-guide/error-tracking.md) |

## Disconnect and uninstall

- **Disconnect** (`disconnectShopify` / `DELETE /v1/connections/shopify`, or `POST /v1/shopify/embedded/disconnect` from the Shopify admin) first clears the storefront metafields (best effort, with a fresh token, so the blocks stop asking buyers), then deletes the row and writes an `app/uninstalled` tombstone (`webhook_id = local:<uuid>`) into `shopify_compliance_requests` in one transaction. A disconnect from the Shopify admin also sends the account owner an in-app notice (`shopify_disconnected`). The app stays installed in the store until the merchant removes it in the Shopify admin. The webhook subscriptions are app-level, so **Shopify keeps sending** order webhooks for the store after a disconnect; they are dropped on arrival (no linked row: `200`, nothing stored).
- **Uninstall** in Shopify delivers `app/uninstalled`; the webhook deletes the row and writes the tombstone under Shopify's webhook id (see [Webhooks → Shopify](./webhooks.md#shopify)).

The tombstone records the account, the store and the moment (`window_end`). A later `shop/redact` from Shopify uses it to find whose events to erase, even after the store was reinstalled elsewhere.

## Compliance webhooks

Every App Store app must take Shopify's three mandatory compliance webhooks, answer an invalid `hmac` with `401` and a valid delivery with a fast `2xx`, and finish the work within 30 days. Lumio receives them at `POST /v1/webhooks/shopify/compliance` (a compliance topic sent to `/v1/webhooks/shopify` is handled the same way). See [Webhooks → Shopify compliance topics](./webhooks.md#shopify-compliance-topics) for the receipt.

**Queue, never inline.** A verified delivery becomes one row in `shopify_compliance_requests` (unique on `X-Shopify-Webhook-Id`, so a redelivery adds nothing) and is answered `200` at once. The row holds the store, the order ids from the payload and the account that holds the store at receipt, whether or not the integration is paused. The payload itself (customer id, e-mail, phone) is never stored. The compliance worker (`workers::shopify_compliance`, always on, every minute, safe on several replicas) does the work in `services::shopify_compliance`:

| Topic | What Lumio does | Done |
|---|---|---|
| `customers/redact` | Deletes the listed orders' `shopify:order` / `shopify:order_paid` events, with or without a customer label: through the order number the rest of the event (amount, line items, time) is still the customer's data for the merchant. Other orders, products and other accounts stay. No cache keeps a deleted event: the live broadcast stores nothing, and the dead-letter copy is caught by the second pass. | After the second pass |
| `shop/redact` | Deletes the store's `shopify` events of every account that held it, up to the moment it stopped holding it (`window_end` of the tombstone). Events of other platforms and of a store the account connected later stay. A connection row that `app/uninstalled` never reached is removed first, like an uninstall. | After the second pass |
| `customers/data_request` | Looks up the listed orders, writes the audit event (counts only) and sends the channel owner an in-app notice. | At once |

**Whose data.** The tenants of a store are the account that holds it now and every account named in an `app/uninstalled` tombstone of that store. A store Lumio never knew completes as a no-op.

**Second pass.** A failed event insert is parked in Redis for up to 72 hours and replayed later, so a parked copy could land after a redaction. A redaction therefore runs on receipt and again 73 hours after receipt, and completes only on that second pass.

**Retries.** A failed pass is retried with a backoff of 2^attempts minutes, capped at six hours, and never dropped. After ten passes it is logged as an error. The metric `shopify_compliance_passes_total{topic, outcome}` counts `completed`, `recheck`, `failed` and `stuck`.

**What the data request tells the merchant.** The merchant (the streamer) answers the customer; Lumio does not contact the customer or Shopify. The owner's notice (in the app only, no e-mail) names the store and the order ids Lumio holds data for, and says what that is: order number, amount, currency, payment status, line items (product, quantity, price) and time, and the customer label if one is set. Order ids with no stored event are listed as having no data. When nothing matches, or the request lists no orders, the notice says Lumio holds no data for the request. The label value itself is never shown in the notice or the audit log. The notice links to the events page, where the orders are.

**What the queue keeps.** A completed request keeps no order ids: only the store, the account and the timestamps. Completed requests are deleted 30 days after completion (Shopify API Terms §6.2.3: Merchant Data goes within 30 days); open requests are never swept. An `app/uninstalled` tombstone goes 30 days after its account last held `shopify` events of that tenancy (created before its `window_end`): the daily sweep checks each tombstone against TimescaleDB and restarts its clock (`completed_at`) while such events exist. After a disconnect in Lumio the app stays installed, so no `shop/redact` comes, the events stay for their normal retention, and Shopify sends `customers/redact` up to six months after the customer's last order; the tombstone is what still names the old account then. After a real uninstall `shop/redact` deletes the events within about five days, so the tombstone goes about 30 days after that. A tombstone whose account was deleted goes 30 days after completion. The audit events (24 months, store address and counts only) are the lasting record.

## Audit

| Event | Scope | Actor | Metadata |
|---|---|---|---|
| `account:integration_connected` | account | The member who confirmed the link | `platform`, `shop_host`, `scopes`, `source` (`shopify_admin`), `shopify_user_id` |
| `account:integration_disconnected` | account | The member (disconnect in Lumio) or none (from the Shopify admin, `app/uninstalled`) | `platform`, `shop_host`, `reason` (`user` / `shopify_admin` / `app_uninstalled`), `shopify_user_id` (Shopify admin only) |
| `account:shopify_settings_updated` | account | The member (Lumio) or none (Shopify admin) | One event per changed value: `platform`, `shop_host`, `setting` (`customer_display` / `show_items` / `show_price`), `from`, `to`, `source` (`lumio` / `shopify_admin`), `shopify_user_id` (Shopify admin only) |
| `account:shopify_order_name_hidden` | account | The member | `platform`, `event_id` |
| `account:shopify_data_request` | account | none | `platform`, `shop_host`, `orders_requested`, `orders_found`, `orders_with_label` |
| `account:shopify_customer_redacted` | account | none | `platform`, `shop_host`, `orders` (count) |
| `account:shopify_shop_redacted` | account | none | `platform`, `shop_host` |

No token, customer label or customer contact ever appears in the metadata. Events written from the Shopify admin (`/v1/shopify/embedded/*`) record the browser's user agent but no IP address and no location; `shopify_user_id` and `shop_host` identify who acted. See [Audit log](./audit-log.md).

## Configuration

`[shopify]` in the API config (`LUMIO__SHOPIFY__*`): `client_id`, `client_secret` and `client_secret_previous` (both ENV only), `api_version` (default `2026-10`), `scopes` (default `read_orders,read_products,read_legal_policies`) and `app_store_url`. See [Installation → Configuration](../getting-started/installation.md) and [OAuth setup → Shopify](../getting-started/oauth-setup.md#shopify).

### Client-secret rotation

Every Shopify signature check tries `client_secret` first and `client_secret_previous` second: the embedded page's ID token, the launch `hmac` in `apps/shopify`, and the HMAC of every webhook delivery (`/v1/webhooks/shopify` and `/v1/webhooks/shopify/compliance`). Shopify signs webhooks with the app's **oldest unrevoked** secret, so during a rotation order and compliance webhooks still carry the old signature ([Manage your app credentials → Rotate your client secret](https://shopify.dev/docs/apps/build/authentication-authorization/manage-credentials#rotate-your-client-secret)). Rotate without downtime in this order:

1. In the Dev Dashboard (app → **Settings** → **Credentials**) click **Rotate** next to the client secret and generate a new one. The old secret stays active.
2. Set `LUMIO__SHOPIFY__CLIENT_SECRET` to the new secret and `LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS` to the old one, on the API **and** on `apps/shopify`, and restart both. The token calls (exchange, refresh) now use the new secret; the verifiers accept both.
3. Let the access tokens move to the new secret. A store's token is re-pinned to the new secret when it next refreshes (`fresh_access_token` refreshes on the first use after the one-hour access token runs out) or when a staff member next opens the app (token exchange). A store that is not used before step 4 reads `needs_reconnect` afterwards and heals the next time the app is opened in its Shopify admin.
4. Revoke the old secret in the Dev Dashboard. From then on Shopify signs with the new secret.
5. Watch `shopify_client_secret_matches_total{secret="previous"}` (both `verifier="id_token"` and `verifier="webhook"`). Once it stops increasing, remove `LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS` on both services and restart.

If a secret is being actively misused, revoke it first (step 4) and accept the downtime: until the new secret is set, ID tokens and webhooks signed with it are refused with `401`, and Shopify retries the webhooks.

### Monitoring

The API exposes two Shopify series on its internal `/metrics` port ([Metrics](../developer-guide/metrics.md)):

| Metric | Labels | Meaning |
|---|---|---|
| `shopify_client_secret_matches_total` | `verifier` (`id_token`, `webhook`), `secret` (`current`, `previous`) | Verified Shopify signatures, by the client secret that signed them. `secret="previous"` is non-zero only during a rotation. |
| `platform_api_requests_total{platform="shopify"}` | `endpoint` (`/admin/api/{version}/graphql.json`, `/admin/oauth/access_token`), `outcome` (`ok`, `unauthorized`, `forbidden`, `rate_limited`, `client_error`, `server_error`, `unexpected_status`, `transport_error`) | Every response of an outgoing Admin API or token-endpoint call. |

`outcome="forbidden"` (HTTP `403`) on either endpoint usually means the Shopify [IP allowlist](https://shopify.dev/docs/apps/build/dev-dashboard/ip-allowlist) does not contain the egress address of the host that made the call. The best-effort calls (settings sync to the storefront metafields, metafield cleanup on disconnect) do not fail the user's action, so this counter and the matching `WARN` log line (`Shopify Admin API answered 403 Forbidden`, with the endpoint only, never the store or a token) are the signal. No label carries a store or account.

---

## Features / Auth

Source: https://docs.lumio.vision/features/auth

# Auth

## Overview

Lumio supports email/password and platform sign-in through the ID app. The API resolves eleven auth contexts (including developer keys and Anonymous), handles sessions and 2FA, and enforces RBAC through `lo-auth`.

In **Security → Sign-in**, a passkey row shows the user's label and the provider name or YubiKey model when known. A provider logo appears next to that name when available; providers without a usable logo and unknown providers show a generic passkey symbol. The trademark notice appears below the list whenever a provider logo is visible. See [Account Security](/user-guide/account-security) for setup and recovery.

### Auth Types

| Type | Prefix | Use Case | Rate Limit |
|------|--------|----------|------------|
| **System Key** | `lm_sys_` | Internal service-to-service communication | Unlimited |
| **User API Key** | `lm_usr_` | Personal, per-member external API access | 1200 req/min |
| **Service Key** | `lm_svc_` | Account-owned key for CI/CD & integrations (survives member departure) | 1200 req/min |
| **Developer API Key** | `lm_dev_` | Approved developer or team extension development | 1200 req/min |
| **JWT** | `lm_` + `eyJ...` | Session-based auth after OAuth login | 600 req/min |
| **Popout Token** | `lm_pop_` | Browser-source and dashboard popout access with a scoped RBAC permission set | 600 req/min |
| **Overlay Token** | `lm_overlay_` | One-overlay browser-source WebSocket access | 600 req/min |
| **Shared Overlay Token** | `lm_share_` | Time-limited shared overlay WebSocket access | 600 req/min |
| **Extension Token** | `lm_ext_` | Short-lived extension iframe/runtime access | 600 req/min |
| **Widget Token** | `lm_widget_` | One-widget browser-source WebSocket access | 600 req/min |
| **Anonymous** | (none) | Unauthenticated public access | 120 req/min |

Token type is automatically identified from the prefix via `identify_token()`.

## Architecture

```
Client Request
    |
    v
Auth Middleware (identify_token -> resolve AuthContext)
    |
    +-- lm_sys_* --> System Key lookup (config + DB, hash match)
    +-- lm_usr_* --> User API Key lookup (DB, hash match)
    +-- lm_svc_* --> Service Key lookup (account_service_keys, hash match)
    +-- lm_dev_* --> Developer API Key lookup
    +-- lm_share_* --> Shared overlay token lookup
    +-- lm_overlay_* --> Overlay token lookup
    +-- lm_ext_* --> Extension token lookup
    +-- lm_widget_* --> Widget token lookup
    +-- lm_eyJ* --> JWT validation (decode + verify)
    +-- ?token=lm_pop_* --> Popout token lookup (DB, hash match)
    +-- (none)  --> Anonymous
    |
    v
AuthContext (enum: System | ApiKey | ServiceKey | DeveloperKey | User | PopoutToken | OverlayToken | SharedOverlayToken | ExtensionToken | WidgetToken | Anonymous)
    |
    v
Permission checks (PermissionGuard / require_permission)
    |
    v
Handler / Resolver
```

### OAuth Login Flow

1. User initiates login in the **ID App** (NextAuth-based).
2. ID App handles OAuth with the provider (Twitch, YouTube/Google, Discord, Kick).
3. ID App calls the `exchangeToken` GraphQL mutation with:
   - Provider name and provider-specific user ID
   - OAuth access token
   - User profile (display_name, username, avatar_url, email)
4. The API finds or creates the user via `find_or_create_user_by_provider`.
5. If 2FA is enabled, the API returns a pending challenge. The ID app offers a passkey, authenticator app code or recovery code before creating the session or a PKCE code. A passkey sign-in completes both steps. A trusted device may skip this step for 30 days.
6. Once the sign-in is complete, a session is created with a SHA-256 hash of the refresh token's `jti` and cached in Redis.
7. A JWT and refresh token are returned. Email/password sign-in follows the same 2FA gate. Confirming an email address alone never signs the user in.

Changes to sign-in methods and enabling 2FA require a fresh identity confirmation on the interactive session. The confirmation expires after ten minutes. With 2FA enabled, a passkey, authenticator app code or recovery code counts; without it, the user can confirm with an existing platform connection or email password. A reconnect to the same provider account is exempt. Platform OAuth step-up does not request provider `max_age`, so a provider may reuse an existing login session.

### Token Refresh Flow

1. Client sends expired JWT's refresh token to the `refreshToken` mutation.
2. Refresh token is validated and the session is looked up by token hash.
3. A new JWT is issued with the same session ID.
4. A new refresh token is issued with the remaining session lifetime (refresh token rotation). The session's `token_hash` is updated atomically, invalidating the old refresh token.

### Proxy-Level Auto-Refresh

All three Next.js apps (web, admin, ID) run a `proxy.ts` that intercepts every request and proactively refreshes the JWT when it is within 60 seconds of expiry. The proxy calls the GraphQL `refreshToken` mutation directly and sets updated cookies on the response. The user experiences no interruption.

If the API is unreachable during a refresh attempt, the proxy passes the request through without logging out - the page renders and shows a service-unavailable error instead.

Public web pages that show the signed-in viewer refresh too, but never redirect to the login: the marketing pages (`/`, `/features`, `/pricing`, `/music`, `/invite`, `/ideas` and their sub-pages), `/legal/*`, `/withdraw`, `/cancel`, the session-reading public API `/api/ideas/*`, and `/popout/*` when no popout session cookie is present (the popout then falls back to the dashboard cookie). With an expired JWT and a valid refresh cookie the page renders signed in. Without a session, or when the refresh is refused, the page renders signed out and the cookies stay as they are. File routes such as `/ideas/feed.xml`, `robots.txt` and `sitemap.xml`, the share images under `/og/`, the share pages under `/share/`, and `/overlay` / `/widget` (they authenticate with their own token) are never refreshed: a shared cache could replay a `Set-Cookie` on a cacheable response to other visitors.

### Cross-Origin Request Guard

The session cookies are `SameSite=Lax`. SameSite counts a whole site, so a request from any sibling origin (for example `docs.lumio.vision` to `lumio.vision`, or one `*.zaflun.dev` host to another) still carries them. The `proxy.ts` of all three Next.js apps therefore refuses a `POST`, `PUT`, `PATCH` or `DELETE` to `/api/*` with `403 FORBIDDEN` unless it comes from the app's own pages:

- With a `Sec-Fetch-Site` header (every current browser), only `same-origin` passes.
- Without it, the `Origin` header must equal the app's configured public origin: `LUMIO_APP_URL` for web and admin (web also accepts the overlay origin from `LUMIO_OVERLAY_URL`), `AUTH_URL` for the ID app. A request with neither header is refused.

The guard runs before any auth check, so it also covers the public `/api/*` routes. `GET`, `HEAD` and `OPTIONS` are not checked. The only exemption is web's `/api/csp-report`, which browsers post to from the overlay and widget pages. The check lives in `shared/api/src/same-origin.ts` (`@lumio/api/same-origin`); a new route that must accept cross-origin writes needs an explicit, commented exemption in that app's `proxy.ts`.

### Client-Side Refresh Timer

The web and admin apps run a `useTokenRefresh()` hook that proactively refreshes the JWT for long-lived pages (popouts, chat, dashboards left open overnight). The scheduler lives in `src/lib/token-refresh.ts` of each app; it calls `POST /api/auth/refresh` and reacts to the answer:

- **Success** - the next refresh is scheduled 5 minutes before the new token expires (at least 60 seconds later).
- **401** - the session is dead (revoked, expired, or another tab already rotated the refresh token). The hook stops for good and reloads the page **once**. The reload goes through the proxy: for a dead session it clears the cookies and redirects to the ID login; if another tab won the rotation, the browser already holds the new cookies and the page simply loads. A `sessionStorage` marker allows at most one such reload per 5 minutes, so a reload loop is impossible.
- **Popouts** (`/popout/*`, also in OBS) stop on a 401 and never reload: the proxy skips `/popout`, so a reload would not clear anything.
- **Network error, 5xx or 429** - retried with exponential backoff: 60 s, 2, 4, 8 minutes, capped at 15 minutes. A success resets the backoff.
- **Single-flight across tabs** - each refresh runs inside the Web Locks API lock `lumio-token-refresh` (`navigator.locks`; a plain call where the API is missing), so two tabs never rotate the same refresh token at once.

The timer only fires while the tab is visible; becoming visible again triggers an immediate refresh unless the hook has stopped.

Neither the refresh route nor the proxies' `/api/*` branch deletes cookies on a failed refresh. Refresh-token rotation has no grace window, so with two concurrent refreshes the loser's delete could overwrite the winner's fresh cookies and log the user out. Only the page-navigation branch of the proxy clears them.

### Logout Flow

1. Client sends the refresh token to the `logout` mutation.
2. Session is deleted from PostgreSQL and Redis.
3. Returns success even if the token was already expired.

## API

### GraphQL Queries

| Query | Args | Returns | Guard |
|-------|------|---------|-------|
| `me` | -- | `MeResult!` | `AuthGuard` |
| `myPermissions` | -- | `[String!]!` | `AuthGuard` |

**`MeResult`** includes:
- User profile (`id`, `displayName`, `email`, `avatarUrl`, `createdAt`)
- `activeAccountId` (nullable)
- `accounts: [AccountMembership!]!` (role, plan, owner status, the channel's name and picture as `identity`)
- `permissions: [String!]!` -- resolved account-scoped permissions
- `adminPermissions: [String!]!` -- resolved admin-scope permissions
- `userPermissions: [String!]!` -- resolved user-scoped (cross-account, non-admin) permissions, e.g. Ideas Hub `ideas:moderate_*`. This is the exact set `AuthContext::require_user_permission` enforces, so the frontend can gate user-scoped controls on it without drifting from the backend. Account-independent (unchanged by an active-account switch). REST parity: `user_permissions` on `GET`/`PATCH /users/me`.
- `loginConnections: [LoginConnection!]!`
- `enabledFeatures: [String!]!`
- `featureStatuses: [FeatureStatusGql!]!` -- merged account-scope flags plus the user-scope `system:account_creation` flag
- `token: String` -- present only when `updateMe` switched the active account
- `ownedAccountCount: Int!` / `maxAccounts: Int!` -- multi-account ownership counters
- `streamerMode: Boolean!` -- hides sensitive data in the UI
- `isDeveloper: Boolean!` -- has a `developer_profiles` entry or an admin override
- `extensionDevMode: Boolean!` -- load draft extension versions
- `locale: String!` -- UI language preference: `auto` · `en` · `de`
- `timezone: String!` -- timezone preference: `auto` or an IANA name
- `dateFormat: String!` -- date-format preset: `auto` · `dmy_dot` · `dmy_slash` · `mdy_slash` · `ymd_dash`
- `timeFormat: String!` -- time-format preset: `auto` · `h12` · `h24`
- `seasonLookEnabled: Boolean!` / `seasonStrength: String!` (`full` · `subtle`) / `seasonMotion: String!` (`auto` · `off`) / `seasonCreatures: JSON!` / `seasonBannerDismissed: [String!]!` -- seasonal-look preferences (see [GraphQL API](../api-reference/graphql.md))
- `motionPreference: String!` -- "Animations in Lumio": `system` · `reduced` · `off` (see [GraphQL API](../api-reference/graphql.md))

The four display preferences, the five seasonal-look preferences and the motion preference are user-global (stored on `users`, applied across the webapp) and settable via `updateMe` / `PATCH /users/me`; an invalid value is rejected fail-closed on both protocols (never coerced to `auto`), and changing them emits no audit event.

### GraphQL Mutations

| Mutation | Args | Returns | Guard |
|----------|------|---------|-------|
| `exchangeToken` | `input: ExchangeTokenInput!` | `TokenResult!` | None (public) |
| `refreshToken` | `refreshToken: String!` | `TokenResult!` | None (public) |
| `logout` | `refreshToken: String!` | `LogoutResult!` | None (public) |
| `logoutSession` | -- | `LogoutResult!` | `AuthGuard` |
| `disconnectLoginConnection` | `loginConnectionId: UUID!` | `LogoutResult!` | `AuthGuard` + session + step-up |
| `updateMe` | `input: UpdateMeInput!` | `MeResult!` | `AuthGuard` |

#### ExchangeTokenInput

```graphql
input ExchangeTokenInput {
  provider: String!      # "twitch", "discord", "google", "kick"
  providerId: String!    # Provider-specific user ID
  accessToken: String!   # OAuth access token from provider
  profile: ProviderProfileInput!
}

input ProviderProfileInput {
  displayName: String!
  username: String
  avatarUrl: String
  email: String
}
```

#### TokenResult

```graphql
type TokenResult {
  token: String!         # Lumio JWT (short-lived, lm_ prefix)
  refreshToken: String!  # Refresh token (long-lived)
  expiresAt: String!     # JWT expiration (ISO 8601)
  isNewUser: Boolean!    # First login ever
  hasAccount: Boolean!   # User has at least one account
}
```

### REST Endpoints

Auth REST endpoints are public (no permission guard) unless noted. They live under `/v1/auth`.

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/v1/auth/token` | Issue a JWT for a dashboard login (ID App -> API handshake). |
| `POST` | `/v1/auth/refresh` | Exchange a refresh token for a new JWT. |
| `POST` | `/v1/auth/logout` | Invalidate the current refresh token/session. |
| `POST` | `/v1/auth/authorize` | OAuth 2.0 authorize handshake for downstream clients. |
| `POST` | `/v1/auth/token/exchange` | Exchange a provider OAuth token for a Lumio JWT. |
| `POST` | `/v1/auth/link` | Link an additional provider identity to the authenticated user (session JWT required; a new link also needs a step-up, a reconnect of the same connection does not). |
| `POST` | `/v1/auth/ws-token` | Mint a short-lived WebSocket handshake token for the current principal. |
| `POST` | `/v1/auth/popout/exchange` | Exchange a raw `lm_pop_*` token for the short-lived popout session cookie (see [Popout Tokens](#popout-tokens-lm_pop_)). |

Bodies are `application/json` with snake_case fields. Response shapes match the GraphQL `TokenResult` / `LogoutResult` types.

### Step-up before sign-in changes

Turning on two-factor authentication (`POST /v1/users/me/mfa/setup` and `POST /v1/users/me/mfa/enable`, GraphQL `startMfaSetup` / `enableMfa`), linking a new sign-in (`POST /v1/auth/link` without `reconnect`) removing one (`DELETE /v1/login-connections/{id}`, GraphQL `disconnectLoginConnection`) dissolving a channel (`DELETE /v1/accounts/{id}`, GraphQL `dissolveAccount`, ZAF-2052) and scheduling a channel dissolution (`POST /v1/accounts/{id}/dissolution`, GraphQL `scheduleAccountDissolution`) need a step-up on the calling session in the last 10 minutes. Without it both protocols answer `403` with code `STEP_UP_REQUIRED` and the message "Please confirm that it's you first", and nothing changes. The dashboard then shows its "Is it you?" dialog. Without 2FA the step-up is a platform round trip or the password; with 2FA a passkey, app code or recovery code counts.

`enableMfa` checks the mark again, so a setup started under a fresh mark cannot be finished after the mark ran out. A reconnect (`reconnect: true` with the `connection_id` of a connection of the same platform account) adds no new sign-in and needs no step-up. Removing a connection checks the "last sign-in method" rule first, so nobody is asked to confirm a removal that cannot happen; dissolving checks `account:delete`, ownership, the active account, the typed name and the absence of an active subscription (`ACTIVE_SUBSCRIPTION`) first in the same way. Cancelling a scheduled dissolution needs no step-up. API keys, service keys and popout tokens cannot hold a step-up, so they cannot dissolve a channel.

The ID app calls `/v1/auth/link` with the shared `lumio-token` session cookie, so a step-up done in the dashboard counts for the link that follows.

In the dashboard (**Security › Sign-in**) the dialog comes before each of these actions and is skipped while the session counts as confirmed:

- **Two-factor › Set up** confirms before step 1 of the set-up dialog. **Turn on** asks again if the mark ran out during the set-up.
- **Add connection › Continue to …** confirms before the hop to the ID app. **Reconnect** needs no confirmation.
- **Remove connection** (the unlink icon on a connection) first asks "Remove connection?", then confirms, then removes.

If the user confirms through a platform or the password, the dashboard remembers the action and continues it after `?step_up=ok`. If the server still answers `STEP_UP_REQUIRED` because the mark ran out in the meantime, the dialog opens again instead of an error. When the mark runs out while the user is at the platform during a link, the ID app returns `link_result=step_up_required` to the dashboard. The dashboard then asks again and repeats the link with the same channels.

The ID app's confirm card names the reason and the account. The dashboard adds two display-only parameters: `purpose`, one of `deleteProfile`, `export`, `dissolveChannel`, `emailLogin`, `mfa`, `addSignIn` or `removeSignIn`, and `account_name`, the selected platform account. The card shows the reason in its subtitle, for example "Lumio asks before you delete your profile", and the button reads "Confirm with Twitch · cruex". Unknown values fall back to a general sentence. Neither parameter grants anything; the API checks the account itself. **Choose another sign-in** returns with `step_up=choose`. The dashboard resumes the stored action, and because nothing was confirmed, its dialog opens again.

### User / Session Endpoints

These live under `/v1/users/me` and are covered in detail in [Sessions](/features/sessions) and the Users resource.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/users/me` | Auth | Current user profile + permissions |
| `PATCH` | `/v1/users/me` | Auth | Update email, preferences, active account (not the display name - see below) |
| `PUT` | `/v1/users/me/name-source-connection` | Session | Choose the display name + avatar source: a login connection or own details (`kind`) |
| `PATCH` | `/v1/users/me/display-name` | Session | Set the own display name (own details only) |
| `POST` | `/v1/users/me/avatar` | Session | Upload the own profile picture (multipart `file`; REST-only) |
| `DELETE` | `/v1/users/me/avatar` | Session | Remove the own profile picture |
| `GET` | `/v1/users/me/login-connections` | Auth | List provider identities |
| `GET` | `/v1/users/me/sessions` | Auth | List active sessions |
| `DELETE` | `/v1/users/me/sessions/{id}` | Auth | Revoke one session (ownership enforced in handler) |
| `DELETE` | `/v1/users/me/sessions` | Auth | Revoke all other sessions for the current user |

## AuthContext

The `AuthContext` enum is the core of the auth system, resolved by middleware and available in every handler/resolver:

```rust
enum AuthContext {
    System { name, permissions },
    ApiKey { user_id, account_id, label, permissions, rate_tier },
    User { user_id, account_id, session_id, admin_permissions, account_permissions, user_permissions },
    PopoutToken { account_id, user_id, label, permissions, token_hash },
    OverlayToken { token_id, overlay_id, account_id },
    SharedOverlayToken { token_id, overlay_id, account_id, expires_at },
    ExtensionToken { token_id, extension_id, install_id, account_id },
    WidgetToken { token_id, widget_id, account_id },
    Anonymous,
}
```

### Permission Resolution

- **System** -- Checked against the system key's own permission list (not bound to an account, so it can act on any account within those permissions). Internal and cross-account System surfaces additionally require a named grant via `require_system_permission` - the bot fleet's feeds (ZAF-1922), extension functions on any install, draft extension files/bundles and the WebSocket `presence:*` / `sounds:*` channels (ZAF-1976) need `bots:internal`. No System surface is gated on the key type alone.
- **API Key** -- Checked against the key's assigned permissions.
- **User (JWT)** -- Admin-scope and account-scope permission lists are checked in order for the active account.
- **Popout Token** -- Checked against the token's custom permission list.
- **Overlay / Shared Overlay / Extension / Widget Token** -- No RBAC permissions; they only grant their own scoped runtime/WebSocket access.
- **Anonymous** -- Always denied.

Account roles are registry-validated against explicit `resource:action` strings; wildcard grants are not assignable through roles. Runtime wildcard matching only applies to permission lists that legitimately contain wildcards, such as configured system keys.

## JWT Structure

### Claims

| Field | Type | Description |
|-------|------|-------------|
| `sub` | `UUID` | User ID |
| `account_id` | `UUID?` | Active account (can be switched) |
| `session_id` | `UUID?` | References sessions table (JWT auth only) |
| `iat` | `i64` | Issued at (Unix timestamp) |
| `exp` | `i64` | Expiration (Unix timestamp) |
| `jti` | `UUID` | Unique token identifier (UUID v7) |

All JWTs are prefixed with `lm_` for type identification.

## API Keys

### System Keys (`lm_sys_`)

- Generated via `generate_system_api_key()`
- Provisioned through the **Admin panel** (System → System API Keys), stored in the `api_keys` table with `is_system = true` and no owning user/account. The auth middleware resolves them by hash against that table, falling back to any static keys loaded from TOML config.
- Used by internal services and bots. A key reaches only what its scopes allow: the bot fleet's internal surface requires the system-only `bots:internal` grant (ZAF-1922), so each bot/worker key carries it and the `apps/id` audit-ingest key (`audit:ingest` only) reaches nothing else. See [System Keys → Provisioning bot and worker keys](../admin/system-keys.md#provisioning-bot-and-worker-keys).
- 32 random bytes, hex-encoded
- Stored as SHA-256 hash for verification

### User API Keys (`lm_usr_`)

- Generated via `generate_user_api_key()`
- Created by users from **Settings → Channel → Access → API Keys**
- Available when `feature:apikeys` is enabled
- Gated by `apikeys:read` to view keys, `apikeys:create` to create keys, `apikeys:edit` to rename, and `apikeys:delete` to revoke keys
- Personal to the creator within the active account: each key is bound to `(user_id, account_id)`, and users only manage their own keys
- **Member-bound lifetime:** a personal key stops authenticating the moment its owner is no longer a member of the account. Removing the member (or the member leaving) purges their personal keys for that account, and the auth layer additionally refuses any `lm_usr_` key whose owner is not a current member (or the owner) of the key's account. This is the deliberate contrast with account-owned `lm_svc_` service keys below, which **survive** member departure.
- Permission checkboxes can only select a subset of the creator's current permissions; the backend rejects any requested permission the creator does not hold
- Optional expiry can be set at creation time
- Display prefix shows the first 2 chars of the random part (e.g., `lm_usr_ab`)
- Full key shown once on creation, only hash stored in DB
- Revoke hard-deletes the key

### Service Keys (`lm_svc_`)

Account-owned service API keys for CI/CD pipelines and long-lived integrations that must keep working across team changes. Unlike personal `lm_usr_` keys, a service key is **owned by the account, not a member**, and **survives the departure of the member who created it**.

- Generated via `generate_service_api_key()`
- Created from **Settings → Channel → Access → API Keys → Service Keys**
- Available when `feature:apikeys` is enabled (same flag and `apikeys:*` permission family as personal keys)
- Gated by `apikeys:read` to view, `apikeys:create` to create, `apikeys:edit` to rename, and `apikeys:delete` to revoke
- Creating or rotating a service key requires an interactive sign-in session. The caller must hold every permission assigned to the key; rotation rechecks the existing scopes before replacing its secret. An API key cannot create or rotate another service key.
- Stored in the dedicated `account_service_keys` table (never `api_keys`), scoped to `account_id`
- Carries **no member identity**: the middleware resolves it to an account-scoped principal (`AuthContext::ServiceKey`) with the key's own permission list; `user_id` is `None`, so it keeps authenticating after any member - including its creator - is removed from the account
- `created_by` records the minting member only as a nullable audit pointer (`ON DELETE SET NULL`); removing that member sets it to `null` but never deletes the key
- Permission checkboxes can only select a subset of the creator's current permissions; the backend rejects any requested permission the creator does not hold (same `ZAF-371` subset guard as personal keys)
- Optional expiry can be set at creation time
- Display prefix shows the first 2 chars of the random part (e.g., `lm_svc_ab`)
- Full key shown once on creation, only hash stored in DB
- Rename changes the label only; permissions, key material and expiry are immutable once minted
- Revoke hard-deletes the key
- Managed on both protocols: GraphQL `accountServiceKeys` / `createAccountServiceKey` / `updateAccountServiceKey` / `deleteAccountServiceKey` and REST `/v1/service-keys`
- Lifecycle emits account-scoped audit events `account:service_key_created` / `account:service_key_updated` / `account:service_key_revoked`

## Popout Tokens (`lm_pop_`)

- Generated via `generate_popout_token()`
- Long-lived by default, with optional `expires_at` and `revoked_at` lifecycle controls
- Used for browser sources and dashboard popout windows
- Limited, configurable permissions
- 32 random bytes, hex-encoded, SHA-256 hashed for storage
- The raw token is exchanged **once, at page load**, for a short-lived (15-minute) **popout session** cookie (`lumio-popout-token`); it never travels in a proxied API/WebSocket call. Proxy auth reads the session cookie only, so a `?token=` left in a URL can never downgrade an already-logged-in operator to token-scoped rights. See [API authentication](../api-reference/authentication.md#popout-tokens--popout-sessions).
- **Always bound to an explicit user (ZAF-1922):** creating without a user binds the creator, unassigning binds the editor, and there is no fallback to the account owner - a token with no bound user is rejected like an invalid one.
- **Member-bound:** a token bound to a member stops working once that member is no longer part of the account. Removing the member (or the member leaving) deletes the tokens assigned to them for that account, and the raw-token resolver, the exchange, the popout-session resolver and the WebSocket re-validation additionally refuse a token whose assigned member is neither a current member nor the owner of the account.
- An open popout WebSocket is re-validated every 30 seconds and closed with `TOKEN_REVOKED` once its origin token is revoked, expired or deleted (or its member left), and with `TOKEN_EXPIRED` when its session JWT expires. See [Credential re-validation](../api-reference/websocket.md#credential-re-validation).
- Signing out of the webapp (`POST /api/auth/logout`, also used by the footer's **Manage Cookies** → Authentication) deletes `lumio-popout-token` and `lumio-popout-origin` along with the login cookies, so pop-out sessions opened in that browser end too. Both cookies are host-only and are deleted without a domain. An OBS browser source is a separate browser and keeps its session.

## Login Connections

Login connections link OAuth provider identities to Lumio users. Each connection stores:

- Provider name and provider account ID
- Username, display name, avatar URL
- Encrypted OAuth tokens (access_token, refresh_token)
- Scopes and token expiry

Supported providers: **Twitch**, **YouTube** (via Google), **Discord**, and **Kick**.

Discord is a sign-in-only provider. Its login connection cannot be assigned to a channel. In **Security → Sign-in** it shows **Sign-in only** instead of channel chips or **+ Channel**; the add-connection dialog offers no channel selection for Discord. The personal name/avatar source can still be a Discord login connection.

### Display name & avatar source

A user's Lumio `display_name` and `avatar_url` are **derived** from one of their login connections - the *name source* - not entered as free text. The user picks the source connection (persisted as `users.name_source_connection_id`); when none is picked it defaults to their first-ever-connected login (`login_connections.created_at` ascending). On every login the name/avatar are re-mirrored from the resolved source, so signing in through a *secondary* platform never changes them.

Change the source via `PUT /v1/users/me/name-source-connection` (REST) or the `setNameSourceConnection` mutation (GraphQL) - both ownership-checked against the caller's own connections and session-only. The current source is exposed as `name_source_kind` + `name_source_connection_id` on `GET /users/me` / `me`. A channel's name and picture are separate: they come from one of the channel's own channel connections or its own details, never from a login connection (see [Accounts › Channel name and picture](./accounts.md#channel-name-and-picture)).

**Own details** (`name_source_kind = 'own'`, ZAF-2096). The same mutation with `kind: "own"` switches to the user's own details; the current name and picture stay as the starting values and sign-ins no longer overwrite them (`find_or_create_user_by_provider` keeps both when the kind is `own`). E-mail-only profiles are always `own`. With own details, `updateDisplayName` / `PATCH /v1/users/me/display-name` sets the name (trimmed, NFC, 2-32 characters, no control or invisible characters). The picture is uploaded via REST-only `POST /v1/users/me/avatar` and removed via `removeAvatar` / `DELETE /v1/users/me/avatar`. The server checks the size (5 MB), the magic bytes (PNG/JPEG/WebP) and the pixel count (16 MP) itself, then re-encodes the picture as metadata-free 512 px and 128 px WebP in lo-storage (`users/{user_id}/avatar/…`, key prefix in `users.avatar_storage_key`). Switching back to a connection, removing the picture, a replacement and the profile deletion all delete the files. The GDPR "user data only" export contains the picture file. At most two profile or channel pictures are decoded at a time across the API; a further upload gets `503 AVATAR_BUSY` with `Retry-After`. Every change writes `user:profile_identity_changed`. See the [REST reference](../api-reference/rest-api.md#post-usersmeavatar).

## Key Files

| File | Purpose |
|------|---------|
| `crates/lo-auth/src/lib.rs` | Public API re-exports |
| `crates/lo-auth/src/jwt.rs` | JWT creation, validation, refresh token generation |
| `crates/lo-auth/src/context.rs` | `AuthContext` enum with permission checks |
| `crates/lo-auth/src/api_key.rs` | API key generation, hashing, type identification |
| `crates/lo-auth/src/popout_token.rs` | Popout token generation and validation |
| `crates/lo-auth/src/rbac.rs` | Permission constants, default roles |
| `crates/lo-auth/src/error.rs` | Auth error types |
| `apps/api/src/graphql/auth.rs` | GraphQL mutations (exchange, refresh, logout) and `me` query |
| `apps/api/src/db/auth.rs` | User, session, and login connection DB operations |

---

## Features / Billing

Source: https://docs.lumio.vision/features/billing

# Billing

## Overview

The Billing module manages everything related to paid subscriptions: plans, per-account limits, feature gating, Stripe Checkout, the Stripe Customer Portal, invoices, and coupon validation. Lumio delegates all payment processing to Stripe - no card data ever touches Lumio infrastructure. Plans and prices are stored in the database and mapped to Stripe products by price ID, so pricing can be changed in Stripe without redeploying the API.

Every account has exactly one active plan at a time. The plan drives nine hard limits (overlays, widgets, storage, upload size, integrations, chat retention, sound count, sound file size, sound storage) plus a feature-flag set that gates individual modules. Limits can be overridden per account by admins via `account_limits` rows; plan defaults apply otherwise. Two further plan columns - `max_accounts` (multi-account ownership) and `max_commands` (bot command count) - are enforced by their own modules rather than through `accountLimits`; both read straight from the canonical `plans` row.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/billing.rs`) - queries and mutations for billing status, plans, limits, invoices, coupon validation, checkout, portal, and cancellation.
- **REST** (`apps/api/src/routes/billing.rs`) - parity endpoints under `/v1/billing/*` plus the Stripe webhook at `/v1/webhooks/stripe`.
- **Admin** (`apps/api/src/graphql/admin.rs`) - coupon CRUD (`adminCoupons`, `adminCreateCoupon`, `adminUpdateCoupon`, `adminDeactivateCoupon`), plan/feature mapping (`adminSetPlanFeature`), per-account plan override (`adminUpdateAccountPlan`), and per-account limit override (`adminUpsertAccountLimits`).
- **Plan limits** - resolved from the canonical `plans` table (`apps/api/src/db/plans.rs`). The nine `accountLimits` limits apply a per-account `account_limits` override over the plan default via `COALESCE(override, plan)` at each read/enforcement site; `max_accounts` and `max_commands` read the plan row directly (no override). There is no hard-coded Rust limits table - the divergent `PlanLimits::for_plan` was removed in ZAF-1092.
- **Webhook handler** (`apps/api/src/routes/billing.rs`) - verifies Stripe-Signature via HMAC-SHA256, then dispatches on event type.

### Frontend

- **Subscription area** (`apps/web/src/components/settings/sections/plan/subscription-tab.tsx`) - receives plans, billing status and the channel header from `loadSubscriptionSection()` in `apps/web/src/lib/settings/loaders/plan.ts` and drives Stripe Checkout. Its settings gate is owner-only.
- **Invoices area** (`apps/web/src/components/settings/sections/plan/invoices-tab.tsx`) - receives recent invoices from `loadBillingSection()` and opens the Customer Portal in a new tab. Its settings gate is owner-only.
- **Without Stripe** - the Subscription area still loads and shows the plan cards, while checkout and cancellation controls are disabled. The Invoices area sends no invoice query and shows "Billing is not set up in this environment." Platform admins can also see the missing `LUMIO__STRIPE__*` keys. A later `BILLING_DISABLED` invoice error returns the same disabled state without logging it as a failure.
- **Proxy route** (`apps/web/src/app/api/billing/[...path]/route.ts`) - the browser calls `/api/billing/{status,plans,limits,invoices,validate-coupon,checkout,portal,cancel}`; each maps internally to a GraphQL query or mutation via `serverGql`.
- **Admin coupons UI** (`apps/admin/src/app/(admin)/coupons/`), **admin plans UI** (`apps/admin/src/app/(admin)/plans/`), and **admin subscriptions/billing views**.

### Stripe Integration

Three Stripe surfaces are used:

1. **Checkout Sessions** - one-time hosted pages for signup / plan change. Returned URL is redirected to. `success_url` and `cancel_url` both land on `/dashboard?billing=success|cancelled`.
2. **Customer Portal** - Stripe-hosted page for payment method updates, invoice history, plan change, and self-service cancellation. Lumio creates the session with a `return_url` back to `/dashboard`.
3. **Webhooks** - Stripe pushes events to `/v1/webhooks/stripe`. Lumio handles `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, and `invoice.payment_failed`.

All Stripe calls use the `stripe` Rust crate with the secret key from `config.stripe.secret_key`. When `config.stripe.enabled = false`, `billingStatus` still answers (with `billingEnabled: false`) and `plans` still lists the plans, while every other billing endpoint and mutation fails with the code `BILLING_DISABLED` (HTTP 409 on REST, `extensions.code` on GraphQL) - this is the kill-switch used by the dev and test environments, which run without paid tiers. Clients read `billingEnabled` first instead of provoking the error.

## Plan Tiers

Two tiers are sellable: **Free** and **Pro**. Their rows are seeded into the `plans` table, and the database is the runtime source of truth - admins can adjust prices, Stripe price IDs, and feature mappings without a deploy. An Enterprise tier once existed, but its plan row was removed in migration `20260415000009_drop_enterprise_plan` and existing Enterprise accounts were moved to Pro, so nothing resolves to it at runtime.

Seeded plan-row values:

| Plan | Max overlays | Max widgets | Storage | Upload size | Integrations | Chat retention | Max accounts | Max commands |
|------|--------------|-------------|---------|-------------|--------------|----------------|--------------|--------------|
| **Free** | 1 | 3 | 100 MB | 10 MB | 2 | 365 days | 1 | 25 |
| **Pro** | 5 | 20 | 1 GB | 50 MB | 10 | 1095 days | 3 | 200 |

`0` in `max_commands` means unlimited. `0` in `chat_retention_days` does not: the retention sweep treats it as the 1095-day (3-year) maximum for all channel data, and every surface renders it as "3 years". The seeded `plans` rows are the **single canonical source** for every limit - there are no hard-coded Rust fallbacks (ZAF-1092). If a plan row cannot be resolved, the bot-command cap fails open (unlimited) rather than blocking legitimate command creation.

### Account Limit Overrides

Admins may override any of these limits per account via `adminUpsertAccountLimits`. `UpsertAccountLimitsInput` accepts `maxOverlays`, `maxWidgets`, `maxStorageBytes`, `maxUploadSizeBytes`, `maxIntegrations`, `chatRetentionDays`, `maxSounds`, `maxSoundFileSize`, `maxSoundStorageBytes`, and a free-text `notes`. Overrides are stored in `account_limits` and, when present, replace the plan default. `accountLimits` (the authenticated query) returns the merged result as `AccountLimitsResult`.

## User Flow

### Subscribing

1. The owner opens the Subscription area through `/dashboard/settings/channel/subscription`. The settings section route checks ownership, then loads the plans, billing status, channel header and any locked API-key notice on the server.
2. The owner picks a plan and interval (`monthly` or `yearly`). Any eligible coupon is applied to the checkout session; the area has no coupon field.
3. Before the redirect the owner ticks the withdrawal-waiver checkbox (unticked by default, see [Withdrawal waiver and order confirmation](#withdrawal-waiver-and-order-confirmation)). Without it no checkout session is created.
4. Frontend calls `POST /api/billing/checkout` → GraphQL `createCheckout(acceptWithdrawalWaiver: true)` → Stripe Checkout Session.
5. Browser redirects to the returned Stripe URL and completes payment.
6. Stripe posts `checkout.session.completed` to the webhook.
7. Webhook handler resolves the plan from the subscription's price ID, then either:
   - **Existing account** (metadata has `account_id`): updates `billing_accounts` with the new Stripe customer id, subscription id, plan id, and period end; invalidates the account feature cache.
   - **New user** (metadata has `user_id`): creates an `accounts` row with the paid plan, seeds default roles, adds an owner membership, and stores the billing info.

   It then stores the withdrawal-waiver proof and sends the order confirmation.
8. Stripe redirects the user back to `/dashboard?billing=success`.

### Managing / Cancelling

1. User opens `/dashboard/settings/channel/billing` and clicks **Open customer portal**.
2. Frontend calls `POST /api/billing/portal` → GraphQL `createPortal` → Stripe Billing Portal Session.
3. The Stripe-hosted portal opens in a new tab. It offers invoices, payment methods, billing details and cancellation, but **no plan change**: every portal session uses Lumio's own portal configuration with `subscription_update` disabled, because a plan change is a new contract that needs the withdrawal-waiver declaration, which only the checkout collects. The configuration is found by its metadata tag `lumio_purpose = no_plan_change_v1` or created once per Stripe account. If Stripe cannot provide it, the portal does not open (`500 Billing portal is unavailable`). Changes made in the portal come back to Lumio via webhooks.
4. The **Verträge hier kündigen** button opens a dialog for an ordinary or extraordinary cancellation. The declaration and receipt are stored first. An ordinary request sets `cancel_at_period_end = true` when Stripe accepts it; an extraordinary request waits for an operator without an automatic Stripe change. See [Withdrawal & Cancellation](./contract-declarations.md).

### Billing cadence and cancellation state

`billingStatus` / `GET /v1/billing/status` report the subscription's cadence (`billingInterval` / `billing_interval`: `month`, `year`, or `null` without a subscription) and whether it is cancelled at period end (`cancelAtPeriodEnd` / `cancel_at_period_end`; the end date is `currentPeriodEnd`). Both are stored on the account (`accounts.billing_interval`, `accounts.subscription_cancel_at_period_end`):

- `checkout.session.completed` and `customer.subscription.updated` copy the cadence from the subscription's first price (`recurring.interval`; anything other than month/year is stored as `null`) and the flag from Stripe's `cancel_at_period_end` - so resuming a cancelled subscription in the Stripe portal clears the flag again.
- An ordinary `cancelSubscription` / `POST /v1/billing/cancel` sets the flag when Stripe accepts the cancellation. An extraordinary request leaves it unchanged pending operator review.
- `customer.subscription.deleted` clears the cadence, the flag and the period end.

### Withdrawal waiver and order confirmation

EU consumers have a 14-day right of withdrawal (§ 355 BGB). Lumio starts the service at once, so the buyer must expressly request that before paying and confirm what that means for the right of withdrawal (§ 356 Abs. 5 BGB for plans and extension subscriptions, Abs. 6 for one-time extension purchases). The same mechanism covers every paid Stripe checkout: plan checkout (`createCheckout` / `POST /v1/billing/checkout`) and extension purchase (`POST /v1/extension-purchases`).

- **Checkbox before the redirect.** The web app shows an unticked checkbox with the declaration text and a link to the withdrawal information in the terms (`/legal/terms#withdrawal-information`, de `#widerrufsbelehrung`) above the plan cards in **Settings → Channel → Subscription** (component `WithdrawalWaiver`, `apps/web/src/components/billing-hub/withdrawal-waiver.tsx`). Until it is ticked the buy buttons are `aria-disabled`; pressing one shows an error under the box. The proxy `POST /api/billing/checkout` forwards `accept_withdrawal_waiver` as `acceptWithdrawalWaiver` and sends `true` only for a literal `true` from the browser. The texts live in `apps/web/messages/{en,de}.json` under `withdrawalWaiver` (`plan`, `extensionPayment`, `extensionSubscription`); `apps/web/__tests__/billing/withdrawal-waiver-texts.test.ts` fails if they differ from the backend map. The store has no purchase dialog yet, so the web app does not call `POST /v1/extension-purchases` today. All three checkout entry points require `accept_withdrawal_waiver` / `acceptWithdrawalWaiver` to be `true`. A missing or `false` value creates no Stripe session and fails with `400 VALIDATION_ERROR` and the message `You must accept the withdrawal waiver (accept_withdrawal_waiver) before checkout`, identical on REST and GraphQL. On GraphQL the argument is a required `Boolean!`, so an omitted argument is a schema error.
- **Texts.** The wording is versioned in code (`lo_email::withdrawal`, map version → kind → language; current version `2026-10-22`). Plans use text A, one-time extension purchases text B, extension subscriptions text C. A wording change is a new version; old versions stay so the proof can always show the exact text a buyer agreed to.
- **Proof.** The checkout session carries the declaration in its metadata (`withdrawal_waiver_kind`, `withdrawal_waiver_version`, `withdrawal_waiver_accepted_at` = server time of the checkout request, `withdrawal_waiver_user_id`, `withdrawal_waiver_locale`). On `checkout.session.completed` the webhook stores one row per Stripe session in `withdrawal_waiver_consents` (kind, text version, time, buyer, account, plan or extension id and a snapshot of the order facts). A webhook redelivery changes nothing. The row is deleted with the account; if the buyer's profile is deleted, the row stays with the account without the buyer. A session without a declaration (created before this existed) stores nothing, and the buyer keeps the full right of withdrawal.
- **Audit.** Each stored proof emits `billing:withdrawal_waiver_accepted` (account scope, actor = buyer; metadata `kind`, `text_version`, `accepted_at`, `checkout_session_id`, `plan_id` or `extension_id`).
- **Order confirmation (§ 312f BGB).** Right after storing the proof, Lumio mails the buyer an order confirmation in their language: provider, product, term, price (with the § 19 UStG note), discount, time of contract, reference, next renewal and how to cancel (subscriptions), the declaration in its exact wording with time and version, the withdrawal information including the model withdrawal form, and the full terms of use. The withdrawal information and the terms are the texts of `/legal/terms` shipped with the same release. A failed send never fails the webhook; a sweeper retries unsent confirmations every 5 minutes, up to 10 attempts, and stores `confirmation_sent_at` once the mail went out. A buyer without an e-mail address (or a deleted buyer) is logged as an error and not retried.
- **Renewals** of the same subscription need no new declaration. A plan change goes through the checkout and needs a new one; the customer portal offers no plan change (see above).

### Coupon Redemption

1. User enters a code in the plan selector. Frontend calls `GET /api/billing/validate-coupon?code=...` → GraphQL `validateCoupon`.
2. Backend queries `Stripe::PromotionCode.list(code, active=true)`. Valid codes return the coupon id, percent/amount off, currency, and name.
3. If valid, the code is passed through to `createCheckout` as `couponCode`. It is applied as a Stripe `Discount` on the Checkout Session.
4. Admin-defined coupons (stored in the `coupons` table via `adminCreateCoupon`) are independent of Stripe Promotion Codes and are consumed by future server-side redemption flows.

## Webhook Event Handling

| Stripe event | Action |
|--------------|--------|
| `checkout.session.completed` | Link Stripe customer + subscription to account (or create the account); set plan; set period end; invalidate feature cache; store the withdrawal-waiver proof and send the order confirmation. If the proof of an existing account cannot be stored, the webhook answers `500` so Stripe redelivers |
| `customer.subscription.updated` | Re-resolve plan from subscription items' price IDs; update `plan_id` and `subscription_period_end`; invalidate feature cache |
| `customer.subscription.deleted` | Downgrade account to `free`; clear `stripe_subscription_id` and `subscription_period_end`; invalidate feature cache |
| `invoice.paid` | Send the channel owner a configurable invoice notice, in-app by default. |
| `invoice.payment_failed` | Notify the channel owner in-app and by email while Stripe handles retries; the notice is locked on. |
| anything else | Logged and ignored |

Signature verification: the handler parses `t=<timestamp>,v1=<signature>` from the `Stripe-Signature` header and recomputes HMAC-SHA256 over `{timestamp}.{body}` using `config.stripe.webhook_secret`. Invalid signatures return 401.

## Permissions

User-facing account-scope permissions that gate the billing routes (ZAF-735 #4). Reads (`GET /v1/billing/status`, `/invoices`, and the GraphQL `billingStatus` / `accountLimits` / `invoices`) require `plan:read`. Subscription-management mutations (`createPortal`, `cancelSubscription`) require `plan:edit` **and** an interactive sign-in session (ZAF-1750): neither a delegated popout token nor a user's own API key (`lm_usr_`, whatever its scopes) can open the Stripe portal or cancel the subscription. Checkout (`createCheckout`) requires an interactive sign-in session only (a brand-new account has no plan permission yet). The session check runs before the billing-enabled check on both protocols, so an API key always gets `403` / `FORBIDDEN` `This action requires an interactive sign-in session` and Stripe is never called - see [Authentication → Session-only Surfaces](../api-reference/authentication.md#session-only-surfaces). An active account is still required on the account-scoped routes; the Stripe webhook stays public (HMAC-verified):

| Permission | Purpose |
|------------|---------|
| `plan:read` | Read billing status, account limits, and invoices |
| `plan:edit` | Open the Stripe customer portal and cancel the subscription |

`billing:read` / `billing:edit` are **admin-global** permissions for the admin panel's billing surface (checked against `admin_permissions`), not these account routes.

Admin-global permissions:

| Permission | Purpose |
|------------|---------|
| `plans:read` / `plans:create` / `plans:edit` / `plans:delete` | Manage plan catalog and plan→feature mapping |
| `coupons:read` / `coupons:create` / `coupons:edit` / `coupons:delete` | Manage admin-issued coupon codes |
| `subscriptions:read` / `subscriptions:edit` | View and act on cross-account subscriptions |
| `accounts:edit` | Required for `adminUpdateAccountPlan` and `adminUpsertAccountLimits` |

Invoices and the customer portal are gated by the settings section's owner-only check before the loader runs, in addition to backend auth.

## API

### GraphQL Queries

| Query | Auth | Description |
|-------|------|-------------|
| `plans` | Public | List all plans with prices, limits, and feature flags |
| `publicFeatureEnabled(key: String!)` | Public | Check whether a global feature flag is on |
| `billingStatus` | Auth | Current plan, Stripe customer/subscription ids, active flag, period end, `billingInterval` (`month` \| `year` \| `null`), `cancelAtPeriodEnd` |
| `accountLimits` | Auth | Merged per-account limits (override > plan default) |
| `invoices(limit: Int)` | Auth | Recent Stripe invoices (1–100, default 12) |
| `validateCoupon(code: String!, planSlug: String)` | Auth | Validate a Stripe promotion code |
| `adminCoupons(active, limit, offset)` | `coupons:read` | List admin-issued coupons |
| `adminCoupon(id: UUID!)` | `coupons:read` | Get a single coupon |

### GraphQL Mutations

| Mutation | Auth | Description |
|----------|------|-------------|
| `createCheckout(planSlug: String!, interval, couponCode, acceptWithdrawalWaiver: Boolean!)` | Session | Create a Stripe Checkout Session; returns hosted URL. `acceptWithdrawalWaiver` must be `true` |
| `createPortal` | `plan:edit` + session | Create a Stripe Customer Portal Session (no plan change); returns hosted URL |
| `cancelSubscription(kind, reason, effective, effectiveDate, receiptEmail, name, clientRequestId)` | `plan:edit` + session | Record a plan cancellation declaration; an ordinary request sets `cancel_at_period_end` when Stripe accepts it, while an extraordinary request waits for review |
| `adminCreateCoupon(input: CreateCouponInput!)` | `coupons:create` | Create an admin coupon |
| `adminUpdateCoupon(id, input)` | `coupons:edit` | Update description, max redemptions, valid-until, active flag |
| `adminDeactivateCoupon(id: UUID!)` | `coupons:edit` | Soft-deactivate a coupon |
| `adminUpdateAccountPlan(accountId, planId)` | `accounts:edit` | Change an account's plan; invalidates feature cache |
| `adminUpsertAccountLimits(accountId, input)` | `accounts:edit` | Override any of the five per-account limits |
| `adminSetPlanFeature(planId, featureId, enabled)` | `plans:edit` | Toggle a feature flag for a plan; invalidates all accounts on that plan |

### REST Endpoints

All paths are under `/v1/`. All JSON bodies are snake_case.

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| `POST` | `/v1/billing/checkout` | Session | Create Stripe Checkout Session. Body: `{ plan, interval?, coupon_code?, accept_withdrawal_waiver }`; `accept_withdrawal_waiver` must be `true` |
| `POST` | `/v1/billing/portal` | `plan:edit` + session | Create Stripe Customer Portal Session (no plan change) |
| `GET` | `/v1/billing/status` | Auth | Current plan + subscription state, incl. `billing_interval` (`month` \| `year` \| `null`) and `cancel_at_period_end` |
| `POST` | `/v1/billing/cancel` | `plan:edit` + session | Record an ordinary or extraordinary cancellation and return its reference and status; only an ordinary request changes Stripe automatically |
| `GET` | `/v1/billing/invoices?limit=N` | Auth | Recent Stripe invoices (1–100, default 12) |
| `GET` | `/v1/billing/validate-coupon?code=X&plan=Y` | Auth | Validate a Stripe promotion code |
| `POST` | `/v1/webhooks/stripe` | Stripe-Signature | Stripe webhook receiver (not user-callable) |

### Proxy Endpoints (Browser)

The Next.js app exposes REST-shaped proxy endpoints for the browser. All live under `/api/billing/` and map 1:1 to the GraphQL operations above:

```
GET    /api/billing/status
GET    /api/billing/plans
GET    /api/billing/limits
GET    /api/billing/invoices?limit=N
GET    /api/billing/validate-coupon?code=X&plan=Y
POST   /api/billing/checkout      { plan_slug, interval?, coupon_code?, accept_withdrawal_waiver }
POST   /api/billing/portal
POST   /api/billing/cancel
```

The browser should never call `/v1/billing/*` directly - always go through `/api/billing/*` so the JWT is read from cookies and permission guards run.

## Configuration

Stripe configuration lives under `[stripe]` in the TOML config:

| Key | ENV var | Description |
|-----|---------|-------------|
| `stripe.enabled` | `LUMIO__STRIPE__ENABLED` | Master switch. When `false`, billing endpoints other than the status and plans fail with `BILLING_DISABLED`. |
| `stripe.secret_key` | `LUMIO__STRIPE__SECRET_KEY` | Stripe API secret key (`sk_live_...` or `sk_test_...`) |
| `stripe.webhook_secret` | `LUMIO__STRIPE__WEBHOOK_SECRET` | Webhook signing secret (`whsec_...`) |

Each plan's `stripe_monthly_price_id` and `stripe_yearly_price_id` are stored in the `plans` table and must match the price IDs in your Stripe dashboard. A plan with a missing price id for the chosen interval will fail checkout with "Stripe price ID not configured for this plan".

## Domains

Checkout + portal `success_url`, `cancel_url`, and `return_url` are all derived from `config.server.public_url`:

- **Production**: `https://lumio.vision`
- **Staging**: `https://lumio.web.staging.zaflun.dev`

The webhook is always posted to `{api_public_url}/v1/webhooks/stripe`:

- **Production**: `https://api.lumio.vision/v1/webhooks/stripe`
- **Staging**: `https://lumio.api.staging.zaflun.dev/v1/webhooks/stripe`

Register both URLs with the corresponding Stripe account (live vs test) and copy the generated `whsec_` secret into `stripe.webhook_secret` for each environment.

---

## Features / Withdrawal & Cancellation

Source: https://docs.lumio.vision/features/contract-declarations

# Withdrawal & Cancellation

## Overview

Lumio accepts withdrawal declarations for plans and paid extension purchases, and cancellation declarations for plan and paid extension subscriptions. The public [withdrawal and cancellation forms](/user-guide/withdrawal-and-cancellation) work without signing in. A signed-in member can select a contract from every channel they may manage. The options are grouped by channel, and the forms also offer **Other contract** for a free-text reference. The forms share the [legal layout](/user-guide/legal-pages).

Each submission is stored with its receipt time before any Stripe operation. The confirmation shows a short case reference and the Europe/Berlin receipt time; a receipt is sent to the address entered on the form. Repeating a submission with the same `client_request_id` returns the original declaration. The ID is bound to that declaration: reused for another channel, contract, kind or sender it is refused with `IDEMPOTENCY_KEY_REUSED` and returns no receipt. The entered receipt address is stored on the declaration, not on the user's profile.

## Withdrawal

`/withdraw` collects the declarant's name, email address and contract. A signed-in member may select an eligible plan or extension purchase from any manageable channel. The form has a review step that repeats the entries before submission. A signed-out declaration needs a contract description and Turnstile verification. Signed-in withdrawals, including **Other contract**, do not use Turnstile. Every withdrawal remains open for an operator to review. A refund, when due, is issued by hand in Stripe; submitting the form does not refund a payment automatically.

The signed-in contract list includes extension purchases within 14 days of the purchase, or up to 12 months and 14 days without a recorded waiver. The plan is listed within 14 days of its recorded waiver; without a recorded waiver it is always listed, because Lumio does not store the plan's start date. The operator checks the deadline when handling the declaration. **Other contract** remains available even when no listed contract qualifies.

## Cancellation

`/cancel` is the confirmation page: choose a plan or extension subscription from any manageable channel, or describe another contract, then choose ordinary or extraordinary cancellation, the requested effective time, and the receipt address. An extraordinary cancellation needs a reason. Signed-out and signed-in **Other contract** submissions use the public form and Turnstile. Already cancelled subscriptions cannot be selected again.

An ordinary signed-in subscription cancellation records the declaration and asks Stripe to cancel at period end. If Stripe is unavailable, the receipt still succeeds and a background worker retries for seven days; the declaration remains open for operator follow-up if retries do not succeed. An extraordinary request and every signed-out cancellation wait in the operator queue without an automatic Stripe change. The paid subscription remains active until Stripe applies the cancellation. The receipt of an ordinary signed-in cancellation is sent after the Stripe call and names the date the contract ends; only when that date is unknown (Stripe unavailable, or a signed-out declaration) does it say the contract ends at the end of the current paid period.

## Operator handling

The [admin declaration queue](/admin/contract-declarations) lists open cases first. Operators can match a public declaration to a plan or extension purchase, mark a case processed or rejected, record a manually issued refund reference, and extend its retention for a legal hold. The queue covers all accounts and requires admin-scoped permissions.

## API and audit

REST endpoints and GraphQL twins are listed in the [REST API](/api-reference/rest-api#contract-declarations) and [GraphQL API](/api-reference/graphql#contract-declarations). Withdrawal and cancellation declarations, operator decisions, matching and retention extensions write [audit events](/features/audit-log#event-catalog). A public declaration has system scope because there is no authenticated user or account; an authenticated declaration uses its account or user scope.

---

## Features / Developer Credit Notes

Source: https://docs.lumio.vision/features/developer-credit-notes

# Developer Credit Notes

## Overview

Lumio pays extension developers their revenue share. Every payout is documented by a **self-billed credit note** (*Gutschrift*, § 14 Abs. 2 S. 2 UStG): Lumio, the recipient of the developer's service, issues the invoice on the developer's behalf. The note is issued in the same database transaction as the payout, so no payout exists without its note, and a note that cannot be issued books no payout.

The developer finds every note and cancellation under **Extensions → Payouts** (`/dashboard/extensions/payouts`, see [Developer Payouts](../user-guide/developer-payouts.md)), gets each one by e-mail with the PDF attached, and can download the PDF at any time. Operators see all notes on the admin page `/credit-notes`, including those of deleted developer profiles, and cancel them there (see [Credit Notes](../admin/credit-notes.md)).

## What a note contains

| Part | Content |
|------|---------|
| Number | `GS-<year>-<6 digits>`, e.g. `GS-2026-000001`. One gap-free range per calendar year (Europe/Berlin), shared by notes and cancellations. The prefix comes from `[billing.credit_notes] number_prefix`. |
| Issuer | Lumio's name, address and VAT ID from `[billing.issuer]`, copied onto the note at issue. |
| Supplier | The developer's verified verification: name, company, address, country, Steuernummer and/or USt-IdNr., copied at issue. A later change of the verification never changes an issued note. |
| Service | One line per service, each with its own net amount (see [Lines](#lines)). The developer's own revenue share is "Revenue share for the sale of extensions via the Lumio Marketplace" with the service period. The period starts where the developer's last effective note ended (or when the profile was created) and ends on the issue date. |
| Amounts | Net, VAT and gross in cents, EUR only. The payout amount is the gross amount. |
| VAT | Derived from the tax details of the verification (below), printed as an amount or as the matching legal sentence. |

## Lines

A note has one line for the profile's own revenue share. When an operator has [settled a released balance](../admin/users.md#settling-a-released-balance) onto the profile, the settled amount was earned through an earlier, deleted developer profile, so it gets its own line with its own service date (Legal decision ZAF-2843):

| Order | Line | Net amount |
|-------|------|------------|
| 1 | "Umsatzbeteiligung aus dem Verkauf von Erweiterungen über den Lumio Marketplace, erzielt über ein früheres Entwicklerprofil (Guthaben freigegeben am D) / Revenue share for the sale of extensions via the Lumio Marketplace, earned through an earlier developer profile (balance released on D)", then "Leistungszeitraum bis / Service period until D". `D` is the release date (Europe/Berlin). | The part of the settled amount paid out with this payout |
| 2 | The own revenue share with its service period, as above | The rest of the payout's net amount; the line is left out when that is 0 |

- **Split.** A payout first uses the settled amounts that are not yet on a note, oldest settlement first, up to the payout's net amount. A rest moves to the next note as a line 1 again, with the same `D`. Several settled balances give one line 1 each.
- **Period.** Line 1 does not move the service period. A note with only line 1 has the issue date as its period, and the next note's period starts there.
- **Failed payout.** The cancellation negates both lines, and the settled amount is on the next note again. An objection without a re-issue does not give it back, because the money stays paid out. A corrected re-issue copies line 1 unchanged.
- The note names nothing of the earlier profile: no developer ID, name, claim code or support reference. VAT is one rate over the whole note.

How much of each settled balance a payout took is stored in `developer_released_balance_allocations` (one row per settled balance and payout, two IDs and an amount). The row is deleted with the payout or the settled balance, and a failed payout deletes it. A settled balance is kept past its 8 years while part of it is not paid out yet.

The PDF is printed in German and English and is the document of record: it is rendered once, stored write-once under `billing/credit-notes/<year>/<id>.pdf` with its SHA-256, and checked against that hash every time it is served.

## VAT treatment

The developer enters the tax details in the verification form and later in the **Tax details** card on the verification page (also after the verification was approved; the change does not reset the review):

| Developer | Needs | Treatment on the note |
|-----------|-------|-----------------------|
| Germany, small business (§ 19 UStG) | Steuernummer or USt-IdNr., "small business: yes" | No VAT; "Steuerfreie Leistung als Kleinunternehmer nach § 19 Abs. 1 UStG." |
| Germany, charges VAT | Steuernummer or USt-IdNr., "small business: no" | 19 % VAT **on top of** the revenue share: the balance is debited by the net amount, the payout is net + VAT |
| Other EU country | USt-IdNr. | No VAT; "Steuerschuldnerschaft des Leistungsempfängers" (§ 13b UStG) |
| Outside the EU | — | No VAT; same reverse-charge sentence |

While the details are incomplete, a payout request answers `TAX_DETAILS_REQUIRED` and the monthly cycle skips the developer (counted as `refused`); nothing is booked and no number is used. Without a complete `[billing.issuer]` config no note and so no payout can be issued at all (`CREDIT_NOTE_ISSUER_NOT_CONFIGURED`).

> The VAT treatment of foreign developers (individuals without business status, EU developers without a VAT ID, a VIES check) is reviewed by a tax adviser before real payouts start. The wording of the printed sentences is a draft by Legal.

## Cancellation and objection

| Event | What happens |
|-------|--------------|
| A payout fails (Stripe or PayPal error, PayPal "item failed" webhook) | In one transaction: the payout becomes `failed`, the net amount goes back to the balance, and a **cancellation note** with its own number and the negated amounts cancels the payout's note. A replayed webhook changes nothing. The next payout's note covers the period again. |
| The developer objects to a note (§ 14 Abs. 2 S. 3 UStG) | An operator records it with the date it arrived (`cancelCreditNote` / `POST /v1/admin/credit-notes/{id}/cancel`, reason `developer_objection`); optionally a corrected note is re-issued for the same payout and period. |
| A note has wrong data | An operator cancels it with reason `correction` and re-issues it from the corrected verification. A re-issue whose total would differ from the paid amount is refused (`CREDIT_NOTE_AMOUNT_MISMATCH`). |

Every operator cancellation emits the audit event `system:developer_credit_note_cancelled`. An issued note is never edited: a database trigger rejects every change except recording the cancellation, storing the PDF once and recording the delivery.

## Delivery

After the payout transaction commits, the credit note worker renders and stores the PDF (every minute) and mails it to the developer's e-mail address in their e-mail language, German or English, with the PDF attached. A successful mail sets `delivered_at`. A failed mail is retried hourly for 14 days; notes whose PDF is pending for more than an hour or that are undelivered after a day are logged as an operator warning. The worker needs file storage (`[storage]`) and an enabled `[email]` provider.

## Retention

Notes are kept **8 full calendar years after the year of issue** (§ 14b Abs. 1 UStG, § 147 AO): a note from 2026 is deleted from 1 January 2035, 00:00 Europe/Berlin. A note and its cancellation are deleted together, once both are past that date. The PDF is queued for deletion in the same step. Deleting a developer profile or a payout keeps the notes (they are detached), and a GDPR erasure does not shorten the period. The daily step of the account security worker runs the purge.

## Configuration

| Key | ENV | Default | Meaning |
|-----|-----|---------|---------|
| `billing.issuer.name` | `LUMIO__BILLING__ISSUER__NAME` | _(empty)_ | Lumio's legal name on the note |
| `billing.issuer.address` | `LUMIO__BILLING__ISSUER__ADDRESS` | _(empty)_ | Postal address, one line per address line |
| `billing.issuer.vat_id` | `LUMIO__BILLING__ISSUER__VAT_ID` | _(empty)_ | USt-IdNr. (or Steuernummer) on the note |
| `billing.credit_notes.number_prefix` | `LUMIO__BILLING__CREDIT_NOTES__NUMBER_PREFIX` | `GS` | Number prefix; must not collide with Stripe's invoice numbers |
| `billing.credit_notes.domestic_vat_rate_bp` | `LUMIO__BILLING__CREDIT_NOTES__DOMESTIC_VAT_RATE_BP` | `1900` | VAT for German standard-rated developers, in basis points |

With an empty issuer field the API logs a warning at start-up and refuses every payout.

## API

- Developer: `developerCreditNotes`, `developerCreditNote` (GraphQL) / `GET /v1/developer/credit-notes[/{id}[/pdf]]` (REST); `updateDeveloperTaxDetails` / `PUT /v1/developer/verification/tax-details`.
- Operators: `adminCreditNotes`, `adminCreditNote`, `cancelCreditNote` / `GET /v1/admin/credit-notes[/{id}[/pdf]]`, `POST /v1/admin/credit-notes/{id}/cancel` (`billing:read` / `billing:edit`).

Details: [REST API](../api-reference/rest-api.md#developer-credit-notes), [GraphQL](../api-reference/graphql.md#developer-credit-notes).

---

## Features / Developer Payouts

Source: https://docs.lumio.vision/features/developer-payouts

# Developer Payouts

## Overview

Extension developers earn a revenue share that is credited to their **balance**. A **payout** moves the whole balance to the developer, with a self-billed credit note in the same transaction (see [Developer Credit Notes](./developer-credit-notes.md)). Only developers with a verified identity are paid.

A payout is created in one of three ways, always as `pending`, with the balance debited:

| Source | When |
|--------|------|
| **Request** | The developer clicks **Request payout** (`requestPayout` / `POST /v1/developer/payouts/request`). The balance must reach the minimum of the payout method. |
| **Closing payout** | The developer schedules a profile deletion with a grace period; the remaining balance is paid out even below the minimum. |
| **Payout cycle** | Once per calendar month (Europe/Berlin) Lumio pays out every balance that reaches the method's minimum. |

A developer has at most one `pending` or `processing` payout at a time. While one is open, a profile deletion waits for it (`409 DEVELOPER_FUNDS_OUTSTANDING`).

## Payout cycle

The API runs the payout cycle every 15 minutes on every replica; running it on several replicas at once is safe. Each run has two steps.

1. **Monthly scheduling.** Every verified developer whose balance reaches the minimum of their method (`min_payout_stripe`, `min_payout_paypal`, `min_payout_bank`) gets a payout, unless they already had a payout this calendar month (requested, closing, failed or scheduled). Stripe and PayPal developers are only scheduled while that provider's credentials are configured, so no balance is booked that Lumio cannot send. SEPA payouts are always scheduled; an operator transfers them.
2. **Sending.** Every `pending` Stripe or PayPal payout that was never sent, whether scheduled, requested or a closing payout, is sent:

   | Method | Call | Result |
   |--------|------|--------|
   | Stripe | Transfer to the developer's Connect account | `completed`; a transfer is final when it is created |
   | PayPal | Batch payout to the developer's PayPal e-mail | `processing`, then `completed` or `failed` from the PayPal payouts webhook |
   | SEPA (`bank`) | none | stays `pending` until an operator records the transfer |

A payout is sent **at most once**. Before calling the provider the cycle marks it (`execution_started_at`) and saves the mark. Then:

| Provider answer | What happens |
|-----------------|--------------|
| Accepted | `completed` (Stripe) or `processing` (PayPal) |
| Refused (for example an invalid destination, or insufficient platform funds) | `failed`: the balance is credited back and the credit note cancelled. The developer can request again |
| Not reached (connection refused, rate limited, no PayPal token) | The mark is removed; the next run sends it |
| Unknown (timeout, provider error 5xx, duplicate request) | Stays `pending` with the mark and is **never sent again**. An operator checks with the provider and settles it |

## Operator settlement

Operators settle what the cycle cannot: SEPA transfers and payouts whose answer is unknown. Such a payout is listed with `needs_operator: true`. In the admin app they are settled on the [Developer Payouts](../admin/developer-payouts.md) page; the API:

| Action | GraphQL | REST | Permission |
|--------|---------|------|-----------|
| List payouts (newest first, optional `status` filter) | `adminDeveloperPayouts` | `GET /v1/admin/developer-payouts` | `billing:read` |
| Mark paid | `completeDeveloperPayout` | `POST /v1/admin/developer-payouts/{id}/complete` | `billing:edit` |
| Mark failed (balance credited back, credit note cancelled) | `failDeveloperPayout` | `POST /v1/admin/developer-payouts/{id}/fail` | `billing:edit` |

Only a `pending` or `processing` payout can be settled (`409 PAYOUT_NOT_IN_FLIGHT` otherwise). A payout the cycle marked less than 15 minutes ago cannot be marked failed (`409 PAYOUT_BEING_SENT`): the provider call may still be running, and marking it failed could pay it twice. Mark it failed only after you confirmed with Stripe or PayPal that nothing arrived.

## Configuration

`[payments]` in the API config:

| Key | ENV | Default | Meaning |
|-----|-----|---------|---------|
| `payout_cycle_enabled` | `LUMIO__PAYMENTS__PAYOUT_CYCLE_ENABLED` | `true` | Run the cycle. With `false` nothing is scheduled or sent; requested payouts wait for an operator |
| `stripe_secret_key` | `LUMIO__PAYMENTS__STRIPE_SECRET_KEY` | empty | Without it Stripe payouts are neither scheduled nor sent |
| `paypal_client_id`, `paypal_client_secret` | `LUMIO__PAYMENTS__PAYPAL_CLIENT_ID`, `…_SECRET` | empty | Without both, PayPal payouts are neither scheduled nor sent |
| `paypal_environment` | `LUMIO__PAYMENTS__PAYPAL_ENVIRONMENT` | `sandbox` | `live` for real payouts |
| `min_payout_stripe`, `min_payout_paypal`, `min_payout_bank` | `LUMIO__PAYMENTS__MIN_PAYOUT_*` | `100`, `2500`, `5000` | Minimum balance in cents |

Without a complete `[billing.issuer]` no credit note and so no payout can be issued; the cycle then schedules nothing.

## Audit events

| Event | Scope | When |
|-------|-------|------|
| `developer:payout_requested` | `user` | The developer requested a payout, or the closing payout of a profile deletion was created (`source`: `request`, `closing`) |
| `system:developer_payout_scheduled` | `system` | The monthly cycle created a payout |
| `system:developer_payout_sent` | `system` | The cycle handed a payout to Stripe or PayPal |
| `system:developer_payout_completed` | `system` | An operator marked a payout paid, or the PayPal webhook confirmed it (`source`: `operator`, `webhook`) |
| `system:developer_payout_failed` | `system` | The provider refused it, an operator marked it failed, or the PayPal webhook reported it (`source`: `cycle`, `operator`, `webhook`) |

Metadata: `payout_id`, `developer_id`, `method`, `amount`, `currency`, `status`, the masked destination `payout_reference`, the provider ids, and for a failure the refunded amount and the cancellation note's number. It never contains the full PayPal e-mail, IBAN, or the payee's name and address.

---

## Features / ProfileService

Source: https://docs.lumio.vision/features/profile-service

# ProfileService

## Overview

The `ProfileService` is a unified platform user enrichment system that combines database records with real-time platform API data. It provides a single `get_profile()` method that returns a `UnifiedProfile` for any platform user, transparently handling caching, enrichment staleness, and API failure protection via a per-account+platform circuit breaker.

## Architecture

```
API / Chat Worker
    |
    v
ProfileService.get_profile(account_id, platform, platform_user_id, credentials?)
    |
    +-- 1. Redis cache check (lumio:user_profile:{account}:{platform}:{user})
    |       Hit? --> Return cached UnifiedProfile
    |
    +-- 2. Database lookup (platform_users table)
    |       Found? --> UnifiedProfile::from_db(row)
    |       Not found? --> UnifiedProfile::empty(platform, user_id)
    |
    +-- 3. Enrichment check (enriched_at older than the platform's interval, or never?)
    |       |
    |       +-- Circuit breaker open? --> Cache with 15min TTL, return DB data
    |       |
    |       +-- No credentials? --> Cache with 30min TTL, return DB data
    |       |
    |       +-- Cold-start lock (SETNX) --> loser waits 250ms and re-reads the cache
    |       |
    |       +-- Enrich via platform API
    |           |
    |           +-- Success --> Apply enrichment, persist to DB, reset failure counter, cache with 4h TTL
    |           |
    |           +-- Failure --> Record failure (circuit breaker), cache with 30min TTL
    |
    v
UnifiedProfile
```

### Cold-Start Lock

Before enriching, the service takes a Redis `SETNX` lock on
`{cache_key}:lock` with a 5-second TTL. On a hot stream many concurrent lookups
of the same chatter would otherwise all miss the cache and stampede the platform
API. The loser of the race sleeps 250 ms and re-reads the cache; if the cache is
still empty it proceeds with its own enrichment rather than returning an empty
profile. The lock is deleted as soon as the enrichment attempt returns, whether
it succeeded or failed.

### Multi-Platform Enrichment

Each platform has a dedicated enrichment method with different data coverage:

| Platform | Avatar | Bio/Description | Account Age | Broadcaster Type | Follower Status | Follower Count |
|----------|--------|-----------------|-------------|------------------|-----------------|----------------|
| **Twitch** | Yes | Yes | Yes | Yes | Yes (requires scope) | Yes |
| **YouTube** | Yes | Yes | Yes | -- | -- | -- |
| **Kick** | Yes | Yes | -- | -- | -- | Best-effort |

*Follower Status* is whether the user follows **your** channel; *Follower Count* is how many users follow **them**.

**Twitch** provides the richest enrichment through the Helix API:
- User info (`GET /users`): avatar, description, broadcaster type, account creation date. A failure here fails the enrichment.
- Follower check (`GET /channels/followers?broadcaster_id=<your channel>&user_id=<user>`): requires `platform_channel_id` in credentials; non-fatal if the scope is missing.
- Follower count (`GET /channels/followers?broadcaster_id=<user>&first=1` → `total`): the user's own follower count, stored as `follower_count`. Needs no extra scope - without moderator rights on the user's channel Helix still returns `total`. Non-fatal: a failure leaves the stored value untouched.

**YouTube** uses the YouTube Data API to fetch channel snippet data (thumbnails, description, published date). The channels call requests only `snippet`, so no subscriber count is stored.

**Kick** makes two **independent** calls to its public API, concurrently: `GET /public/v1/users?id=<user>` (avatar) and `GET /public/v1/channels?broadcaster_user_id=<user>` (`channel_description` → bio; blank counts as no bio). Each failure is logged at `warn` with its HTTP status and ignored, so a failing user lookup no longer discards the bio. The enrichment only fails - and counts toward the circuit breaker - when **both** calls fail (e.g. a revoked token).

The official Kick API exposes **no** follower count, and its `channel_description` is often empty even when the channel's "About" panel on kick.com shows a bio - that text is the user's `bio`. When the channel call returned the channel's `slug`, the enricher makes a third, **best-effort** call to Kick's **undocumented** website API, `GET https://kick.com/api/v2/channels/<slug>`, and reads `followers_count` and `user.bio`. The bio is used only when the official `channel_description` is empty; a non-empty official description always wins. That endpoint has no contract and sits behind Cloudflare bot protection, so the Kick follower count - and the bio fallback - **may be absent**:

- No OAuth token is sent (it is a public website endpoint), and the call has a 5 s timeout.
- `followers_count` or `followersCount` is accepted, as a number or a numeric string (Kick currently serves a string). Any other shape counts as "no count".
- A blank `user.bio` counts as no bio.
- Any failure - a `403` challenge, a timeout, a changed response - is logged and leaves `follower_count` and the bio fallback empty (previously stored values are kept). It never fails the enrichment and never counts toward the circuit breaker, which only guards the official API.

## Caching Strategy

All profiles are cached in Redis under the key `lumio:user_profile:{account_id}:{platform}:{platform_user_id}`.

| Scenario | TTL | Description |
|----------|-----|-------------|
| Enrichment succeeded | 4 hours (`CACHE_TTL_SUCCESS` = 14400s) | Full profile with fresh API data |
| Enrichment failed, or no credentials supplied | 30 minutes (`CACHE_TTL_DB_FALLBACK` = 1800s) | Shorter TTL to re-check sooner |
| Circuit breaker open | 15 minutes (`CACHE_TTL_CIRCUIT_OPEN` = 900s) | Minimal TTL during API outage |
| Enrichment still fresh | 4 hours | No re-enrichment needed |

### Enrichment Staleness

Enrichment is triggered when `enriched_at` is `None` (never enriched) or older than the platform's configured interval - 1 day for Twitch and Kick, 14 days for YouTube by default (see *Enrichment Intervals*). With the interval set to `0` the staleness check reduces to "has this profile ever been enriched?", so only first-time enrichment runs automatically.

## Circuit Breaker

The circuit breaker protects against cascading failures when a platform API is down or rate-limited. It operates per account+platform combination.

### Configuration

| Parameter | Value | Description |
|-----------|-------|-------------|
| Failure threshold | 5 | Failures within the window to trip the breaker |
| Failure window | 60 seconds | Rolling window for counting failures |
| Cooldown | 300 seconds (5 min) | How long the circuit stays open |

### Mechanism

1. Each enrichment failure increments a Redis counter (`lumio:circuit_count:{account}:{platform}`).
2. The counter expires after the failure window (60s) if no further failures occur.
3. When the counter reaches 5, a cooldown key (`lumio:circuit:{account}:{platform}`) is set with a 5-minute TTL.
4. While the cooldown key exists, `is_circuit_open` returns `true` and enrichment is skipped.
5. A successful enrichment calls `record_success`, which clears the failure counter so a near-trip state does not carry forward.
6. After the cooldown expires, enrichment attempts resume.

## UnifiedProfile

The `UnifiedProfile` struct combines database fields with enrichment data:

### Database Fields
- `platform`, `platform_user_id`, `username`, `display_name`
- `avatar_url`, `color` (chat color)
- `is_mod`, `is_sub`, `is_vip`, `badges`
- `message_count`, `first_seen_at`, `last_seen_at`
- `is_banned`, `banned_at`, `banned_by`, `ban_reason`, `ban_type`, `timeout_expires_at`
- `user_treatment`, `treatment_updated_at`, `treatment_updated_by`

### Enrichment Fields
- `description` -- User bio from platform API
- `broadcaster_type` -- Twitch-specific (partner, affiliate, etc.)
- `is_follower`, `followed_at` -- Follower relationship to the channel
- `account_created_at` -- When the platform account was created
- `follower_count` -- The user's own follower count (Twitch; Kick best-effort via an undocumented endpoint; `NULL` on YouTube). Stored in `platform_users.follower_count`; the enrichment upsert uses `COALESCE`, so a failed lookup never erases a known count
- `enriched_at` -- Timestamp of last successful enrichment

### Enrichment Merge

`apply_enrichment()` only overwrites fields that have `Some` values in the enrichment data, preserving existing database values for fields the platform does not provide.

## Credentials

The `ChannelCredentials` struct is provided by the caller and contains decrypted OAuth tokens:

```rust
struct ChannelCredentials {
    client_id: String,           // Platform app client ID
    client_secret: String,       // Platform app client secret
    access_token: String,        // Channel's OAuth access token
    refresh_token: Option<String>, // Channel's OAuth refresh token
    platform_channel_id: Option<String>, // Broadcaster ID (for follower checks)
}
```

Credentials are loaded and decrypted by the API layer (`apps/api`) from the `app_credentials` and `channel_connections` tables, keeping the crypto module decoupled from `lo-chat`.

## Manual Refresh

Users with the `chat:refresh_user` permission can manually trigger a profile re-enrichment from the refresh control in the user info card's header (`apps/web/src/components/user-card/user-card-header.tsx`, gated in `apps/web/src/components/info-user-modal.tsx`), which is rendered only when the viewer holds that permission. This evicts the Redis cache entry, resets the row's `enriched_at` via `reset_enriched_at`, and forces an immediate enrichment call against the platform API.

### API

| Protocol | Operation | Feature | Permission |
|----------|-----------|---------|------------|
| GraphQL | `refreshPlatformUserProfile(platform: String!, platformUserId: String!): GqlUnifiedProfile!` | `feature:multichat` | `chat:refresh_user` |
| REST | `POST /v1/chat/users/{platform}/{platform_user_id}/refresh` | `feature:multichat` | `chat:refresh_user` |

### Rate Limiting

Manual refresh is rate-limited to once every 10 minutes per (account, platform, user) triple. The limit is enforced via a Redis SETNX cooldown key - `lumio:user_profile:{account_id}:{platform}:{platform_user_id}:refresh_cooldown` - with a 600-second TTL.

Both protocols return the same code with the remaining seconds, in their own envelope:

- **REST:** HTTP `429` with `{ "error": "REFRESH_COOLDOWN", "retry_after_seconds": <n> }`
- **GraphQL:** an error with message `Refresh cooldown active` and extensions `code: "REFRESH_COOLDOWN"`, `retryAfterSeconds: <n>`

### Platform Support

Manual refresh is available for the supported chat platforms:

| Platform | Enrichment triggered |
|----------|---------------------|
| Twitch | Full enrichment (avatar, bio, account age, broadcaster type, follower status, follower count) |
| YouTube | Avatar, bio, account creation date |
| Kick | Avatar, bio, follower count (best-effort, undocumented endpoint) |

### Enrichment Intervals

Auto-enrichment intervals are configurable via the `[profile]` TOML section:

```toml
[profile]
# YouTube (days). 0 = disabled (manual refresh only). Default: 14.
youtube_enrichment_interval_days = 14
# Twitch, Kick (days). 0 = disabled (manual refresh only). Default: 1.
enrichment_interval_days = 1
```

ENV overrides: `LUMIO__PROFILE__YOUTUBE_ENRICHMENT_INTERVAL_DAYS`, `LUMIO__PROFILE__ENRICHMENT_INTERVAL_DAYS`.

| Platform | Default interval | Config key |
|----------|-----------------|------------|
| Twitch | 1 day | `enrichment_interval_days` |
| Kick | 1 day | `enrichment_interval_days` |
| YouTube | 14 days | `youtube_enrichment_interval_days` |

Setting an interval to `0` disables automatic re-enrichment for that platform - profiles are only enriched on first view and via the manual refresh button. First-time enrichment (user never enriched before) always runs regardless of the interval setting.

YouTube's longer default interval reflects the YouTube Data API quota cost per enrichment call. Manual refresh still resets the `enriched_at` timestamp regardless of platform.

## Key Files

| File | Purpose |
|------|---------|
| `crates/lo-chat/src/profile_service.rs` | ProfileService implementation, enrichment, cold-start lock, circuit breaker |
| `crates/lo-chat/src/platform_users.rs` | Database operations for `platform_users` table, including `reset_enriched_at` |
| `apps/api/src/graphql/chat.rs` | `refreshPlatformUserProfile` mutation |
| `apps/api/src/routes/chat.rs` | `POST /v1/chat/users/{platform}/{platform_user_id}/refresh` |
| `apps/web/src/components/info-user-modal.tsx` | User info card; renders the manual refresh control only with `chat:refresh_user` |
| `crates/lo-twitch-api/` | Twitch Helix API client (used for Twitch enrichment) |
| `crates/lo-youtube-api/` | YouTube Data API client (used for YouTube enrichment) |
| `crates/lo-kick-api/` | Kick API client (used for Kick enrichment) |

---

## Features / Channel Status

Source: https://docs.lumio.vision/features/channel-status

# Channel Status

## Overview

The channel status module tracks live stream status per platform for each account. It stores whether a channel is online, along with metadata such as stream title, category, viewer count, and stream start time. Status is updated by platform workers (Twitch, YouTube, Kick) and includes a manual Spotify connect feature for controlling the Spotify polling worker independently of stream status.

## Architecture

```
Platform Workers (Twitch/YouTube/Kick)
    |
    +--> db::channel_status::set_online / set_offline / update_stream_data
    |
    v
channel_status table (PostgreSQL)
    ^
    |
Dashboard UI
    |
    v
Next.js API Proxy
    |
    v
GraphQL (ChannelStatusQuery / ChannelStatusMutation)
    |
    +--> db::channel_status::get_status
    +--> services::channel_status (manual connect via Redis)
```

### Status Updates

Platform workers poll for stream status changes and update the database:

- **Going online** -- `set_online()` upserts a row with `is_online = TRUE` and metadata (title, category, viewer count, start time).
- **Going offline** -- `set_offline()` sets `is_online = FALSE` and clears `started_at`.
- **Data updates** -- `update_stream_data()` updates viewer count, title, and category for channels that are already online.

### Spotify Manual Connect

The Spotify worker normally polls only when a channel is online. The manual connect feature allows users to start Spotify polling independently, using a Redis key with a 30-minute TTL. This is useful for pre-stream setup or listening sessions without going live.

- **Start** -- Sets a Redis key and publishes a synthetic status change event via Redis pub/sub.
- **Stop** -- Deletes the Redis key and publishes a status change event.
- **Query** -- Returns whether manual connect is active and the remaining seconds.

### Spotify Worker Lifecycle (relay)

The **channel-status relay** (`apps/api/src/workers/channel_status_relay.rs`) owns the [Spotify worker](./spotify.md)'s start/stop lifecycle. It subscribes to `lumio:channel_status:*` and, on every status change, evaluates whether the worker should run for that account:

- **Should run** when any channel is online **or** a manual connect is active. On a `should-run` transition the relay **resolves the worker config from the live `channel_connections` row on demand** (`resolve_spotify_config`) and starts the worker with the connection's **current** `connection_id`. There is no boot-time config snapshot, so a Spotify connection linked, re-authorized, or disconnected-and-reconnected *after* the API booted starts polling on the next stream-start or manual connect -- **without an API restart**. An account with no Spotify connection resolves nothing and is simply not started.
- **Should not run** (no channel online, no manual connect) tears the worker down. A separate 60-second poll also stops any worker whose manual connect has expired.

This is why stopping the worker at stream end / manual-connect expiry is safe: it always restarts from the DB on the next trigger. Note the [emission asymmetry](./spotify.md#event-emission-worker-vs-control-path): only the worker produces `spotify:track`; `spotify:skip`/`play`/`pause`/… come from the playback-control path and do **not** depend on the worker running.

## API

### GraphQL Queries

| Query | Args | Returns | Permission |
|-------|------|---------|------------|
| `channelStatus` | -- | `[ChannelStatus]` | `connections:read` |
| `channelSchedule` | `from: DateTime`, `to: DateTime` | `[ScheduledStream!]!` | `connections:read` |
| `spotifyManualStatus` | -- | `SpotifyManualStatus` | `spotify:read` |

- `channelStatus` returns all platform statuses for the active account.
- `channelSchedule` returns the stream plan of the account's connected channels — see [Stream plan](#stream-plan).
- `spotifyManualStatus` checks the Redis TTL key and returns active status with remaining seconds.

### GraphQL Mutations

| Mutation | Args | Returns | Permission |
|----------|------|---------|------------|
| `startSpotifyManual` | -- | `SpotifyManualStatus` | `spotify:worker` |
| `stopSpotifyManual` | -- | `Boolean` | `spotify:worker` |

### REST Endpoints

All paths live under `/v1`.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/channel-status` | `connections:read` | All platform statuses for the active account |
| `GET` | `/v1/channels/schedule?from=&to=` | `connections:read` | Stream plan of the connected channels (twin of `channelSchedule`, body `{ "data": [ScheduledStream] }` in snake_case) |
| `GET` | `/v1/spotify/manual-connect` | `spotify:read` | Manual-connect status + remaining seconds |
| `POST` | `/v1/spotify/manual-connect` | `spotify:worker` | Start manual Spotify polling (30 min TTL) |
| `DELETE` | `/v1/spotify/manual-connect` | `spotify:worker` | Stop manual Spotify polling |

### GraphQL Types

```graphql
type ChannelStatus {
  platform: String!
  broadcastId: String!
  isOnline: Boolean!
  broadcastStatus: String
  streamTitle: String
  category: String
  viewerCount: Int
  likeCount: Int
  totalViews: Int
  startedAt: DateTime
  scheduledStart: DateTime
  liveChatId: String
  updatedAt: DateTime!
}

type ScheduledStream {
  platform: String!      # youtube | twitch | kick
  title: String!         # "" when the platform has none
  category: String
  startsAt: DateTime!
  endsAt: DateTime       # null when the platform has no end (YouTube always)
  isRecurring: Boolean!
  url: String!           # YouTube watch page, Twitch/Kick channel page
  source: String!        # youtube_broadcast | twitch_schedule | kick_schedule
}

type SpotifyManualStatus {
  active: Boolean!
  remainingSeconds: Int
}
```

### Stream plan

`channelSchedule(from, to)` / `GET /v1/channels/schedule?from=&to=` lists the planned broadcasts of the account's **connected** channels, starting inside `from..to` and sorted by `startsAt`. Both protocols share the guard (`connections:read`), the validation and the messages:

- `from` defaults to now, `to` to `from` + 30 days (RFC 3339).
- ``Bad request: `to` must be after `from` `` when `to <= from`; ``Bad request: The window from `from` to `to` must not exceed 60 days`` when the window is longer. Code `BAD_REQUEST` on both protocols; REST answers `400`.

| Platform | Source | `source` | Notes |
|----------|--------|----------|-------|
| YouTube | `channel_status` rows the YouTube worker writes for discovered public scheduled broadcasts (`broadcast_status = "upcoming"`, `scheduled_start`) | `youtube_broadcast` | One entry per scheduled broadcast with a known start time; a chat ID is not required. `url` is the watch page; no end time; never recurring. A broadcast that went live becomes a `live` row and drops out. |
| Twitch | Helix `GET /schedule` (official, no scope) with the channel connection's token | `twitch_schedule` | Recurring segments arrive expanded. Cancelled occurrences (`canceled_until`) and segments inside the `vacation` window are dropped. No schedule (`404`) is an empty plan. |
| Kick | `web.kick.com/api/v1/channels/{channel_id}/calendar/events?from_utc=&to_utc=` — **undocumented**, the data behind the "Schedule" tab on kick.com; no token | `kick_schedule` | The official Kick API has no schedule endpoint. Recurring events arrive expanded (`event_type = RECURRING`). The kick.com channel id is looked up from the slug (`channel_login`). A format change or an unknown channel is an empty plan. |

Twitch and Kick are fetched for the next 61 days and cached per channel in Redis (`lumio:channel_schedule:{platform}:{channel_id}`) for 10 minutes; a failed fetch is cached as an empty plan for 2 minutes. Entries later than 61 days from the fetch are not returned. Every failure (platform down, no usable token, reconnect required, Redis unavailable) only empties that channel — it never fails the list. Tokens refresh only through `get_fresh_connection_token`.

While a platform is live, the plan entry covering the current time on that platform is left out (`startsAt <= now < endsAt`; without an end, any past start). There is no WebSocket channel for the plan: clients reload it on page load and on the platform online/offline events. Reading the plan emits no audit event. The counter `channel_schedule_fetches_total{platform, outcome}` (`cache_hit`, `ok`, `no_token`, `no_slug`, `error`) is exposed on the internal `/metrics`.

## Permissions

| Permission | Description |
|------------|-------------|
| `connections:read` | View channel status and the stream plan |
| `spotify:read` | View the Spotify manual connect status |
| `spotify:worker` | Start/stop Spotify manual connect |

## Database

### Table: `channel_status`

| Column | Type | Description |
|--------|------|-------------|
| `account_id` | `UUID` (PK, FK) | Account ID |
| `platform` | `TEXT` (PK) | Platform identifier |
| `broadcast_id` | `TEXT` (PK) | Broadcast/stream identifier (per-broadcast rows for multi-stream) |
| `is_online` | `BOOLEAN` | Whether the channel is currently live |
| `broadcast_status` | `TEXT NULL` | `"live"`, `"upcoming"`, or `NULL` (non-YouTube platforms) |
| `stream_title` | `TEXT` | Current stream title |
| `category` | `TEXT` | Current stream category/game |
| `viewer_count` | `INT` | Current viewer count |
| `like_count` | `INT NULL` | Current like count (YouTube only) |
| `total_views` | `BIGINT NULL` | Lifetime view count (YouTube only) |
| `started_at` | `TIMESTAMPTZ` | When the stream started |
| `scheduled_start` | `TIMESTAMPTZ NULL` | When an upcoming broadcast is scheduled to start |
| `live_chat_id` | `TEXT NULL` | YouTube live chat ID for this broadcast |
| `updated_at` | `TIMESTAMPTZ` | Last status update |

**Primary key:** `(account_id, platform, broadcast_id)` -- one status row per broadcast per platform per account, using upsert on conflict.

### DB Functions

| Function | Description |
|----------|-------------|
| `set_online` | Upsert with `is_online = TRUE` and metadata (title, viewer count, like count, total views, scheduled start, live chat ID) |
| `set_offline` | Set `is_online = FALSE`, clear `started_at` |
| `upsert_upcoming` | Upsert an upcoming broadcast (`is_online = FALSE`) with title and scheduled start when available; the live chat ID may be absent until resolution succeeds |
| `delete_broadcast` | Delete a specific broadcast row (used when a broadcast disappears from discovery) |
| `get_status` | Get all statuses for an account, ordered by platform |
| `is_any_online` | Check if any platform is online (DB fallback) |
| `update_stream_data` | Update viewer count, title, category for online channels |
| `get_all_online_accounts` | Boot recovery: all accounts with online channels, grouped |

### Redis Keys

| Key | TTL | Description |
|-----|-----|-------------|
| `lumio:spotify_manual:{account_id}` | 30 min | Manual Spotify connect active flag |
| `lumio:channel_schedule:{platform}:{channel_id}` | 10 min (failed fetch: 2 min) | Cached Twitch/Kick stream plan |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/channel_status.rs` | GraphQL queries and mutations |
| `apps/api/src/db/channel_status.rs` | Database operations |
| `apps/api/src/services/channel_status.rs` | Manual connect logic (Redis TTL, pub/sub) |
| `apps/api/src/services/channel_schedule.rs` | Stream plan: sources, window, cache |

---

## Features / Emotes

Source: https://docs.lumio.vision/features/emotes

# Emotes

## Overview

The emotes module fetches, caches, and parses chat emotes from multiple providers across platforms. It supports both channel-specific emotes (fetched per platform + channel ID) and user-specific emotes (Twitch subscriber emotes for the authenticated user). Emotes are used in chat message rendering and overlay alerts.

## Architecture

```
Dashboard UI / Overlay
    |
    v
Next.js API Proxy (/api/emotes)
    |
    v
REST API (GET /v1/emotes/{platform}/{channel_id}, GET /v1/emotes/user)
GraphQL   (emotes(platform, channelId), userEmotes)
    |
    v
services::emotes::resolve_channel_emotes  (one shared code path)
    |
    +--> Redis hot-cache check
    |       Hit? --> Return cached EmoteSet[]
    |
    +--> Fetch from provider APIs (Twitch, YouTube, Kick, 7TV, FFZ, BTTV)
    |       success --> upsert rows into the durable chat_emotes catalog
    |                   (invalidates the catalog map key; never fails the request)
    |
    +--> Assemble response
    |       any provider returned emotes? --> use the fetched sets
    |       total upstream outage?        --> fall back to the chat_emotes catalog
    |                                          (a failed fetch never empties the map)
    |
    +--> Warm the Redis hot cache
    |
    v
EmoteSet[] response
```

The channel-emote path (`emotes` / `GET /v1/emotes/{platform}/{channel_id}`) is a
single function shared by REST and GraphQL, so both protocols return the **same
set, the same fields and the same errors** and both read/write the **one** Redis
hot-cache key - neither can poison the other (ZAF-577).

### Emote Providers

| Provider | Enum Value | Platforms | Description |
|----------|------------|-----------|-------------|
| **Twitch** | `twitch` | Twitch | Native Twitch emotes (global + channel) |
| **7TV** | `7tv` | Twitch, YouTube, Kick | Third-party emote service |
| **FrankerFaceZ** | `ffz` | Twitch, YouTube | Third-party emote extension |
| **BetterTTV** | `bttv` | Twitch, YouTube, Kick | Third-party emote extension |
| **YouTube** | `youtube` | YouTube | YouTube native chat emojis (~100 standard shortcodes such as `:yt:`, `:hand-pink-waving:`) |
| **Kick** | `kick` | Kick | Kick native emotes: the channel set, Kick's `Global` set and Kick's `Emojis` set |

### Per-Platform Fetch Strategy

| Platform | Providers Fetched |
|----------|-------------------|
| **Twitch** | Twitch (native channel and global, fetched as two separately-scoped sets; needs the `twitch` system credential's client_id **and** client_secret), 7TV (channel + global), FFZ (channel), BTTV (channel), FFZ (global) |
| **YouTube** | YouTube (native standard emojis), 7TV (channel + global), BTTV (channel), FFZ (channel + global) |
| **Kick** | Kick (channel, `Global`, `Emojis`), 7TV (channel + global), BTTV (channel), FFZ (global). FFZ has no Kick channel support, so only its global set is fetched. |

Empty sets are filtered out -- only providers with at least one emote are included in the response.

#### Kick native sets

Kick's official API has no emote endpoint, so the Kick sets come from Kick's
**undocumented** website endpoint `https://kick.com/emotes/{slug}` (no token is
sent). It returns three sets, each returned as its own `EmoteSet` with
`provider = "kick"` and a `section` field:

| `section` | Content | Catalog scope |
|-----------|---------|---------------|
| `channel` | The channel's own emotes | the channel (`channel_id` = Kick broadcaster id) |
| `global` | Kick's global emotes | `channel_id = NULL` |
| `emojis` | Kick's emoji set | `channel_id = NULL` |

Every Kick emote carries `subscribers_only` (`true` = usable only by the
channel's subscribers; the field is omitted when `false`) and the image URL
`https://files.kick.com/emotes/{id}/fullsize`. The endpoint is keyed by the
channel **slug**: it comes from `channel_connections.channel_login` (set on
connect and back-filled from the chat webhook's `broadcaster.channel_slug`),
falling back to the official `GET /public/v1/channels?broadcaster_user_id=` with
the connection's token. The fetch is **fail-open**: an unknown slug, a timeout,
a Cloudflare `403` or a format change yields no Kick sets, never an error, and
the resolver falls back to the durable catalog. Sets rebuilt from the catalog
carry no `section` / `subscribers_only` (the catalog does not store them).

**Channel owner.** Kick's channel set carries the broadcaster as
`user: {id, username, profile_pic}`. Every emote of the `channel` section gets
`owner_id = "kick:<user id>"` (for example `kick:676` for xQc), and the response's
`owners` map carries that id's `display_name` (Kick `username`) and `avatar_url`
(Kick `profile_pic` on `files.kick.com`, `https://` only). The emote library uses
them to show one section per Kick channel, labelled with the streamer's name
and avatar, the same way it groups Twitch channel emotes. Kick owner ids are
namespaced with `kick:` because Kick and Twitch ids are both bare numbers and
the frontend keys `owners` by id. `global` and `emojis` emotes have no
`owner_id`. A channel set without a usable `user` yields no owner and no error,
and so does a response rebuilt from the catalog: the catalog keeps `owner_id`
on the rows but not the owner's name or avatar, so `owners` is then `null` and
the frontend falls back to its generic **Channel** label. The owner is part
of the fetched sets, so it is cached with them in the Redis hot cache; it costs
no extra upstream call.

**No cross-channel subscriber emotes on Kick.** Twitch's `GET /v1/emotes/user`
(Helix `chat/emotes/user`) also lists emotes from other channels the viewer is
subscribed to. Kick has no official equivalent: the Kick website gets that list
through the viewer's session cookie, and Lumio never sends its OAuth token to
undocumented Kick hosts. The Kick menu therefore shows the current channel(s)
plus Kick's `Global` and `Emojis` sets, not the viewer's subscriptions to other
channels.
Fetch outcomes are counted in `chat_emote_set_fetch_total{platform, outcome}`. Any other `platform` value returns an empty set list.

#### The Twitch app access token

Helix `GET /chat/emotes` and `GET /chat/emotes/global` require a real bearer
token even though the data is public, so the native Twitch sets are fetched with
an **app access token** minted from the `twitch` system credential via the
OAuth2 client-credentials grant (`api::oauth::get_app_access_token`). The token
is app-scoped, not user-scoped - one Redis key per platform
(`lumio:oauth:app_token:{platform}`), cached for the grant's lifetime minus a
5-minute safety margin and capped at 24h so a rotated or revoked credential
cannot linger for the full ~60 days Twitch hands out.

If the system credential is missing, carries no client_secret, or the grant
fails, the two Twitch fetches are **skipped entirely** and the rest of the
providers are unaffected. Skipping is deliberate: sending an empty bearer would
cost two round-trips per cache miss to be told `401` and still yield nothing.

Every successful fetch is upserted into the durable `chat_emotes` catalog
(`source = 'api_fetch'`; `provider` is who hosts the emote, `platform` is the
chat platform it is usable on, `channel_id` is `NULL` for a provider's global
set). If **every** third-party fetch fails - a total upstream outage - the
response is served from the catalog instead of collapsing to an empty set, so a
provider outage can no longer wipe a channel's emote map. The YouTube static
standard-emoji set is exempt: it is always present and is deliberately not
counted when deciding whether to fall back. All catalog reads and writes are
fail-open: a Postgres or Redis error is logged and degrades, it never fails the
request. See the [Emote Catalog developer guide](../developer-guide/emote-catalog.md).

### Provider Channel-Lookup URLs

| Provider | Twitch | YouTube |
|----------|--------|---------|
| 7TV | `POST https://7tv.io/v4/gql`, platform `TWITCH` | `POST https://7tv.io/v4/gql`, platform `GOOGLE` |
| BTTV | `https://api.betterttv.net/3/cached/users/twitch/{channel_id}` | `https://api.betterttv.net/3/cached/users/youtube/{channel_id}` |
| FFZ | `https://api.frankerfacez.com/v1/room/id/{channel_id}` | `https://api.frankerfacez.com/v1/room/yt/{channel_id}` |

Note on 7TV: emotes come from 7TV's v4 GraphQL API, not the v3 REST API (in
maintenance mode, and it rejects YouTube with `400 invalid platform`). The
channel lookup is `users.userByConnection(platform, platformId)` with platform
`TWITCH`, `KICK` or `GOOGLE`. For YouTube, `platformId` is the `UC…` channel id.
The query reads the channel's active emote set. The global set comes from
`emoteSets.global` in a second request, so one failing never empties the other.
Both requests ask only for the 7TV user id, the active set id and each emote's
id, set alias and `animated` flag. The emote `name` is the set alias, which is
the name chat types, not the emote's default name. 7TV reports query errors with
HTTP 200: an `errors` array or `data: null` is logged and treated as a failed
fetch (fail-open), and `userByConnection: null` means no 7TV account is linked
to the channel.

Note on FFZ: while BTTV uses a `/users/...` URL pattern, FFZ uses `/room/...`. Both are equivalent in semantics - they return the channel-active emote set. FFZ's `/user/...` endpoint returns user-profile data (uploaded sets, badges) and is **not** what the chat renders.

## Chat emote and badge cards

Hover an emote or badge in Multichat, its chat popout, an event line, or the user card to open a larger card. A touch tap opens a bottom sheet on a phone; on a wider tablet it opens a card beside the item. The same interaction works in a chat popout used as an OBS dock or browser source. The card uses a larger provider image when available and falls back to the chat image if it fails to load. A badge without an image shows its drawn badge artwork instead.

An emote card shows its name, provider, image, origin when known, and ID when present. It can show the creator name for 7TV, BTTV, or FFZ, and a YouTube member-emote label. The **Animated** or **Static** chip appears only when that state is known: Twitch, 7TV, and BTTV use their emote flag; FFZ uses a flag from a live provider fetch; Kick and YouTube use the server-side image check in [`emoteInfo`](../api-reference/graphql.md#emoteinfo). Catalog fallback values of `animated: false` for older FFZ rows and for Kick or YouTube do **not** establish that an image is static. An unknown result shows no chip.

Origin is read from the message's emote identity and the channel catalog. Twitch message fragments can carry the owning broadcaster ID; YouTube channel-emote IDs contain a `UC…` channel ID; Kick channel sets carry an owner ID when Kick supplies one. The card labels global emotes and the current or another channel when it can establish the scope. For another channel it shows the channel name or ID; a Twitch login or YouTube channel ID supplies a channel link. Kick does not reliably supply a foreign channel slug, so its channel name can appear without a usable link. Third-party catalog sets supply `channel` or `global` scope and, where available, a creator name. A 7TV, BTTV, or FFZ emote also links to its provider page when its ID is valid.

**Copy name** copies text for pasting into chat: the exact case-sensitive name for Twitch, 7TV, BTTV, and FFZ; a colon-wrapped shortcode such as `:yt:` for YouTube; and `[emote:37226:KEKW]` for a Kick emote with a numeric ID. If that Kick ID is unavailable, it copies the name. Kick's native chat renders the markup as an emote; a bare name remains text. **Copy ID** copies the emote ID when present. Badge cards show the badge image, title including a known tier or month count, and platform, with no ID or copy controls. In an OBS browser source, external popups may be blocked, so a **Copy link** control appears beside channel and provider links for opening them in a browser.

### In stream reports

The top emotes and top GIFs of a [stream report](./stream-history.md) open the same card, on the dashboard and on a shared report. An emote card shows the full name the tile cuts off, the larger image, the provider, the use count and — for reports finalized with them — the emote ID, the **Animated**/**Static** chip, the chat platform it was used on (when it differs from the provider) and the owning channel. A report has no live chat around it, so the card names the owning channel without a "this channel" or "other channel" label. Older reports without these fields show name, provider, image and count only, with no empty ID line.

A GIF card shows a larger preview, the caption, the platform, the source (GIPHY for Twitch GIFs) and how often it was posted. It links to the GIF's GIPHY page only when both the stored ID and the image address identify a GIPHY GIF. At **Animations in Lumio: Reduced** or **Off** (or a reduced-motion system setting on a shared report), the card shows a still placeholder and plays the GIF only after **Play** is pressed. On touch devices a tap on a GIF tile opens the card or sheet; the tile itself does not start playing, so the GIF plays from the card's **Play** button.

A shared report is public and has no session, so its cards make no server requests: they show only what the report stored. The owning channel's name therefore stays unknown there; the channel row appears only when the stored ID alone gives a safe link (a YouTube `UC…` channel ID).

## API

### REST Endpoints

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| `GET` | `/v1/emotes/{platform}/{channel_id}` | Fetch channel emotes | Authenticated (no RBAC permission) |
| `GET` | `/v1/emotes/user` | Fetch user's Twitch subscriber emotes | Authenticated + active account |
| `GET` | `/v1/emotes/info` | Resolve owner and Kick/YouTube image animation for up to 50 emotes | Authenticated, including popout tokens; overlay, shared overlay, widget and extension tokens refused; no RBAC permission |

### GraphQL

The same data is exposed as two queries in the chat schema, both guarded by
`feature:multichat` + `chat:read`:

| Query | Returns | Permission |
|-------|---------|------------|
| `emotes(platform: String!, channelId: String!)` | `GqlEmoteSetsResponse!` | `feature:multichat` + `chat:read` |
| `userEmotes` | `GqlEmoteSetsResponse!` | `feature:multichat` + `chat:read` |
| `emoteInfo(platform: String!, items: [GqlEmoteInfoItemInput!]!)` | `[GqlEmoteInfo!]!` | Authenticated, including popout tokens; overlay, shared overlay, widget and extension tokens refused; no RBAC permission |

The channel query and its REST twin resolve through the **same**
`resolve_channel_emotes` function, so their returned sets, fields and errors are
identical. The one
deliberate asymmetry is the guard: the GraphQL surface carries the chat feature
flag and the `chat:read` permission, while the REST surface only requires an
authenticated principal - emote catalogues are public data. (The web app reads
emotes through GraphQL only.) GraphQL exposes the Kick fields as `section` on
`GqlEmoteSet` and `subscribersOnly` on `GqlEmote`; REST returns the same values
as `section` / `subscribers_only`. Both protocols return the same `owners`
(Kick channel owners, see [Kick native sets](#kick-native-sets)): REST as a map
keyed by owner id, `{"kick:676": {"display_name": "xQc", "avatar_url": "https://files.kick.com/..."}}`,
GraphQL as the list `owners: [GqlEmoteOwner { id, displayName, avatarUrl }]`.
`owners` is `null` when no set has an owner (every non-Kick channel request, a
Kick body without `user`, a catalog fallback).

`emoteInfo` and `GET /v1/emotes/info` share validation and resolution. They accept `twitch`, `youtube`, or `kick`, return one result per item in request order, and cap each request at 50 items. Overlay, shared overlay, widget and extension tokens are refused with `Emote details are not available to overlay, widget or extension tokens` (ZAF-1922). Per request at most 10 distinct owners are resolved and at most 10 images probed; items beyond come back `owner: null` / `animated: null`. Probe results are cached by the fetched image URL (hashed), not by the client's emote id. Each result has an emote ID, a nullable owner (`owner_id`, login, display name, avatar URL), and a nullable animated state. The image check applies only to Kick and YouTube; see the [GraphQL reference](../api-reference/graphql.md#emoteinfo) and [REST reference](../api-reference/rest-api.md#get-v1emotesinfo).

#### GET /v1/emotes/{platform}/{channel_id}

Fetches all available emote sets for a given platform and channel. Results are cached in Redis.

**Response:**
```json
{
  "data": {
    "sets": [
      {
        "provider": "7tv",
        "emotes": [
          {
            "id": "60ae958e...",
            "name": "LULW",
            "url": "https://cdn.7tv.app/emote/.../1x.webp",
            "provider": "7tv",
            "animated": false
          }
        ]
      }
    ],
    "owners": null
  }
}
```

#### GET /v1/emotes/user

Fetches all Twitch emotes available to the authenticated user (subscriber emotes from all channels). Requires a Twitch login connection with `user:read:emotes` scope. Automatically refreshes the token if expired.

Also resolves emote owner information (channel names and avatars) via batch Twitch user lookup.

**Response includes:**
- `sets` -- Array of `EmoteSet` with the user's available emotes
- `owners` -- Map of owner IDs to `{ display_name, avatar_url }` for grouping emotes by channel (GraphQL: `[{ id, displayName, avatarUrl }]`)

## Types

### EmoteSet

```rust
struct EmoteSet {
    provider: EmoteProvider,  // twitch, 7tv, ffz, bttv, youtube, kick
    emotes: Vec<Emote>,
    section: Option<String>,  // Kick: "channel" | "global" | "emojis"; omitted otherwise
}
```

### Emote

```rust
struct Emote {
    id: String,               // Provider-specific emote ID
    name: String,             // Emote name (e.g., "Kappa", "LULW")
    url: String,              // CDN URL for the emote image
    provider: EmoteProvider,  // Source provider
    animated: bool,           // Whether the emote is animated (GIF/WEBP)
    owner_id: Option<String>, // Owner for grouping: Twitch broadcaster id, or "kick:<user id>" (Kick channel emotes)
    subscribers_only: bool,   // Kick sub-only emote; omitted from JSON when false
    owner_name: Option<String>, // 7TV, FFZ or BTTV creator name when known
    scope: Option<String>,      // "channel" or "global" for third-party sets
}
```

### Message Parsing

The `parse_emotes()` function splits a chat message into segments of text and emotes:

```rust
fn parse_emotes(message: &str, emote_sets: &[EmoteSet]) -> Vec<EmotePart>
```

**Behavior:**
- Builds a name-to-emote lookup from all provided sets
- Splits message on whitespace boundaries
- Exact, case-sensitive matching only (`Kappa` matches, `kappa` does not, `KappaRoss` does not)
- Consecutive text words are merged into a single `EmotePart::Text`
- Returns `Vec<EmotePart>` where each part is either `Text { text }` or `Emote { id, name, url, provider }`

A sibling helper, `enrich_message_emotes_from_sets(message, sets)`, applies the
same word-based matching but returns the standard chat `emotes` JSON array
(`[{id,name,url,provider,animated}]`, deduped by name) or `None`. The Kick webhook path normalises Kick's raw
`[emote:ID:NAME]` markup into the same shape — see [Kick chat emotes](#kick-chat-emotes).

## Twitch cheermotes

A cheer in Twitch chat (`Cheer100`) is a normal chat message whose cheer words
arrive as `cheermote` fragments. The EventSub worker turns each one into an
entry of the message's existing `emotes` array, so live WebSocket delivery,
persistence and chat history (GraphQL and REST pass the JSONB through
unchanged) carry it without a new column:

```json
{
  "id": "cheermote:cheer:100",
  "name": "Cheer100",
  "url": "https://d3aqoihi2n8ty8.cloudfront.net/actions/cheer/dark/animated/100/2.gif",
  "provider": "twitch",
  "animated": true,
  "kind": "cheermote",
  "bits": 100,
  "color": "#9c3ee8",
  "urls": {
    "dark": {
      "animated": "…/dark/animated/100/2.gif", "static": "…/dark/static/100/2.png",
      "animated_hd": "…/dark/animated/100/4.gif", "static_hd": "…/dark/static/100/4.png"
    },
    "light": {
      "animated": "…/light/animated/100/2.gif", "static": "…/light/static/100/2.png",
      "animated_hd": "…/light/animated/100/4.gif", "static_hd": "…/light/static/100/4.png"
    }
  }
}
```

- `name` is the word as typed, `bits` the amount of that occurrence, `color` the
  tier colour. `url` is the dark animated image, so a reader that only knows
  emote entries still shows a graphic.
- Every theme carries an animated and a still image per density: `animated` /
  `static` are Helix scale `2` (56 px) and always present; `animated_hd` /
  `static_hd` are scale `4` (112 px) for large chat fonts. The HD pair is
  optional — it is only written when Twitch has both scale-4 images for that
  theme, never one without the other; a tier without scale 4 keeps only the
  scale-2 keys. Entries stored before the HD pair existed have no `*_hd` keys.
- The dashboard picks the scale-4 file on a 2× screen (`srcset` `1x`/`2x`) and
  whenever the rendered graphic is larger than 28 CSS px, the scale-2 file
  otherwise. It never uses an animation as the still: without motion an entry
  that has no `static` image (or only the legacy `url`) renders as text.
- Images come from Helix `GET /bits/cheermotes?broadcaster_id=` (global plus the
  channel's custom cheermotes), scale `2` plus optional scale `4`, cached in Redis under
  `lumio:cheermotes:v2:twitch:{broadcaster_id}` for 6 h; after a failed fetch an
  empty placeholder is cached for 5 min (`apps/api/src/services/cheermotes.rs`).
  The worker's channel token is used; Helix accepts an app or a user token.
- The catalog is only looked up for messages that contain a cheer, and the
  cache-miss fetch is capped at 2 s. **Fail-open:** without a catalog, or for a
  prefix the catalog does not know, no entry is written and `Cheer100` stays
  text. A Shared Chat cheer uses the origin channel's catalog.
- Cheermote entries are **not** emotes for statistics: the stream report's
  `emote_total` / `top_emotes` skip entries with `kind = "cheermote"`.

The `twitch:cheer` event gets the same entries from its plain-text message, plus
a total-amount image set — see [Events → Twitch cheer payloads](./events.md#twitch-cheer-payloads-twitchcheer).

## Kick chat emotes

Kick's `chat.message.sent` webhook carries emotes **inline** in `content` as
`[emote:ID:NAME]` markers, for example
`Hello [emote:4148074:HYPERCLAP] [emote:37226:KEKW]`. The accompanying
`emotes[].positions {s, e}` span the whole marker and `e` is inclusive.

**Ingest** (`services::kick_emotes::extract_kick_emotes`): the marker is the
source of truth. Each marker (`\[emote:(\d+):([^\]\s]+)\]`) is replaced by its
name in the stored message text, and the message gets one `emotes` entry **per
occurrence**, `{id, name, url, provider: "kick", animated: false}`, with the URL
frozen at ingest as `https://files.kick.com/emotes/{id}/fullsize` — the same
pattern as Twitch. A message without a marker has no `emotes` field; a malformed
marker stays text. The quoted reply parent (`reply_parent_message`) is converted
to plain text the same way. `emotes[]` is only cross-checked.

**Stored rows from before this parser** were rewritten once by the TimescaleDB
migration `20260930000001_kick_chat_emote_markup_backfill` (text + `emotes`).

**Sending:** Kick renders an emote only when it receives the marker. The Kick
send path (`services::chat_send::send_kick`, shared by GraphQL
`sendChatToPlatform` and REST `POST /v1/chat/send`) converts every whitespace-
separated word that exactly matches a known Kick emote (Kick-provider rows of
the channel's catalog, including Kick's global and emoji sets) into
`[emote:ID:NAME]`. 7TV/BTTV/FFZ names stay text.

**Rendering:** Kick needs no special case in `MessageContent`. The message
text holds the emote names and the per-message `emotes` array holds their frozen
URLs, as for Twitch. Kick markers may sit back to back or touch punctuation
(`[emote:1:A][emote:1:A]!` is stored as `AA!`). So a per-message emote is also
matched *inside* a longer whitespace-token, but only for the occurrences that
were not already matched as a whole word. This keeps a Twitch `LUL` sent once
from turning the word `LULW` into an image, and channel-map emotes are never
split out of a word.

**Emote menu:** the Emote Library in the chat input orders Kick's sets like
Twitch's. Kick channel emotes get **one section per Kick channel**, grouped by
`owner_id` and labelled with the owner's `display_name`, with the avatar in the
section header and the sidebar. These sections sit in the same block as the
Twitch channel sections: after **Recently Used**, before 7TV/BTTV/FFZ. A channel
emote whose owner has no `owners` entry (for example the catalog fallback) shows
under the generic **Channel** label with the Kick icon. **Kick Global** and
**Kick Emojis** follow the providers, like **Twitch Global**. When Kick's own
emote endpoint cannot be reached, the menu still shows those sections from the
durable catalog (the last known state), and the server retries Kick within 5
minutes instead of keeping the incomplete menu for 6 hours. The **Kick** platform
tab shows the Kick channel sections, Kick Global, Kick Emojis and the
7TV/BTTV/FFZ emotes fetched for the Kick channel; Twitch sections never appear
there, and Kick sections never appear on the Twitch tab. Emotes with
`subscribers_only` carry a lock marker and a "Subscribers only" tooltip. Clicking
an emote inserts its name, and the send path above turns it into the marker. The
web proxy (`/api/emotes/{platform}/{channelId}`) requests
`owners { id displayName avatarUrl }` and returns them as the same
`Record<ownerId, { display_name, avatar_url }>` map as `/api/emotes/user`; the
browser merges the owners of every channel response over the user endpoint's and
caches sets plus owners in `localStorage` under `lumio:emotes:v4:*` for 6 hours.

## YouTube Standard Emojis

YouTube Live Chat ships with ~100 platform-native standard emojis (e.g. `:yt:`, `:hand-pink-waving:`, `:dothefive:`). YouTube does not expose an API for the catalogue, so the list is curated manually in `crates/lo-chat/src/youtube_emotes.rs` and embedded in the REST/GraphQL response for `platform = "youtube"` as an additional `EmoteSet` with `provider = "youtube"`. The set is pushed first in the response so the frontend's first-write-wins emote map gives YouTube native emojis priority over any 7TV/BTTV/FFZ entry that happens to share a shortcode.

**Sending:** YouTube Live Chat renders `:shortcode:` tokens server-side, so chat messages sent through Lumio with YouTube shortcodes are forwarded as plain text in `messageText` and YouTube turns them into emoji images on delivery. No client-side conversion is required.

**Rendering:** Incoming YouTube messages keep the raw shortcode in `message_text`. The `MessageContent` renderer (`apps/web/src/app/(main)/(app)/dashboard/chat/message-content.tsx`) and the lighter `EmoteText` component split each whitespace-token by the shortcode regex `:[a-zA-Z0-9_-]+:` and replace runs of back-to-back shortcodes (e.g. `:hand-pink-waving::hand-pink-waving:`) with separate `<img>` elements separated by visible spaces.

**Super Chats and membership milestones:** a `youtube:superchat` or `youtube:member` event stores the emotes in the viewer's message as `raw.emotes`, in the same shape chat messages use; an event without emotes has no `emotes` key, and its text keeps the shortcodes unchanged. On the InnerTube path every emoji YouTube sent with the message resolves, standard and channel-custom, from the image in the message itself; channel-catalog emotes (for example a 7TV name typed as text) resolve too. On the Data API and gRPC path the message is text only, so its emotes resolve from the channel catalog. The event therefore carries its own emote images and does not depend on the channel emote map. A new member's welcome text is YouTube's own text, not the viewer's, and is not scanned.

**URL freshness (ZAF-578):** each stored message freezes its emotes' CDN URLs at write time, so a rotated URL (e.g. a dead `yt3.ggpht.com` link) would render broken forever. When a name resolves in **both** the per-message array and the live channel-emote map, the renderer prefers the channel-map URL for the image (keeping the per-message entry's identity), and falls back to the frozen URL only when the catalog has no row. A name with no usable URL on either side renders as plain text rather than a broken image.

**Adding new emojis:** Append a `(shortcode, cdn_url)` tuple to `YOUTUBE_STANDARD_EMOTES` in `crates/lo-chat/src/youtube_emotes.rs` and rebuild the API binary.

## Caching and durable storage

Emote definitions are persisted in the **emote catalog** - the `chat_emotes` table
in the primary PostgreSQL - with Redis and an in-process LRU acting as caches in
front of it:

```
LruCache (in-process, ~60s)  ->  Redis (6h)  ->  Postgres chat_emotes
```

A cache expiry therefore only empties a cache; the shortcode → URL mapping itself
survives. See the [Emote Catalog developer guide](../developer-guide/emote-catalog.md)
for the tier semantics, the schema, the invalidation rule, and how to add a
writer.

The channel-emote fetch path is both a **reader and a writer** of the catalog.
It still keeps its assembled provider sets in a Redis hot cache per platform +
channel ID (the versioned `lumio:emotes:v4:{platform}:{channel_id}` key used by
`emote_service::get_cached_emotes` / `cache_emotes`, 6 h - 5 min for a degraded
response), checked before any external API call. The version segment
(`EMOTE_CACHE_VERSION`) is bumped whenever the cached sets change shape, so a
deploy never serves the previous build's sets for the rest of their TTL. On a cache miss it fetches from the providers, **upserts every success
into `chat_emotes`** (`source = 'api_fetch'`, via
`emote_catalog::upsert_and_invalidate`), and - when every fetch fails, or only the platform-native one (Kick's own sets, Twitch Helix) - reads the durable catalog back (`emote_catalog::load_channel_emote_sets` / `load_channel_provider_emote_sets`)
so an outage degrades to the last known state instead of an empty map. See [Serving the catalog on an upstream outage](../developer-guide/emote-catalog.md#serving-the-catalog-on-an-upstream-outage).

For connected Twitch, Kick and YouTube channels, the [7TV EventAPI listener](/developer-guide/seventv-event-listener)
deletes the channel hot-cache key when its active 7TV set changes. Additions
and renames also update the catalog map; the browser refreshes the picker and
autocomplete after a matching live event, debounced by two seconds. The
six-hour hot-cache TTL is the fallback if event delivery is unavailable.
Removals clear the hot cache but do not delete old catalog rows; a removed
shortcode can remain in the chat-ingest map until that map expires.

User emotes are cached separately under `twitch-user:user:{user_id}` with owner data cached under `lumio:emotes:owners:{user_id}` (1 hour TTL).

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/routes/emotes.rs` | REST endpoints for channel and user emotes |
| `apps/api/src/services/cheermotes.rs` | Twitch cheermote catalog (Helix `bits/cheermotes`, Redis 6 h / 5 min) and the cheermote entry shape |
| `apps/api/src/services/emotes.rs` | Provider fetch functions, owner resolution, and the shared `resolve_channel_emotes` orchestrator (hot cache → fetch → catalog upsert → outage fallback) used by both REST and GraphQL |
| `crates/lo-chat/src/emote_catalog.rs` | Durable `chat_emotes` catalog + three-tier read-through; `upsert_and_invalidate` (API-fetch writer) and `load_channel_emote_sets` (outage fallback read) |
| `crates/lo-chat/src/emotes.rs` | Core types (`Emote`, `EmoteSet`, `EmoteProvider`, `EmotePart`) and `parse_emotes()` |
| `crates/lo-chat/src/youtube_emotes.rs` | Static catalogue of YouTube native standard-emoji shortcodes |
| `apps/web/src/app/(main)/(app)/dashboard/chat/message-content.tsx` | Multichat renderer with shortcode-splitting + colon-fallback |
| `apps/web/src/app/(main)/(app)/dashboard/chat/emote-library.tsx` | Emote picker with platform tabs and the `youtube-global` section |

---

## Features / Emote Directory

Source: https://docs.lumio.vision/features/emote-directory

# Emote Directory

## Overview

The **Emote Directory** is a public, unauthenticated, edge-cacheable browse of
Lumio's durable cross-platform emote catalog (`chat_emotes`). It is the read
surface behind the public Stats app's emote-verzeichnis - the founder-scoped
decision on ZAF-583 was that *"emote verzeichnis kann öffentlich sein und braucht
kein auth"*, so this ships as an open read model with **no login and no RBAC**.

It exposes the same catalog that powers chat rendering and the stream-report
image fallback, but as a browseable list rather than a per-channel emote map. The
catalog is deliberately **tenant-free** - every row is public reference data (the
same CDN URL the chat renderer already uses), so there is no account
boundary to enforce on the read (see the [Emote Catalog](../developer-guide/emote-catalog.md)
developer guide and its migration header).

This is a **read-only** surface. Ingest and upserts into `chat_emotes` are owned
by the emote-fetch / chat pipeline; nothing here writes.

## Protocols

Per the three-protocol rule, the directory ships in **GraphQL (primary) + REST
parity** - identical fields, filters, pagination and error messages on both:

| Protocol | Surface |
|----------|---------|
| GraphQL | `publicEmotes(platform, provider, channelId, animated, search, page, limit): PublicEmotePage!` |
| REST | `GET /v1/public-stats/emotes?platform=&provider=&channel_id=&animated=&search=&page=&limit=` |

**WebSocket is deliberately omitted.** A static browse / search directory has no
live-push consumer - there is nothing to stream - so no WS channel is added and
no `channel_gate_for` / `channel_feature_for` entry is created. AGENTS.md permits
this justified single-protocol omission, and it is documented at both the GraphQL
resolver and the REST handler call sites.

## Filtering, search & pagination

All filters are optional and compose with `AND`:

| Filter | Matches |
|--------|---------|
| `platform` | Exact platform the emote is usable on: `twitch` / `youtube` / `kick` |
| `provider` | Exact host: the platforms above plus `7tv` / `bttv` / `ffz` |
| `channel_id` (`channelId`) | Exact platform channel id; omit to include global (platform-wide) sets |
| `animated` | The animated flag (`true` / `false`) |
| `search` | **Case-insensitive substring** match on the emote `name`. Wildcard characters (`%`, `_`) are matched literally, not as SQL wildcards. |

Pagination is **page-based**: `page` is 1-based (default 1) and `limit` is
clamped to `1..=100` (default 50). The response carries `total` and
`total_pages`. Results are ordered by `name` then `id`, giving a stable
alphabetical directory that paginates deterministically.

Each emote carries: `id`, `platform`, `provider`, `channel_id` (`null` for a
global set), `name`, `url`, `animated`, `owner_id`, `source` (`api_fetch` |
`observed`), `first_seen_at`, `last_seen_at`. The internal `provider_emote_id` is
not exposed.

> **Not modelled (yet):** sorting by usage frequency. `chat_emotes` carries no
> usage counter today (open in ZAF-581), so the directory cannot rank by
> popularity. That is a possible later addition, not part of this surface.

## Public-origin hardening

Because the origin is public and unauthenticated, two protections apply:

- **Rate-limiting.** Every request is throttled by the anonymous-tier, per-IP
  rate limiter that wraps every `/v1` request - no special-casing needed.
- **Edge caching.** The REST `200` sets
  `Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600`.
  The catalog changes on the order of minutes, so edge caching absorbs browse /
  abuse load. The GraphQL surface is a `POST` (not edge-cacheable) and is cached
  at the SSR layer of the public Stats app instead.

## Operator kill-switch

The whole public origin is gated by the account-less **`system:public_stats`**
feature flag - a `system`-category master kill-switch, not a per-plan
entitlement. It defaults **on** (public reads open); flipping it off closes the
directory (and the sibling public channel/stream read model) without a deploy.
For an anonymous caller the flag resolves to its global default, so no account
context is required. When it is off, GraphQL returns
`Feature 'system:public_stats' is not available` and REST returns `403
FEATURE_DISABLED` with the same message.

## The directory page (Stats app)

The browseable UI lives on the public **Stats** app (`stats.lumio.vision`) at
**`/emotes`**, reachable from the left sidebar (**Emotes**). It is placed on the
cookieless public Stats origin - rather than the logged-in dashboard - because it
is public, needs no auth, and is aggressively edge-cached: no session cookie
leaks and the HTML is identical for every visitor.

The page is **server-rendered from the GraphQL read model** (`publicEmotes`) via
the app's public data path - the browser never calls GraphQL directly, and no
session is attached. All filter, search and page state lives in the **URL query**
(`?platform=`, `?provider=`, `?channel=`, `?animated=`, `?search=`, `?page=`), so
every distinct view is its own shareable, edge-cacheable URL and back/forward
navigation just works.

**Controls:**

- **Name search** - a debounced case-insensitive substring match on the emote
  name.
- **Platform** / **Provider** / **Type** (animated / static) dropdowns, and a
  **Channel ID** field. Changing any control resets to page 1.
- **Pagination** - `Previous` / `Next` links carry every active filter forward
  and show the current page, total pages and the total match count.

**Each emote tile shows** the emote image (through the Stats image proxy, on a
theme-aware checkerboard so transparent emotes stay legible), the emote name, an
**animated** marker on GIF emotes, and **provider / owner attribution** - the
provider (Twitch / YouTube / Kick / 7TV / BetterTTV / FrankerFaceZ) with
its icon, plus the owning channel id (or *Global set* for a platform-wide set).

The page is fully **bilingual (EN/DE)** with the standard Lumio language switcher
and supports **light and dark** themes, consistent with the rest of the Stats
app. When the operator kill-switch is off (or the backend is unreachable) the
page renders a calm *"directory unavailable"* state rather than an error.

> **Image note.** Emote images load through the Stats
> [image proxy](../developer-guide/image-proxy.md) (`/img/<provider>/…` on
> `stats.lumio.vision`): the visitor's browser never contacts the provider CDNs
> (7TV / BetterTTV / FrankerFaceZ / platform CDNs), so the images show without a
> consent choice. The founder accepted this public exhibition on ZAF-583; provider
> attribution is always shown. An emote URL the proxy does not cover shows a
> neutral placeholder.

## Related

- [Emotes](./emotes.md) - the per-channel emote fetching / rendering module.
- [Emote Catalog](../developer-guide/emote-catalog.md) - the durable
  `chat_emotes` store and its read-through cache.
- [Public Stats](./public-stats.md) - the per-channel publicness (opt-out)
  layer of the same public app.
- API reference: [GraphQL](../api-reference/graphql.md#emote-directory) ·
  [REST](../api-reference/rest-api.md#emote-directory).

---

## Features / Webhooks

Source: https://docs.lumio.vision/features/webhooks

# Webhooks

Lumio exposes a small set of inbound webhook endpoints under `/v1/webhooks/*` that receive platform event notifications (chat, subscriptions, follows, orders, payments) and fan them out into the same `lo-events` / `lo-chat` pipelines used by the rest of the stack. This page is the public contract for those endpoints.

## Overview

| Platform | Endpoint | Verification | Source crate |
|----------|----------|--------------|--------------|
| YouTube | `POST /v1/webhooks/youtube` (+ `GET` for the challenge echo) | HMAC-SHA256 (`X-Hub-Signature-256`) or HMAC-SHA1 (`X-Hub-Signature`) | `lo-youtube-api` |
| Kick    | `POST /v1/webhooks/kick`    | RSA-SHA256 (`Kick-Event-Signature`) or legacy HMAC (`X-Kick-Signature`) | `lo-kick-api` |
| Shopify | `POST /v1/webhooks/shopify` | HMAC-SHA256 (`X-Shopify-Hmac-SHA256`), app client secret | `lo-shopify` |
| Stripe  | `POST /v1/webhooks/stripe`  | `Stripe-Signature` (`t=…, v1=…`)         | `stripe-rust` |

All endpoints are **unauthenticated** - they are protected by per-platform signature verification, not JWT or API key auth. Callers are expected to be the platform itself, not Lumio users.

The `GET /v1/webhooks/youtube` challenge echo is the only endpoint with no signature step: it exists so the PubSubHubbub hub can confirm a subscription, and it simply reflects `hub.challenge` back as `200 text/plain`.

Route wiring: all seven receivers are mounted together in a dedicated `web::scope("/v1/webhooks")` in `apps/api/src/main.rs`, registered before the main `/v1` scope. The handlers themselves live in `apps/api/src/routes/webhooks.rs` (YouTube, Kick, Shopify), `apps/api/src/routes/webhooks_payments.rs` (Stripe Connect, PayPal Payouts) and `apps/api/src/routes/billing.rs` (Stripe billing).

## Rate limiting — webhook receivers are exempt

The `/v1/webhooks/*` scope sits **outside** the generic per-request rate limiter (`RateLimitMiddlewareFactory`) that wraps the authenticated `/v1` scope. This is deliberate: webhook deliveries arrive unauthenticated from a small, shared pool of the platform's own egress IPs, so under the limiter they all share **one** `anon:{ip}` bucket at the [anonymous tier of 120 req/min](/api-reference/authentication#rate-limits) — a single global cap across every tenant. An active Kick chat (`chat.message.sent`) exceeds 120/min instantly, and because Kick **auto-unsubscribes an app whose webhook fails continuously for ~a day**, the cap would not merely drop events — it would tear down the subscription, which a worker then re-creates, looping (ZAF-1519).

The abuse barrier that replaces the limiter is the **mandatory per-platform signature check** (`webhooks.require_signatures`, on by default): a forged or unsigned request is rejected with `401` before any database work, so the endpoint is signature-gated, not an open firehose. Delivery load is absorbed by the async pipeline (Redis chat buffer + `external_id` event dedup), never by rejecting deliveries. Any finite per-IP ceiling would only reproduce the auto-unsubscribe failure at a higher threshold, so no numeric limit is applied.

> **Twitch is not in this list.** Twitch events do not arrive via HTTP webhook in Lumio - see [Twitch (EventSub, WebSocket)](#twitch-eventsub-websocket-not-webhook) below.

## Twitch (EventSub, WebSocket, not webhook)

Twitch events do **not** use a webhook in Lumio. Instead, the API server runs a background worker (`apps/api/src/workers/twitch_eventsub.rs`) that opens a persistent EventSub WebSocket connection to `wss://eventsub.wss.twitch.tv/ws` per account, then calls the Helix `POST /eventsub/subscriptions` endpoint to register subscriptions with `transport: { method: "websocket", session_id }`.

Session lifecycle:

- **New session.** Before it opens the WebSocket, the worker checks the channel token and deletes the account's old subscriptions. It then registers all types as soon as the `session_welcome` arrives, because Twitch closes a session that has no subscription after 10 seconds.
- **Twitch `session_reconnect`.** The EventSub client (`crates/lo-twitch-api/src/eventsub.rs`) opens the `reconnect_url` and keeps reading the old connection. It closes the old connection only after the new connection sends its `session_welcome`. Twitch moves the subscriptions to the new connection, so the worker does not delete or recreate them, and no event is lost.
- **Failed handover or lost session.** If the handover fails (for example close code `4007`), the connection drops, or the keepalive times out, the worker opens a fresh session on the default endpoint and subscribes again. A Helix `400` saying the WebSocket transport session no longer exists stops the subscription run and also triggers a fresh session, so that no event type stays without a subscription.

Subscribed types are defined in `subscription_types::ALL` in `crates/lo-twitch-api/src/types.rs` (each paired with its EventSub version) and include: `channel.follow`, `channel.update`, `channel.cheer`, `channel.raid`, `channel.channel_points_custom_reward_redemption.add` and `.update` (`twitch:reward`, `twitch:reward_status`), `channel.channel_points_custom_reward.add` / `.update` / `.remove` (`twitch:reward_add` / `_update` / `_remove`, broadcast only), `stream.online`, `stream.offline`, `channel.chat.message`, `channel.chat.message_delete`, `channel.chat.notification`, `channel.subscription.gift`, `channel.ban`, `channel.unban`, `channel.moderate`, hype-train / poll / prediction / goal / ad-break events, and suspicious-user signals. `channel.chat.message_delete` (single-message moderator deletes) uses the same `broadcaster_user_id` + `user_id` condition as `channel.chat.message`, so it needs no additional scope beyond the chat-read grant already required for chat ingest.

`channel.subscribe` and `channel.subscription.message` are defined as constants but deliberately **omitted** from `ALL`: subscribe / resub activity is taken from `channel.chat.notification` instead, which fires in sync with chat and already carries `is_prime` / `sub_tier`.

`channel.subscription.gift` **is** in `ALL`, but only as a straggler safeguard. The canonical gift line still comes from `channel.chat.notification` (richer — `sub_tier`, `community_gift_id`, per-recipient rows). `channel.subscription.gift` is a single self-contained record (gifter + `total` + `is_anonymous`) that the worker holds for a short window keyed on `(gifter, total)`: if a canonical chat header for the same gift arrives in that window it wins and the safeguard is dropped, otherwise the gift line is generated from it. This keeps a gift visible even when the chat-notification path fails (missing / out-of-order per-recipient messages, reconnect, or tracker age-out) without ever doubling the line.

`channel.chat.notification` notice types that become events: `sub` (`twitch:subscribe`), `resub` (`twitch:resub`), `sub_gift` and `community_sub_gift` (`twitch:gift`), `prime_paid_upgrade` (`twitch:prime_upgrade`), `gift_paid_upgrade` (`twitch:gift_upgrade`), `pay_it_forward` (`twitch:pay_it_forward`) and `bits_badge_tier` (`twitch:bits_badge`). The other documented types (`raid`, `unraid`, `announcement`, `charity_donation`, plus their `shared_chat_*` variants) are dropped without logging; raids come from `channel.raid`. Any notice type Twitch has **not** documented is dropped too. Its first occurrence per API process is logged at `info` with the raw event (`Unrecognized channel.chat.notification notice_type dropped`), and later ones at `debug`. This is how payloads such as the Gift Match types (`gift_sub_base_match`, `gift_sub_bonus_match_summary`, `gift_sub_bonus_match`) are captured before they get a mapping. To capture from a channel the account does not own, use `eventsub-debug --watch-channel` ([Platform Stream Debuggers](../developer-guide/platform-stream-debuggers.md)).

There is no HTTP endpoint to expose. Lifecycle is fully managed by the worker - subscriptions are recreated on every reconnect and cleaned up when the channel connection is removed.

## YouTube (PubSubHubbub)

YouTube uses Google's PubSubHubbub (WebSub) hub at `https://pubsubhubbub.appspot.com` to push Atom XML feed updates.

**Endpoints**
- `GET https://api.lumio.vision/v1/webhooks/youtube` - subscription verification. The hub sends `hub.mode`, `hub.topic`, `hub.challenge`, `hub.lease_seconds` as query params; Lumio echoes `hub.challenge` back with a `200 text/plain` response.
- `POST https://api.lumio.vision/v1/webhooks/youtube` - notifications. Body is Atom XML; the handler extracts `<yt:channelId>` and `<yt:videoId>` via `lo_youtube_api::webhook::parse_atom_notification`.

**Lifecycle - receive-only.** Only the **receiving** half of PubSubHubbub exists today. The two endpoints above answer the hub's verification challenge and accept notifications, but Lumio never subscribes itself: the hub URL (`YOUTUBE_PUBSUBHUBBUB_HUB` in `crates/lo-youtube-api/src/types.rs`) has no caller in the codebase, so nothing ever `POST`s a `hub.callback` / `hub.topic` pair. There is consequently **no lease to renew and no automatic re-subscription** - a subscription has to be registered out-of-band before these endpoints ever fire.

Nothing else depends on this path. Live-broadcast discovery and stream statistics run on InnerTube polling plus the public channel Atom feed - see [Channel Status](../developer-guide/channel-status.md).

**Events emitted.** Every notification becomes a single `youtube:subscribe` event. The raw payload preserves `channel_id`, `video_id`, `title`, `published`, `updated`. The account is resolved from `<yt:channelId>` against `channel_connections.platform_channel_id` where `platform = 'youtube'`; an unmatched channel logs a `warn!` and is acknowledged with `200`.

**Security.** The `POST` handler verifies the PubSubHubbub signature header against `webhooks.youtube_secret` (`LUMIO__WEBHOOKS__YOUTUBE_SECRET`), which must equal the `hub.secret` used at subscribe time. It accepts `X-Hub-Signature-256` (HMAC-SHA256) and falls back to `X-Hub-Signature` (HMAC-SHA1); a missing or mismatched header returns `401`. When the secret is unset, the request is rejected with `401` under the production default `webhooks.require_signatures = true`, and only accepted (with a loud warning) when `require_signatures` is explicitly set to `false` for local development.

## Kick

**Endpoint.** `POST https://api.lumio.vision/v1/webhooks/kick`, `Content-Type: application/json`.

**Signature.** Kick's official API signs webhooks **asymmetrically**: an RSA-SHA256 signature over `"{message_id}.{timestamp}.{body}"` in the `Kick-Event-Signature` header. The handler verifies it with a ±300s timestamp tolerance against Kick's public key. Kick publishes that key without authentication at `https://api.kick.com/public/v1/public-key`. It is the same for every Kick app, is not a secret, and is not shown in `kick.com/settings/developer`.

**No key setup is needed.** The API fetches the key itself, caches it in process and in Redis (24 h TTL), and refreshes it every 6 h through a leader-elected worker (`[webhooks.kick_public_key_observer]`). Details: [Kick Webhook Public Key](../developer-guide/kick-webhook-public-key.md).

- **Fail-closed.** There is no built-in fallback key. If no key can be resolved (the Kick fetch failed and Redis is empty), every delivery returns `401` under the production default `webhooks.require_signatures = true`, and the refresher logs at `ERROR` and raises a cold-boot alert. A signature that fails against a resolved key is always `401`, whatever `require_signatures` says.
- **Rotation.** When a signature fails against the fetched key, the receiver re-fetches once and re-verifies once. The reload is single-flight and runs at most once per `refetch_cooldown_secs` (at least 60 s), so forged requests cannot trigger a storm of fetches against Kick.
- **Optional pin.** `webhooks.kick_public_key` (`LUMIO__WEBHOOKS__KICK_PUBLIC_KEY`) overrides the fetched key. Leave it empty. When it is set, it always wins and there is no automatic refresh or rotation refetch. An unparseable pin rejects every delivery. If you pin, preserve the real PEM newlines, because literal `\n` characters break PEM parsing.

Kick's official webhook API does not issue an HMAC shared secret. Leave `webhooks.kick_secret` empty. It is a legacy `X-Kick-Signature` compatibility path, not the Kick OAuth Client Secret, and it is consulted only when no RSA key resolves at all. If no key resolves and `webhooks.require_signatures = false`, the endpoint accepts unsigned payloads for local development only.

**Payload shape.** Kick delivers the **bare event payload** as the request body; the event type, version and message id travel in the `Kick-Event-Type`, `Kick-Event-Version` and `Kick-Event-Message-Id` headers (there is **no** JSON envelope). Dispatch is driven by `Kick-Event-Type`.

**Response codes.** A correctly signed delivery is never answered `4xx`. Kick unsubscribes an app whose webhook keeps failing for about a day, and a retry never fixes a bad body, so a `4xx` would only put the subscription at risk.

| Case | Answer | Log | `outcome` |
|---|---|---|---|
| Signature invalid, or no key while `require_signatures = true` | `401` | `warn!` | (not counted) |
| Signed, but the body is not JSON or `Kick-Event-Type` is missing | `200` | `error!` | `parse_failed` |
| Signed JSON that does not match the documented shape of its type | `200`, payload **stored raw** without canonical fields (a `moderation.banned` payload is dropped) | `warn!` with the event type; for `chat.message.sent` and `moderation.banned` also the JSON path of the first mismatch (e.g. `banned_user.user_id`), with string values redacted | `parse_failed` |
| Event type Lumio does not handle | `200` | `warn!` | `unmapped` |
| No connected account for `broadcaster.user_id` | `200` | `warn!` | `unrouted` |
| Already stored under the same dedup key | `200` | `debug!` | `duplicate` |
| `livestream.metadata.updated` with nothing changed against the stored baseline (first observation or redelivery) — baseline recorded, no event | `200` | `debug!` | `unchanged` |
| Stored (or, for `moderation.banned`, logged) | `200` | `debug!` | `stored` |
| Database error | `500` (Kick retries) | `error!` | `error` |

Every case except the signature check is counted in `platform_webhook_deliveries_total{platform="kick", outcome}` on the internal `/metrics` (see [Metrics](../developer-guide/metrics.md)). The Kick event type is only in the log, never a label. Chat deliveries that decode have their own counter in the chat pipeline.

**Events received** (`lo_kick_api::types::event_types`, all version `1`), 10 of 10 Kick events:

| Kick event | Lumio event type |
|---|---|
| `channel.followed` | `kick:follower` |
| `channel.subscription.new` | `kick:subscribe` |
| `channel.subscription.renewal` | `kick:resub` |
| `channel.subscription.gifts` | `kick:gift` |
| `kicks.gifted` | `kick:kicks` |
| `channel.reward.redemption.updated` | `kick:reward` for the **first** delivery of a redemption `id`, `kick:reward_status` for every later one |
| `livestream.status.updated` | `kick:stream_online` when `is_live` is `true`, otherwise `kick:stream_offline` (one event, two outcomes; there is no `livestream.started`/`livestream.ended`) |
| `livestream.metadata.updated` | `kick:stream_update` |
| `chat.message.sent` | chat pipeline (`ChatBuffer` + pubsub), not the events pipeline |
| `moderation.banned` | moderation-log pipeline, with dedup and broadcast |

The user objects in `chat.message.sent` and `moderation.banned` (`sender`, `broadcaster`, `moderator`, `banned_user`) need `user_id` and `username`. Their `is_anonymous` and `is_verified` flags read `null` or a missing value as `false`, because Kick sends `null` for them in some `moderation.banned` deliveries.

Kick sends `channel.reward.redemption.updated` on every status change (`pending`, `accepted`, `rejected`), so one redemption can arrive two or three times. The receiver looks the redemption `id` up in `platform_event_logs` for the account: the first delivery is the redemption line (`kick:reward`), each later one is a status line (`kick:reward_status`). The rule holds whether or not Kick delivers `pending`.

**Canonical fields.** `lo_kick_api::normalize_event` (`crates/lo-kick-api/src/normalize.rs`) keeps the original payload **complete** in `raw` and **adds** Lumio's canonical fields at the top level, because Kick nests the acting user one level down (`follower`, `subscriber`, `gifter`, `sender`, `redeemer`). Twitch field names win; Kick-only fields get a `kick_` prefix.

| Lumio type | Added top-level fields |
|---|---|
| every event with an actor | `user_id` (**string** of `actor.user_id`), `user_login` (`actor.channel_slug`), `user_name` (`actor.username`), `avatarUrl` (`actor.profile_picture`, omitted when empty so the GraphQL avatar back-fill runs), `is_anonymous` |
| `kick:subscribe`, `kick:resub` | `cumulative_months` (from `duration`), `expires_at` |
| `kick:gift` | `giftCount` and `total` (number of `giftees`), `is_gift`, `isGift`, `giftRecipients` (giftee usernames); with exactly one giftee also `recipient_user_id`, `recipient_user_login`, `recipient_user_name`. An anonymous gifter gets `gifter_is_anonymous: true`, no `user_id`/`avatarUrl`, and the Twitch placeholder names `AnAnonymousGifter` / `ananonymousgifter` |
| `kick:kicks` | `kicks` (from `gift.amount`), `message`, `kick_gift_name`, `kick_gift_type`, `kick_gift_tier`, `kick_pinned_time_seconds`; when `gift.name` matches the static gift table `lo_kick_api::kicks_gifts` (case-insensitive) also `kick_gift_id`, `kick_gift_image{static, animated}` (`animated` is `null` for BASIC gifts) and `kick_gift_color`. An unknown gift adds none of the three. See [Events → KICKs gift graphics](./events.md#kick-payloads-raw) |
| `kick:reward`, `kick:reward_status` | the Twitch reward shape: `id`, `status`, `user_input`, `redeemed_at`, `reward{id, title, cost, prompt}` (`prompt` copied from Kick's `description`) |
| `kick:stream_update` | `title`, `category_id` (string), `category_name`, `language`, `has_mature_content`, plus `title_changed` / `category_changed` / `language_changed` (see *Live status* below) and, like Twitch, `old_title` / `old_category_name` / `old_language` for a field that changed |
| `kick:stream_online` | none (the payload's `title`, `started_at`, `ended_at` are already top level) |
| `kick:stream_offline` | `duration_seconds` = Kick's `ended_at` − `started_at` (whole seconds; time of receipt when `ended_at` is missing). Kick's own `started_at` is kept; when it is missing or Kick's zero timestamp, the start captured in `channel_status` is added as `started_at` instead. Unknown start or a negative duration adds neither field. Added at ingest, before the event is stored and before the status below clears the start. See [Events → Stream offline payloads](./events.md#stream-offline-payloads-stream_offline) |

**Live status.** The two livestream events also drive Kick's live status, through the same `channel_status` service as Twitch (`apps/api/src/services/kick_live_status.rs`), after the event is stored:

| Stored event | Effect |
|---|---|
| `kick:stream_online` | `set_online(…, "kick")` with `broadcast_id` = `started_at` normalised to UTC seconds (`default` when missing) and the webhook `title`. A redelivery for the same stream is a no-op; a different stream first closes the old one. Opens the stream-history session, publishes the status that the relay turns into the WebSocket `channel:online`, and starts the Spotify worker. |
| `kick:stream_offline` | `set_offline(…, "kick")`: ends the Kick stream row, WebSocket `channel:offline`. |
| `kick:stream_update` | While Kick is online: `update_stream_data` with the new title/category (WebSocket status update, live card). While offline it changes nothing but the stored event. `title_changed` / `category_changed` / `language_changed` are computed at ingest against the stored metadata baseline (`platform_channel_metadata`), because Kick sends the new state without a diff — online **and** offline. The first observation (no baseline) records it and stores **no** event; an update where nothing changed is not stored either (outcome `unchanged`). The baseline advances only once the event is stored, so a failed insert (`500`, Kick retries) still reports the change on the retry. See [Events → Stream update payloads](./events.md#stream-update-payloads-twitchstream_update-kickstream_update). |

A failure here is logged and never changes the delivery answer: the status is corrected by two API-side checks (`apps/api/src/workers/kick_live_status.rs`), both on `GET /public/v1/channels?broadcaster_user_id=…` with the connection's token (`stream.is_live`, `stream.viewer_count`, `stream.start_time`, channel-level `stream_title` and `category`; the stream `key` in that response is never read):

- **Start reconcile** — whenever the Kick worker starts (API start, channel connect): sets online when Kick says live, clears a stale online status when it does not.
- **60-s poll while live** — one call per live Kick channel per minute, none for offline channels: viewer count, title and category via `update_stream_data`. Two consecutive "not live" answers set the channel offline; a single one changes nothing. A failed call (429, 5xx, token) skips the tick.

Neither check writes a feed event — only the webhook stores `kick:stream_online` / `kick:stream_offline`. See [Channel Status](../user-guide/channel-status.md).

**Deduplication.** `external_id` is the `Kick-Event-Message-Id` header. A delivery without that header is keyed by `sha256(event_type + body)` (lowercase hex), so a byte-identical redelivery is still dropped as a duplicate.

Account resolution is by the payload's `broadcaster.user_id` against `channel_connections.platform_channel_id` where `platform = 'kick'` (there is no envelope `channel_id`). That id is captured from Kick's `GET /public/v1/channels` at connect time (and backfilled at startup for older rows), so it is never left `NULL`. When no connection matches, the chat, moderation and event paths all log a `warn!` and drop the payload (still acknowledging with `200`) instead of dropping it silently.

**Subscription.** Connecting a Kick channel (and every API start) spawns `run_kick_webhook_worker` (`apps/api/src/workers/kick.rs`), which pulls a fresh access token for that `channel_connections` row via `get_fresh_connection_token` (never refreshing inline), reads the account's existing subscriptions (`GET /public/v1/events/subscriptions`), subscribes to any missing event in **one** call (`POST /public/v1/events/subscriptions` with body `{events:[{name,version:1}], method:"webhook"}` — all events in a single request; `broadcaster_user_id` is inferred from the user token and omitted), inspects each per-event `data[].error` (a `200` does not mean every event subscribed), deletes any subscription for an event Lumio no longer wants, then exits. Reading before writing makes re-runs a no-op, so it never creates duplicate subscriptions. Kick returns **no** per-subscription secret — deliveries are verified with the configured RSA public key.

> **Manual step — the callback URL is app configuration, not an API field:**
> Kick has **no API** to set where deliveries are POSTed. The webhook URL and the "Enable Webhooks" toggle are configured **by hand** at **kick.com/settings/developer → Edit app → "Enable Webhooks" + "Webhook URL"**. The worker logs the value to configure (`{server.public_url}/v1/webhooks/kick`) once at start, but an operator must paste that exact URL into the Kick app or **no delivery ever arrives**. Because the URL is per-app, **one Kick app serves one environment**.

Registered event types (`KICK_WEBHOOK_EVENTS`), all 10 Kick events: `chat.message.sent`, `channel.followed`, `channel.subscription.new`, `channel.subscription.renewal`, `channel.subscription.gifts`, `kicks.gifted`, `channel.reward.redemption.updated`, `livestream.status.updated`, `livestream.metadata.updated`, `moderation.banned`. A unit test checks that every name in `VALID_EVENT_NAMES` is subscribed and that every one except chat and moderation maps to a stored Lumio type. The gift subscription is registered — and mapped by `map_event_type` — under the single canonical name `channel.subscription.gifts` (the plural form Kick actually delivers). Every registered name is validated against `lo_kick_api::types::VALID_EVENT_NAMES` by a unit test, so a non-existent name (like the old `livestream.started`/`livestream.ended`) cannot silently ship again.


## Shopify

**Endpoint.** `POST https://api.lumio.vision/v1/webhooks/shopify`.

**Headers required:**
- `X-Shopify-Topic` - e.g. `orders/create`, `orders/paid`, `products/create`, `app/uninstalled`, or a compliance topic.
- `X-Shopify-Shop-Domain` - the `*.myshopify.com` domain.
- `X-Shopify-Hmac-SHA256` - base64-encoded HMAC-SHA256 of the raw body.
- `X-Shopify-Webhook-Id` - the delivery id (the same on every redelivery); used as the idempotency key of the `app/uninstalled` tombstone and of a compliance request.

**Signature.** One secret for every shop: Lumio is one public Shopify app, and Shopify signs each delivery with the app's client secret (`[shopify] client_secret`, `LUMIO__SHOPIFY__CLIENT_SECRET`). `services::integration_secrets::verify_shopify_webhook` checks it with `lo_shopify::webhook::verify_hmac_any` (constant-time) **before** the shop is resolved to a tenant; a mismatch returns `401`. During a client-secret rotation Shopify keeps signing with the old secret, so the check also accepts `[shopify] client_secret_previous` (`LUMIO__SHOPIFY__CLIENT_SECRET_PREVIOUS`) while it is set; `shopify_client_secret_matches_total{verifier="webhook", secret}` counts which one matched. See [Shopify → Client-secret rotation](./shopify.md#client-secret-rotation).

**Fail-closed on a missing secret.** Like the other platform endpoints, Shopify honours `webhooks.require_signatures`. With no `client_secret` configured and the production default `require_signatures = true`, every delivery is rejected with `401`; the check is skipped only when `require_signatures` is explicitly `false` for local development (with a loud warning).

**Tenant lookup is exact.** After the signature check, the header must be a plain `{store}.myshopify.com` host (`400` otherwise) and resolves through the indexed `integration_configs.shop_host` column by exact equality (`db::shopify::find_by_shop_host`). Each shop belongs to at most one account (partial unique index, see [Shopify](./shopify.md#one-shop-one-account)). Order and product deliveries need an **enabled** integration; a shop with no enabled integration answers `200` and is dropped.

**`app/uninstalled`.** Shopify has already revoked the token. The handler deletes the shop's row (whether or not it is enabled) and writes the `app/uninstalled` tombstone into `shopify_compliance_requests` in one transaction, then emits `account:integration_disconnected` with no actor (`reason: app_uninstalled`). A redelivery finds nothing and writes nothing.

**Events mapped** (`lo_shopify::types::event_topics` → Lumio type):
- `orders/create` → `shopify:order`
- `orders/paid` → `shopify:order_paid`
- `products/create` → `shopify:product`

Any other topic returns `200` and is dropped silently. The event `external_id` is namespaced per topic - `order:{id}`, `order_paid:{id}`, `product:{id}` - because the event dedup key has no type: with the bare order id, `orders/paid` was always dropped as a duplicate of `orders/create`. A redelivery keeps its id, so dedup still holds per topic. Parsing lives in `lo_shopify::webhook::parse_order_webhook` and `parse_product_webhook`.

**What an order event stores.** `orders/create` and `orders/paid` store and broadcast `order_number`, `name` (e.g. `#1001`) and `financial_status`, plus the order details the store's settings switch on at the time the order arrives (see [Shopify → Order details](./shopify.md#order-details)): with `show_items` (default on) `line_items` (`title`, `quantity`), with `show_price` (default off) `total_price` and `currency` and, when items are shown, each item's `price`. A switched-off detail is absent, not `null`, so it never reaches a WebSocket client, a widget, an automation (`{{event.raw.total_price}}` exists only while `show_price` is on) or the events API. The customer appears only as `customer_display`: the reduced label in the form chosen in the integration's `customer_display` setting (`Alex`, `A.` or `Alex M.`, or a sanitized typed name under `custom_name`), only with the buyer's consent record on the order, and the key is absent with the default `none`, without consent, or when the order has no customer first name (see [Integrations → Shopify customer label](./integrations.md#shopify-customer-label-customer_display)). The customer's full name, email, phone, addresses, customer ID, order notes, `note_attributes` and browser IP are never stored, broadcast or logged; `lo_shopify::Order` does not even parse them (of `note_attributes` it keeps only `__lumio_name_consent` and `__lumio_stream_name`, as input to the label). A payload that fails to parse is logged with its error category and position only, never with a value from the payload.

**Unlinked stores.** The webhook subscriptions are app-level, so every store that has the app installed sends its orders, linked or not. The signature is checked first; a store without a linked account is answered `200`, and nothing is stored or logged about the delivery.

### Shopify compliance topics

**Endpoint.** `POST https://api.lumio.vision/v1/webhooks/shopify/compliance`, configured on the app as the `compliance_topics` URI. A compliance topic that reaches `/v1/webhooks/shopify` is queued the same way.

**Topics.** `customers/data_request`, `customers/redact`, `shop/redact`. Any other topic on the compliance endpoint is `400`.

**Receipt.** Same headers and the same app-secret signature check as above, before anything else: an invalid or missing `hmac` is `401`, as Shopify requires. Then the payload's order ids are read (`orders_to_redact` / `orders_requested`; the `customer` object is skipped by the parser and never stored), the store resolves to its account by `shop_host` whether or not the integration is enabled, and one row goes into `shopify_compliance_requests` (`ON CONFLICT (webhook_id) DO NOTHING`). The answer is `200` (also for a redelivery and for an unknown store), `400` for a body of the wrong shape, `500` when the queue cannot be written (Shopify redelivers). The work runs later in the compliance worker; see [Shopify → Compliance webhooks](./shopify.md#compliance-webhooks).

## Stripe

**Endpoint.** `POST https://api.lumio.vision/v1/webhooks/stripe` (wired in `routes/billing.rs`, not `routes/webhooks.rs`).

**Signature.** `Stripe-Signature` header (format `t=<timestamp>,v1=<hex>`), verified against `config.stripe.webhook_secret` (`LUMIO__STRIPE__WEBHOOK_SECRET`) by the in-file `verify_stripe_signature` helper. Verification **fails closed on an empty secret**, enforces a **±300s timestamp tolerance** (replay protection), and compares the signature in **constant time** via the MAC's own verifier - matching the Stripe-Connect twin in `routes/webhooks_payments.rs`. A stale, forged, or unsigned request returns `401`.

**Events handled:**
- `checkout.session.completed` - finalises the account/plan binding (creates an account for new signups or upgrades an existing one via `metadata.account_id` / `metadata.user_id`).
- `customer.subscription.updated` - updates the plan on an account and refreshes `current_period_end`.
- `customer.subscription.deleted` - downgrades to the `free` plan.
- `invoice.payment_failed` - logged for now.

All other Stripe event types are acknowledged with `200` and ignored. Feature-flag caches are invalidated on every plan change.

## Stripe Connect & PayPal Payouts (extension marketplace)

Two additional money-moving webhooks power the extension marketplace and developer payouts (wired in `routes/webhooks_payments.rs`):

| Endpoint | Verification |
|----------|--------------|
| `POST /v1/webhooks/stripe-connect` | `Stripe-Signature` HMAC-SHA256 over the **raw body**, verified against `payments.stripe_connect_webhook_secret`. Enforces a ±300s timestamp tolerance (replay protection) and a constant-time signature comparison. |
| `POST /v1/webhooks/paypal-payouts` | PayPal's asymmetric scheme, verified server-side by forwarding the `PAYPAL-TRANSMISSION-*` / `PAYPAL-CERT-URL` / `PAYPAL-AUTH-ALGO` headers and the raw event to PayPal's `/v1/notifications/verify-webhook-signature` API. Requires `payments.paypal_webhook_id`; the `cert_url` host must be `paypal.com` or a subdomain. |

Neither endpoint carries a `utoipa::path` annotation, so they do not appear in `apps/api/openapi.json`.

**Stripe Connect events handled:** `checkout.session.completed` (extension purchase), `charge.refunded`, `transfer.paid` (legacy: Stripe no longer sends it; the payout cycle marks a Stripe payout completed when the transfer is created), `customer.subscription.created`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_succeeded`, `invoice.payment_failed`, `account.updated`. Anything else is logged at `debug!` and acknowledged.

`checkout.session.completed` records one `extension_purchases` row per Checkout Session: the session id (`cs_…`) is the idempotency key, so a redelivered event neither inserts a second row nor credits the developer twice, also after a refund. `stripe_payment_id` holds the PaymentIntent for one-time purchases and is `null` for subscription checkouts, which have none. A Checkout Session stays open for up to 24 hours; if the extension or its version is deleted or unpublished in that window, the captured payment is still recorded, with `extension_id` and/or `version_id` set to `null` for what no longer exists. Nothing is installed. The same holds when the account can no longer install the extension (for example, a private access grant was revoked after checkout).

**Automatic refund.** Both cases are refunded in full in the same webhook pass, after the purchase and the withdrawal-waiver proof are stored:

- **One-time purchase (`mode=payment`):** `POST /v1/refunds` on the session's PaymentIntent, `reason=requested_by_customer`, `metadata[purchase_id]` and `metadata[cause]` (`detached` for a deleted or unpublished extension or version, `not_installable` for lost access).
- **Subscription (`mode=subscription`):** the subscription is cancelled at once, without proration. The PaymentIntent of its first invoice is then written onto the purchase row, and that PaymentIntent is refunded with the same fields.

Every refund call carries `Idempotency-Key: refund:<checkout session id>`, so a redelivered event cannot refund twice. A purchase that is no longer `completed` is skipped. The webhook does not change the ledger itself. The refund triggers `charge.refunded`, and that handler marks the purchase `refunded` and debits the developer's balance, also when the extension no longer exists (`extension_id` is `null`). A successful refund is recorded as the `extension:purchase_auto_refunded` audit event. If Stripe refuses the refund or cannot be reached, the API logs an error and still answers `200`, because the payment is already recorded and a `500` would make Stripe redeliver the event for days. The purchase then stays `completed`. A payment that could not be installed because of a temporary error is not refunded automatically. Both kinds stay on the admin list [payment without delivery](../admin/extension-purchases.md) until someone refunds or installs them.

**Delivery record.** Every purchase records whether it was delivered: `delivered_at` is set when the extension is installed for the buying account, at checkout or by any later install. A purchase that was not delivered keeps `delivered_at` empty and records why in `undelivered_reason` (`detached`, `not_installable`, `install_failed`, or `refund_failed` once an automatic refund failed). Later uninstalls, deleting the extension or deleting the account do not change a delivered purchase.

**Buyer notice.** Stripe sends its own refund receipt only when e-mail receipts are enabled in the Stripe Dashboard, so once Stripe has accepted an automatic refund, Lumio mails the purchasing user (`metadata.user_id` of the session) in German or English, by the user's resolved e-mail language. The mail names the extension (`extensions.name`; for a deleted extension, the description of the session's Stripe line item), says that it was no longer available when the checkout completed and that the full amount was refunded, shows the amount and the Stripe refund id, and says that the credit appears within 5–10 business days depending on the bank. The mail is sent in the background: the refund never waits for or depends on it, and a failed send is only logged. A session without a buyer, or a buyer without an e-mail address, gets no mail. When Stripe replays an earlier refund response for a redelivered event (`Idempotent-Replayed: true`), no second mail is sent.

`charge.refunded` matches the purchase by its PaymentIntent, marks it `refunded` and debits the developer's balance. A refund issued in the Stripe Dashboard takes the same path. A PaymentIntent that paid no purchase is matched to a renewal invoice (by the PaymentIntent stored on the invoice, otherwise by asking Stripe which invoice it paid). The invoice is marked `refunded`, and the developer that invoice credited is debited. Refunding one renewal does not end access: access follows the subscription.

**Extension subscriptions.** The Checkout Session of a subscription records the `sub_…` id on the purchase and puts `extension_id` and `account_id` into the subscription's metadata, which Stripe copies onto every invoice.

- `invoice.payment_succeeded` with `billing_reason = subscription_create` is invoice #1. The checkout already credited it, so it writes no invoice row and credits nothing. It only stores its PaymentIntent on the purchase, so a refund of invoice #1 from the Stripe Dashboard finds the purchase; if the PaymentIntent cannot be resolved, the API answers `500` and Stripe redelivers. When this event arrives before `checkout.session.completed`, the API answers `500` and Stripe redelivers it.
- Every later paid invoice is recorded once in `extension_subscription_invoices` (keyed on the `in_…` id, so a redelivered event credits nothing). The developer is credited at their current revenue split, the same way as at checkout: a changed split applies from the next renewal on. Both `revenue_balance` and `total_earned` rise. A purchase whose extension or developer no longer exists records the invoice and credits nobody. A database error answers `500`, so Stripe redelivers the event.
- `customer.subscription.created` / `.updated` store Stripe's subscription `status` (`active`, `past_due`, `unpaid`, …), the cancel flag and the period end on the purchase. Stripe does not deliver events in order, so an event older than the last one applied changes nothing.
- `invoice.payment_failed` is only logged. The `customer.subscription.updated` (`past_due`) that Stripe sends with it carries the state. Access continues while Stripe retries the payment.
- `customer.subscription.deleted` ends the subscription (`subscription_ended_at`, status `canceled`). Access ends with it.
- Both shapes of the Stripe API are read: the subscription of an invoice sits at `parent.subscription_details.subscription` since `2025-03-31.basil` and at `subscription` before.

Renewal invoices are booking records with the same 8-year retention as purchases. They are deleted first, and a purchase is kept while it still has invoices. Their revenue moves into the per-extension rollup, so developer totals do not shrink.

**Payouts of a deleted developer.** A payout row outlives the developer profile (`developer_id` becomes `null`, see [data design](../developer-guide/data-design.md#4-retention-per-data-class)). A profile cannot be deleted while one of its payouts is `pending` or `processing`, so the webhooks normally find an attached row. They look payouts up by transfer or batch id, not by developer, so a detached row is still marked `completed`. When a PayPal item fails for a detached row, nobody can be credited: the row is marked `failed`, the money stays with Lumio, and the API logs a warning with the payout id.

**PayPal Payouts events handled:** `PAYMENT.PAYOUTS-ITEM.SUCCEEDED`, `PAYMENT.PAYOUTS-ITEM.FAILED`, `PAYMENT.PAYOUTS-ITEM.UNCLAIMED`, `PAYMENT.PAYOUTSBATCH.SUCCESS`. Anything else is logged at `debug!` and acknowledged.

**Fail-closed by default.** If the corresponding secret / webhook id is **not** configured, both endpoints reject every request. The only way to accept unsigned payloads is the explicit dev-only escape hatch `payments.allow_unsigned_webhooks = true` - never enable it in production. A missing secret in production therefore causes rejection, not silent acceptance.

## Registering subscriptions

There is no public "register a webhook" Lumio endpoint. Subscriptions are created in one of four ways:

1. **Automatic, at connection time and every API start - Kick only.** When a user connects a Kick channel via `apps/api/src/routes/connections.rs` (and for every active connection at API start), a short-lived Kick worker (`apps/api/src/workers/kick.rs`) reconciles the account's event subscriptions against Kick's Events API (`GET`/`POST`/`DELETE /public/v1/events/subscriptions`) using a fresh channel token, then exits. Kick returns no per-subscription secret. **The delivery callback URL is not an API field** — it must be set by hand in the Kick developer dashboard (see the Kick section above); the worker only logs the value (`{public_url}/v1/webhooks/kick`) to configure.
2. **Automatic, at worker startup - Twitch.** The Twitch EventSub worker registers all `subscription_types::ALL` on every new session. A Twitch `session_reconnect` hands the subscriptions over and needs no new registration. This is a WebSocket transport, not an HTTP webhook.
3. **App configuration - Shopify.** The subscriptions (`orders/create`, `orders/paid`, `products/create`, `app/uninstalled` at `{server.public_url}/v1/webhooks/shopify`, plus the compliance topics) are app-level, declared in `apps/shopify/shopify.app.<env>.toml` and deployed with the app. Every store that installs the app sends them; a store that is not [linked](./shopify.md#install-and-link) to a Lumio account is dropped on arrival (`200`, nothing stored), also after a disconnect in Lumio.
4. **Admin-controlled for Stripe.** Configured in the Stripe dashboard (Developers → Webhooks). The callback URL is `https://api.lumio.vision/v1/webhooks/stripe` and the signing secret lives in the Lumio TOML config.

**YouTube has no registration path at all.** Its receiver endpoint exists and is signature-verified, but nothing in the codebase subscribes it - connecting a YouTube channel starts a polling worker instead. A subscription has to be registered out-of-band.

## Configuration / env vars

| Key | TOML path | Env var | Used by |
|-----|-----------|---------|---------|
| Require signatures (gate) | `webhooks.require_signatures` | `LUMIO__WEBHOOKS__REQUIRE_SIGNATURES` | All three platform endpoints |
| YouTube `hub.secret` | `webhooks.youtube_secret` | `LUMIO__WEBHOOKS__YOUTUBE_SECRET` | YouTube endpoint |
| Optional pin for Kick's public RSA PEM key (empty by default: the key is fetched automatically) | `webhooks.kick_public_key` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY` | Kick endpoint |
| Kick key refresher (interval, cooldown, URL, cold-boot alert) | `webhooks.kick_public_key_observer.*` | `LUMIO__WEBHOOKS__KICK_PUBLIC_KEY_OBSERVER__*` | Kick endpoint. See [Kick Webhook Public Key](../developer-guide/kick-webhook-public-key.md#configuration) |
| Legacy HMAC compatibility secret (Kick does not issue one; leave empty; not the OAuth Client Secret) | `webhooks.kick_secret` | `LUMIO__WEBHOOKS__KICK_SECRET` | Used only when no Kick public key resolves |
| Stripe webhook secret | `stripe.webhook_secret` | `LUMIO__STRIPE__WEBHOOK_SECRET` | Stripe endpoint |
| Shopify app client secret | `shopify.client_secret` | `LUMIO__SHOPIFY__CLIENT_SECRET` | Shopify webhooks, ID tokens and token exchange |
| Stripe Connect webhook secret | `payments.stripe_connect_webhook_secret` | `LUMIO__PAYMENTS__STRIPE_CONNECT_WEBHOOK_SECRET` | `stripe-connect` endpoint |
| PayPal webhook id | `payments.paypal_webhook_id` | `LUMIO__PAYMENTS__PAYPAL_WEBHOOK_ID` | `paypal-payouts` endpoint |
| Accept unsigned payment webhooks (dev only) | `payments.allow_unsigned_webhooks` | `LUMIO__PAYMENTS__ALLOW_UNSIGNED_WEBHOOKS` | both payment endpoints |

`webhooks.require_signatures` defaults to `true` and gates the YouTube, Kick and Shopify endpoints: with it on, an unset YouTube secret, a Kick public key that cannot be resolved (no pin, fetch failed, Redis empty), or an unset Shopify app client secret means requests are rejected with `401` (see the Shopify section). Twitch uses the Helix OAuth tokens from `channel_connections` + `app_credentials`; no webhook secret is involved.

## Permissions

Webhook handlers bypass Lumio's JWT/API-key auth and therefore bypass RBAC - they are trust-boundary protected by signature verification only. Once a payload is verified, the handler resolves the target `account_id` from the signed payload (`channel_id`, `shop_domain`, or Stripe customer/metadata) and writes events under that account. There is no `webhooks:*` permission.

## Troubleshooting

- **`401 Unauthorized` on YouTube / Kick / Shopify / Stripe** - signature mismatch, or (for YouTube / Kick / Shopify) no verification value configured while `webhooks.require_signatures = true`. Shopify uses the app client secret, shared by all stores, for its HMAC; check that the configured secret matches the Shopify app. For Kick, fetch the current public key from `https://api.kick.com/public/v1/public-key`, preserve PEM newlines, and check clock skew: the RSA path rejects a `Kick-Event-Message-Timestamp` more than 300 s from server time. For HMAC-based providers, confirm the configured secret and ensure the reverse proxy does not rewrite the raw body.
- **`400 Bad Request` on YouTube** - Atom XML failed to parse or did not contain `<yt:channelId>`. Check that the topic URL you used when subscribing matches the channel you expect notifications for.
- **Events not arriving in the dashboard** - the endpoint may be returning `200` silently when no matching `channel_connections` row is found (see `warn!("No account found for {platform} channel")` log lines). Verify the channel is connected and that `platform_channel_id` matches exactly.
- **Duplicate events** - the event pipeline deduplicates by `external_id` (Kick `Kick-Event-Message-Id`, or `sha256(event_type + body)` when that header is missing; YouTube `video_id`; Shopify `order:{id}`, `order_paid:{id}` or `product:{id}`). Duplicates are logged at `debug!` and silently acknowledged with `200`.
- **Dead PubSubHubbub subscriptions** - YouTube leases expire (typically ≤10 days) and Lumio has no resubscription path, so a lapsed lease stays lapsed until someone re-registers it out-of-band. Reconnecting the YouTube channel does **not** resubscribe. Live-broadcast discovery and stream statistics do not depend on this - they run on InnerTube polling plus the public channel Atom feed.
- **Replay attacks** - the handlers do not currently pin a max clock skew on the Stripe `t=` timestamp or reject duplicate `event_id`s at the HTTP layer. Stripe's own dedup (idempotent event IDs) and the event pipeline's `external_id` unique index absorb replays in practice, but treat this as defence-in-depth only.

## Related

- Three-protocol architecture: [API Reference → REST](/api-reference/rest-api), [GraphQL](/api-reference/graphql), [WebSocket](/api-reference/websocket)
- [Events feature](/features/events) - how inbound events are normalised and broadcast once a webhook has been processed.
- [Token Refresh](/features/token-refresh) - how the OAuth tokens that back webhook subscriptions are kept fresh.

---

## Features / Ideas Hub

Source: https://docs.lumio.vision/features/ideas-hub

# Ideas Hub

## Overview

The Ideas Hub is a community-facing feature request and feedback system built into Lumio. It serves as a global (not account-scoped) space where users can submit ideas, vote on existing ones, leave comments, and track progress through status changes. The hub is accessible both from the authenticated dashboard (`/hub/ideas`) and from the public marketing route (`/ideas`) when the `system:ideas_hub_public` feature flag is enabled.

Ideas Hub permissions are **user-scoped**, not account-scoped: they come from the user's global role (`user_roles` / `user_role_permissions`), so switching accounts does not change what a user may do in the hub.

## Feature Flags

| Flag | Category | Effect |
|------|----------|--------|
| `system:ideas_hub` | `system` | Master kill-switch. Every GraphQL resolver and REST handler calls a flag check first; when the flag is off, GraphQL returns `"Ideas Hub is disabled"` and REST returns `404`. The dashboard route group is wrapped in `FeatureRouteGate`, and the WebSocket `ideas` channel family is gated on it via `channel_feature_for`. |
| `system:ideas_hub_public` | `system` | The public kill-switch, enforced **server-side on all three protocols** (not only in the web UI). Required - in addition to `system:ideas_hub` - for every **anonymous** read on REST, GraphQL, and the WebSocket `ideas` channel, plus the public marketing pages at `/ideas` and the Atom feed at `/ideas/feed.xml` (which `notFound()` when either flag is off). Authenticated dashboard users reach reads on the master flag alone. Submission, voting, and commenting still require authentication. |

Both flags are seeded by migration `20260506000012_seed_ideas_feature_flags` with `enabled = true` and `default_for_accounts = true`. They are infrastructure-category (`system`) flags, so they carry no `plan_features` rows and never appear on pricing cards.

## Architecture

### Backend

- **GraphQL** (`apps/api/src/graphql/ideas.rs`) - queries and mutations for ideas, comments, votes, voters, tags, categories, and timeline. There are no Ideas Hub GraphQL subscriptions; live updates are published to the WebSocket gateway instead.
- **REST** (`apps/api/src/routes/ideas.rs`) - mirrors the GraphQL operations under `/v1/ideas`. Admin operations live on the same prefix (for example `/v1/ideas/categories`), not under a separate `/v1/ideas/admin` namespace.
- **Database** - all tables stored in PostgreSQL; see [Database](#database) below.
- **WebSocket** - real-time updates via `ideas:{id}` (single idea) and `ideas:list` (index) channels; see [WebSocket Channels](#websocket-channels).
- **Atom feed** - a public feed at `/ideas/feed.xml` served by the web app; see [Atom Feed](#atom-feed).

### Frontend

```
Browser
  |-- Dashboard (/hub/ideas)     → Next.js SSR + proxy routes → Rust GraphQL
  |-- Public site (/ideas)       → Next.js SSR (marketing)    → Rust GraphQL (public resolvers)
  |-- Atom feed (/ideas/feed.xml)→ Next.js route handler      → Rust GraphQL (serverGqlSSR)
  |-- Admin (/hub/ideas)         → Next.js admin app          → Rust GraphQL / REST
```

Client-side code calls the catch-all Next.js proxy route `apps/web/src/app/api/ideas/[[...path]]/route.ts`. SSR pages use `serverGqlSSR()` directly.

Submitting and editing an idea share one component - `apps/web/src/app/(main)/(app)/hub/ideas/idea-wizard.tsx`, a three-step `FullscreenWizard` (`@lumio/ui`) switched between create and edit by its `editing` prop. Create is embedded in the index (`/hub/ideas`); edit renders it on its own route (`/hub/ideas/{id}/edit`). A failed submission surfaces the error both as a toast and as an inline banner in the wizard rather than silently leaving the form open.

## Idea Lifecycle

### Status Values

Ideas move through a fixed allowlist of statuses. Changing the status requires `ideas:moderate_status` (held either as a user-role permission or as an admin-role permission). Any value outside the allowlist is rejected with `"Invalid status"`.

| Status | Description |
|--------|-------------|
| `open` | Default status on creation. Visible and accepting votes. |
| `planned` | Acknowledged by the team; on the roadmap. |
| `in_progress` | Actively being worked on. |
| `testing` | Feature built, being tested before release. |
| `completed` | Feature shipped. |
| `closed` | Declined or withdrawn. |

Every status change appends a `status_changed` timeline entry carrying the previous and new status. The status-change operation takes no free-text message.

### Voting

- Each authenticated user with `ideas:vote` can cast one vote per idea. `idea_votes` is keyed on `(idea_id, user_id)`, so a second vote replaces the first.
- The vote value is `up` or `down` (column `vote_type`). Any other value is rejected with `vote_type must be "up" or "down"`.
- Vote counts (`vote_count_up`, `vote_count_down`) are denormalized integer columns on the `ideas` table for fast reads.
- Casting, changing, or removing a vote upserts/deletes the `idea_votes` row and then runs `recount_votes`, which recomputes both counters from `idea_votes`.
- The current user's vote is returned alongside every idea as `myVote` (GraphQL) / `my_vote` (REST) so the UI can show the active state. It is `null` for anonymous readers.

### Comments

- Comments support unlimited nesting via a `parent_id` self-referencing foreign key. Deleting a comment that has replies keeps the replies (see [Deletion and tombstones](#deletion-and-tombstones)).
- Both GraphQL and REST assemble the flat DB result into a `replies` tree in memory before returning - there is no flat-list variant. The flat read is capped at the oldest **500** comments per idea (`MAX_IDEA_COMMENTS`) so the anonymous read stays bounded, and all comment authors are resolved in one batched query rather than one per comment.
- Comment bodies are HTML, sanitized server-side with `lo_common::sanitize_html` (ammonia). Bodies larger than 10 000 bytes are rejected.
- Editing a comment requires `ideas:comment_edit` **and** ownership. Deleting requires `ideas:comment_delete` on your own comment, or `ideas:moderate_comment` for anyone else's.
- Deletion follows [Deletion and tombstones](#deletion-and-tombstones). `comment_count` is recounted after every delete and counts live comments only, not tombstones.
- Comments and replies can be voted on with `ideas:comment_vote`, mirroring idea voting exactly. `idea_comment_votes` is keyed on `(comment_id, user_id)` (`ON DELETE CASCADE`), so a second vote replaces the first and re-voting the active direction removes it (toggle-off). Counts (`vote_count_up`, `vote_count_down`) are denormalized columns on `idea_comments`, recomputed by `recount_comment_votes` after every mutation. Each comment carries the caller's `myVote` / `my_vote` in the comment tree, `null` for anonymous readers.

### Deletion and tombstones

Deleting a post never takes other people's posts with it. The rules live in `db::ideas` (`delete_idea`, `delete_comment`, `remove_user_content`) and run identically for GraphQL, REST and profile deletion:

- **Comment** (author or moderator): with replies, it becomes a **tombstone** - the row stays so the thread keeps its shape, while its `body`, its author link and its own votes go. Without replies it is deleted outright. Replies to a tombstoned comment are still allowed.
- **Idea** (author or moderator): with comments by anyone other than its author, it becomes a tombstone - `title` and `description` are emptied, the author link, its votes, tag assignments and timeline go, and the other people's comments stay. The author's own comments under it are deleted, except those someone else replied to, which become tombstones. Without comments by others the idea is deleted outright with everything under it.
- **Profile deletion** (`db::admin::delete_user_rows`): the person's ideas and comments follow the same two rules in the same transaction, their idea and comment votes go, and every counter they fed is recounted.
- A tombstone that loses its last reply (or an idea tombstone its last comment) is deleted as well, so tombstones never outlive the content they hold up.
- A database CHECK constraint guarantees that a tombstone carries no author and no text.

A tombstone reads as `deleted: true` with `author: null` and an empty `title`/`description` (idea) or `body` (comment) on every read path, for every caller: `ideas`/`GET /v1/ideas` (including search and the admin list), `idea`/`GET /v1/ideas/{id}`, `ideaComments`/`GET /v1/ideas/{id}/comments`. Its voter list and timeline are empty. Live ideas and comments carry `deleted: false`. Writes to a tombstone are refused with the same message on both protocols: `Idea was deleted` for editing, voting on, commenting on or changing the status of an idea tombstone, `Comment was deleted` for editing or voting on a comment tombstone (`409 CONFLICT` on REST). Since a tombstone has no author, only a moderator can delete it, and it stays while replies hang off it. The delete mutations keep their result (`true` / `{ "ok": true }`); refetch to see whether the post was removed or became a tombstone.

### @Mentions

Comments support @mentioning other users who have interacted with the idea (the idea author, voters, and previous commenters).

**Frontend:**

- The comment editor is the shared `RichTextEditor` component, built on [Tiptap](https://tiptap.dev) with the Mention extension. The mention node and its suggestion popup live in `apps/web/src/components/rich-text-editor-mention.ts`, covered by `apps/web/__tests__/components/rich-text-editor-mention.test.tsx`.
- Typing `@` triggers an autocomplete dropdown backed by the participants endpoint (`ideaParticipants(ideaId, search)`). The participant list requires a signed-in user session or personal API key; embed and popout tokens cannot read it.
- ProseMirror must resolve to a **single copy** of `prosemirror-model` and `prosemirror-view`. Tiptap builds the mention `Fragment` with `@tiptap/pm/model` and hands it to `prosemirror-transform`; if the two load different copies, the `instanceof` check fails and inserting a mention throws `RangeError: Can not convert <mention, " "> to a Fragment` inside the click handler - the dropdown appears but selecting an entry does nothing. The root `package.json` pins both through `pnpm.overrides`; keep those pins in step with `@tiptap/pm` when bumping Tiptap.
- Inserted mentions are stored in comment HTML as `<span data-type="mention" data-id="UUID" data-label="Name" data-mention-id="UUID" class="mention">@Name</span>`. `data-type`/`data-id`/`data-label` are Tiptap's canonical mention attributes - the Mention extension's `parseHTML()` only re-parses `span[data-type="mention"]` and recovers the id/label from `data-id`/`data-label`. Emitting only `data-mention-id` (the original markup) meant re-loading a saved comment into the editor - e.g. when **editing** it - degraded every mention back to plain text and dropped the id, so the mention lost its styling, its link, and could no longer be resolved (ZAF-531). `data-mention-id` is retained alongside them for the backend regex extraction.
- Both sanitizers must allow all five attributes for the markup to survive the save round-trip: the client-side DOMPurify allowlist in `shared/ui/src/sanitize-html.ts` and the server-side ammonia sanitizer (`crates/lo-common/src/sanitize.rs`), which permits `span` elements with `data-type`, `data-id`, `data-label`, `data-mention-id`, and `class`.

**Backend** (`apps/api/src/services/idea_mentions.rs`):

- After a comment is created, the API regex-parses every `data-mention-id` attribute value from the sanitized comment HTML.
- The author's own id is skipped and duplicates are collapsed.
- Remaining ids are validated against the **participants** of that idea (idea author ∪ commenters ∪ voters). A well-formed UUID that is not a participant is silently dropped.
- For each surviving user, the API calls `should_notify(db, user_id, "idea_mention")` to resolve the delivery channel.
- Depending on the result, an in-app notification of type `idea_mention` is created and/or a transactional email is sent with `lo-email` `NoticeKind::IdeaMention` (only when the user has an email on record). Its footer links to notification settings because `idea_mention` is configurable.
- Mention dispatch runs in a `tokio::spawn` fire-and-forget task - it never blocks the comment creation response.

**Autocomplete endpoint:**

`ideaParticipants(ideaId: UUID!, search: String)` (GraphQL) and `GET /v1/ideas/{id}/participants?search=` (REST) return the union of the idea author, all voters, and all commenters, filtered by the optional `search` string (bounded to 10 rows). **@mention autocomplete is a dashboard-only action, so both accept only a signed-in user**: a dashboard session or the user's own API key (`lm_usr_*`). An anonymous caller gets `Authentication required` (`401` on REST, `UNAUTHENTICATED` on GraphQL). Every other credential - overlay, shared-overlay, widget, extension and popout tokens, service, developer and system keys - gets `This endpoint requires a logged-in user session` (`403` on REST, `FORBIDDEN` on GraphQL).

### Timeline

Every idea maintains an append-only list of timeline entries. Each row records an `action`, an optional `old_value`, an optional `new_value`, and the acting user (`actor`, nullable once the user is deleted).

| `action` | `old_value` → `new_value` |
|----------|---------------------------|
| `status_changed` | Previous status → new status. Also written on creation as `null` → `open`. |
| `title_changed` | Previous title → new title |
| `description_changed` | Previous description → new description |
| `category_changed` | Previous category label → new category label |

Timeline entries are displayed chronologically (`created_at ASC`) on the idea detail page. Tag changes are not recorded on the timeline.

The previous and new text of `title_changed` and `description_changed` entries are returned only to the idea's author and Ideas staff (`ideas:moderate_read`). Everyone else, including anonymous visitors, gets `null` for both values. Status and category values are public. An author's or actor's `login` is likewise returned only to staff and to the user themself. See [REST API → Ideas Hub](../api-reference/rest-api.md#ideas-hub).

### Sharing

Both the dashboard detail page and the public detail page expose a **Share** action that copies the idea's public URL (`/ideas/{id}`) to the clipboard via `navigator.clipboard`. This is a purely client-side action - no share token or backend call is involved; the target is the public marketing page, gated by the `system:ideas_hub_public` feature flag. Both pages show an inline confirmation (the icon flips to a check for two seconds).

### Tags

- Tags are user-created; any user holding `ideas:create` can create a tag inline when submitting or editing an idea.
- Tags are stored globally (not account-scoped) and shared across all ideas.
- Tag names are trimmed and must be 1–50 characters. `name` is `UNIQUE`, and creating an existing tag returns the existing row rather than erroring.
- Deleting a tag requires the **admin** permission `ideas:delete`. Deleting removes the `idea_tag_assignments` rows via cascade but does not delete the ideas themselves.
- An idea carries at most 20 tags.

### Categories

- Categories are admin-managed only. Users choose from existing categories when submitting an idea but cannot create new ones.
- `ideas.category_id` is `NOT NULL` with `ON DELETE RESTRICT` - every idea has a category, and a category cannot be deleted while any idea references it (the API surfaces this as `"Cannot delete category: ideas still reference it"`).
- A category has a machine `name` (unique), a human-facing `label`, an optional `color`, and a `sort_order`. There is no description field.
- Eight categories ship seeded: `overlay`, `chat`, `bot`, `integration`, `music`, `automation`, `ui`, `other`.

## Database

### Tables

| Table | Description |
|-------|-------------|
| `ideas` | Core idea rows: `id`, `author_id` (`NULL` on a tombstone), `category_id` (FK, `NOT NULL`, `ON DELETE RESTRICT`), `title`, `description` (sanitized HTML), `status`, `vote_count_up`, `vote_count_down`, `comment_count` (live comments only), `created_at`, `updated_at`, `deleted_at` (set on a tombstone) |
| `idea_votes` | `idea_id`, `user_id`, `vote_type` (`'up'` or `'down'`), `created_at`. Primary key `(idea_id, user_id)`. |
| `idea_comments` | `id`, `idea_id`, `author_id` (`NULL` on a tombstone), `parent_id` (nullable, self-ref), `body`, `vote_count_up`, `vote_count_down`, `created_at`, `updated_at`, `deleted_at` (set on a tombstone) |
| `idea_comment_votes` | `comment_id`, `user_id`, `vote_type` (`'up'` or `'down'`), `created_at`. Primary key `(comment_id, user_id)`, both FKs `ON DELETE CASCADE`. |
| `idea_timeline` | `id`, `idea_id`, `actor_id` (nullable, `ON DELETE SET NULL`), `action`, `old_value`, `new_value`, `created_at` |
| `idea_tags` | `id`, `name` (unique), `created_by`, `created_at`. Global, not account-scoped. |
| `idea_tag_assignments` | `(idea_id, tag_id)` join table |
| `idea_categories` | `id`, `name` (unique), `label`, `color`, `sort_order`, `created_at` |

## API

### GraphQL Queries

Ideas Hub reads are **public-flag gated for anonymous callers**: every read requires `system:ideas_hub` (master), and an **anonymous** caller additionally requires `system:ideas_hub_public`. Authenticated users reach the dashboard on the master flag alone. This enforces the public kill-switch server-side (identically on REST and WebSocket), not just in the web UI. `ideaParticipants` is the exception - it **requires authentication**.

| Query | Permission | Description |
|-------|-----------|-------------|
| `ideas(filter: IdeaFilterInput, sort: IdeaSortInput, limit: Int! = 20, offset: Int! = 0)` | Flag (public flag if anonymous) | Paginated idea list; returns `GqlIdeaConnection { items, total }`. `limit` clamps to 1–100. Authors, categories, tags and the caller's votes for the whole page are resolved in one batched query each (no per-idea lookups); REST `GET /v1/ideas` does the same. |
| `idea(id: UUID!)` | Flag (public flag if anonymous) | Single idea (`GqlIdea`), or `null` when not found |
| `ideaComments(ideaId: UUID!)` | Flag (public flag if anonymous) | Comment tree for an idea |
| `ideaCategories` | Flag (public flag if anonymous) | All categories |
| `ideaTags(search: String)` | Flag (public flag if anonymous) | Tag list with optional search |
| `ideaVoters(ideaId: UUID!)` | Flag (public flag if anonymous) | Who voted, and which way (`GqlIdeaVoter`); bounded to 500 rows |
| `ideaParticipants(ideaId: UUID!, search: String)` | **Auth required** | Users who interacted with an idea (author, voters, commenters); used for @mention autocomplete |
| `ideaTimeline(ideaId: UUID!)` | Flag (public flag if anonymous) | Timeline entries for an idea, oldest first |

There is no `myIdeaVote` query - the caller's own vote is returned inline on `GqlIdea.myVote`.

### GraphQL Mutations

| Mutation | Permission | Description |
|----------|-----------|-------------|
| `createIdea(input: CreateIdeaInput!)` | `ideas:create` | Submit a new idea; writes a `status_changed` (`null` → `open`) timeline entry |
| `updateIdea(id: UUID!, input: UpdateIdeaInput!)` | `ideas:edit` (own) or `ideas:moderate_edit` (any) | Edit title, description, category, tags |
| `deleteIdea(id: UUID!)` | `ideas:delete` (own) or `ideas:moderate_delete` (any) | Delete an idea; a tombstone while others' comments hang off it ([Deletion and tombstones](#deletion-and-tombstones)) |
| `updateIdeaStatus(id: UUID!, status: String!)` | `ideas:moderate_status` | Change status and append a timeline entry |
| `voteIdea(id: UUID!, voteType: String!)` | `ideas:vote` | Cast or change a vote (`"up"` or `"down"`) |
| `removeVote(id: UUID!)` | `ideas:vote` | Remove the current user's vote |
| `createIdeaComment(input: CreateIdeaCommentInput!)` | `ideas:comment_create` | Post a comment (top-level or nested) |
| `updateIdeaComment(id: UUID!, body: String!)` | `ideas:comment_edit` + ownership | Edit a comment body |
| `deleteIdeaComment(id: UUID!)` | `ideas:comment_delete` (own) or `ideas:moderate_comment` (any) | Delete a comment; a tombstone while it has replies |
| `voteIdeaComment(id: UUID!, voteType: String!)` | `ideas:comment_vote` | Cast or change a comment vote (`"up"` or `"down"`) |
| `removeIdeaCommentVote(id: UUID!)` | `ideas:comment_vote` | Remove the current user's comment vote |
| `createIdeaTag(name: String!)` | `ideas:create` | Create (or return) a global tag |
| `deleteIdeaTag(id: UUID!)` | admin `ideas:delete` | Delete a tag |
| `createIdeaCategory(input: CreateIdeaCategoryInput!)` | admin `ideas:edit` | Create a new category |
| `updateIdeaCategory(id: UUID!, input: UpdateIdeaCategoryInput!)` | admin `ideas:edit` | Edit a category |
| `deleteIdeaCategory(id: UUID!)` | admin `ideas:delete` | Delete a category (blocked if ideas reference it) |

The four category/tag admin mutations are guarded by `AdminPermissionGuard`, so they check the caller's **admin-role** permissions. The moderation checks (`ideas:moderate_*`) accept the permission from either the user role or an admin role.

Pinning is not implemented - there is no `pinIdea` mutation, no pin endpoint, and no `is_pinned` column.

### REST Endpoints

All Ideas Hub REST paths live under `/v1/ideas`, including the moderator/admin ones.

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/ideas` | Flag only | List ideas with query params for filter/sort/pagination |
| `POST` | `/v1/ideas` | `ideas:create` | Create an idea |
| `GET` | `/v1/ideas/categories` | Flag (public if anon) | List all categories |
| `GET` | `/v1/ideas/tags` | Flag (public if anon) | List all tags |
| `POST` | `/v1/ideas/tags` | `ideas:create` | Create (or return) a tag |
| `GET` | `/v1/ideas/{id}` | Flag (public if anon) | Get a single idea **plus its timeline** (`{ idea, timeline }`) |
| `PATCH` | `/v1/ideas/{id}` | `ideas:edit` (own) or `ideas:moderate_edit` | Update title, description, category, tags |
| `DELETE` | `/v1/ideas/{id}` | `ideas:delete` (own) or `ideas:moderate_delete` | Delete an idea; a tombstone while others' comments hang off it |
| `POST` | `/v1/ideas/{id}/vote` | `ideas:vote` | Cast or change a vote |
| `DELETE` | `/v1/ideas/{id}/vote` | `ideas:vote` | Remove the current user's vote |
| `GET` | `/v1/ideas/{id}/voters` | Flag (public if anon) | List voters and their vote type; bounded to 500 rows |
| `GET` | `/v1/ideas/{id}/participants` | **Signed-in user** (session or `lm_usr_*`) | List users who interacted with the idea; supports `?search=` |
| `GET` | `/v1/ideas/{id}/comments` | Flag (public if anon) | Comment tree with nested `replies` |
| `POST` | `/v1/ideas/{id}/comments` | `ideas:comment_create` | Post a comment |
| `PATCH` | `/v1/ideas/comments/{id}` | `ideas:comment_edit` + ownership | Edit a comment |
| `DELETE` | `/v1/ideas/comments/{id}` | `ideas:comment_delete` (own) or `ideas:moderate_comment` | Delete a comment; a tombstone while it has replies |
| `POST` | `/v1/ideas/comments/{id}/vote` | `ideas:comment_vote` | Cast or change a comment vote |
| `DELETE` | `/v1/ideas/comments/{id}/vote` | `ideas:comment_vote` | Remove the current user's comment vote |
| `PATCH` | `/v1/ideas/{id}/status` | `ideas:moderate_status` | Change status |
| `POST` | `/v1/ideas/categories` | admin `ideas:edit` | Create category |
| `PATCH` | `/v1/ideas/categories/{id}` | admin `ideas:edit` | Update category |
| `DELETE` | `/v1/ideas/categories/{id}` | admin `ideas:delete` | Delete category |
| `DELETE` | `/v1/ideas/tags/{id}` | admin `ideas:delete` | Delete tag |

REST has no standalone timeline endpoint - the timeline ships inside `GET /v1/ideas/{id}`, mirroring GraphQL's `ideaTimeline`.

### Filter / Sort Options

GraphQL takes these as `IdeaFilterInput` / `IdeaSortInput` (camelCase); REST takes them as query parameters (snake_case). The values are identical.

| Parameter | Values | Description |
|-----------|--------|-------------|
| `status` | `open`, `planned`, `in_progress`, `testing`, `completed`, `closed` | Filter by status |
| `category_id` / `categoryId` | UUID | Filter by category |
| `tag_ids` / `tagIds` | UUID list (REST: comma-separated) | Filter to ideas carrying the specified tags |
| `author_id` / `authorId` | UUID | Filter by author |
| `search` | string | Search on title and description |
| `sort` | `newest`, `most_voted`, `most_commented`, `recently_updated` | Sort order (default `newest`) |
| `limit` | integer | Page size (default 20, clamped to 1–100) |
| `offset` | integer | Row offset (default 0) |

### Validation Limits

Identical on both protocols:

| Field | Limit |
|-------|-------|
| Idea title | 200 characters |
| Idea description | 50 000 bytes |
| Tags per idea | 20 |
| Tag name | 1–50 characters |
| Comment body | 10 000 bytes |

## WebSocket Channels

The `ideas` channel family is gated by `channel_feature_for("ideas") = "system:ideas_hub"` (master, enforced for every subscriber) and `channel_gate_for("ideas") = PublicWhenFeature("system:ideas_hub_public")` - the public kill-switch, which `feature_check` enforces **for anonymous subscribers**. So an anonymous client is refused when either flag is off, while an authenticated client subscribes on the master flag alone (matching the REST/GraphQL rule). Traffic is server-push only; clients never publish on these channels.

| Channel | Gate | Description |
|---------|------|-------------|
| `ideas:list` | Public when `system:ideas_hub_public` | Index channel. Carries `idea:created`. |
| `ideas:{id}` | Public when `system:ideas_hub_public` | Per-idea channel. Carries `idea:updated`, `idea:voted`, `idea:comment`, `idea:comment_voted`, `idea:status_changed`. |

Payloads are thin change notifications, not full entities - for example `{ "type": "idea:comment", "idea_id": "…", "comment_id": "…" }`, `{ "type": "idea:comment_voted", "idea_id": "…", "comment_id": "…" }`, or `{ "type": "idea:status_changed", "idea_id": "…", "status": "planned" }`. Clients refetch on receipt. `idea:comment_voted` is emitted for symmetry with `idea:voted`; there is no consumer today.

## Atom Feed

The feed is served at `/ideas/feed.xml` by a Next.js route handler in the web app (`apps/web/src/app/(main)/(marketing)/ideas/feed.xml/route.ts`). It:

- Returns an **Atom 1.0** document (`application/atom+xml`), cached for 300 seconds.
- Lists the 50 newest ideas (`sort: NEWEST`, `limit: 50`) regardless of status.
- Emits per entry: `<title>`, `<link>`, `<id>`, `<updated>`, `<published>`, `<author>`, a `<category>` for the category label, a second `<category term="…" scheme="status">`, and a `<summary type="text">` carrying the vote/comment counts plus the first 500 characters of the tag-stripped description.
- Requires no authentication, and sources its data through `serverGqlSSR()` - not a dedicated REST endpoint.
- Requires **both** `system:ideas_hub` and `system:ideas_hub_public`; if either is off it returns a 404 XML body.

## Permissions

Ideas Hub uses two permission scopes, both defined in `crates/lo-auth/src/rbac.rs`.

**User-scope** (`rbac::user`) - granted through global user roles, seeded by migration `20260506000002_seed_default_user_roles`:

| Permission | Description |
|-----------|-------------|
| `ideas:read` | Read ideas |
| `ideas:create` | Submit ideas and create tags |
| `ideas:edit` | Edit your own idea |
| `ideas:delete` | Delete your own idea |
| `ideas:vote` | Cast and remove votes |
| `ideas:comment_read` | Read comments |
| `ideas:comment_create` | Post comments |
| `ideas:comment_edit` | Edit your own comment |
| `ideas:comment_delete` | Delete your own comment |
| `ideas:comment_vote` | Cast and remove comment votes |

`ideas:read` and `ideas:comment_read` exist in the registry, but no read path enforces them today - reads are gated on the feature flag alone.

Three user roles ship seeded: **Member** (default - every permission above), **Restricted** (`ideas:read`, `ideas:comment_read`), and **Moderator** (Member's set plus the four `ideas:moderate_*` permissions below).

**Admin-scope** (`rbac::global`) - seeded onto the `system_admin` admin role by migration `20260506000011_seed_ideas_admin_permissions`:

| Permission | Description |
|-----------|-------------|
| `ideas:moderate_read` | View the admin ideas management pages and moderation queue |
| `ideas:moderate_status` | Change the status of any idea |
| `ideas:moderate_edit` | Edit any idea's content; gates the admin category/tag management pages |
| `ideas:moderate_delete` | Delete any idea |
| `ideas:moderate_comment` | Delete any comment |

Moderation checks pass when the permission is present on **either** the user role or an admin role. The category/tag write endpoints are the exception: they require the admin-scope strings `ideas:edit` / `ideas:delete`.

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/graphql/ideas.rs` | GraphQL queries and mutations |
| `apps/api/src/routes/ideas.rs` | REST handlers |
| `apps/api/src/db/ideas.rs` | DB operations for ideas, votes, comments, timeline, tags, categories |
| `apps/api/src/services/idea_mentions.rs` | @mention parsing, notification, and email dispatch |
| `apps/web/src/app/api/ideas/[[...path]]/route.ts` | Next.js proxy route |
| `apps/web/src/app/(main)/(app)/hub/ideas/` | Dashboard Ideas Hub pages |
| `apps/web/src/app/(main)/(marketing)/ideas/` | Public Ideas Hub pages and Atom feed |
| `apps/admin/src/app/(admin)/hub/ideas/` | Admin ideas, category, and tag management pages |
| `crates/lo-auth/src/rbac.rs` | User-scope and admin-scope permission constants |
| `crates/lo-common/src/sanitize.rs` | Shared ammonia HTML sanitizer (allows mention spans) |
| `crates/lo-websocket/src/gate.rs` | `channel_gate_for` / `channel_feature_for` for `ideas:*` channels |
| `crates/lo-email/src/notices.rs` | `IdeaMention` email copy in both languages |

---

## Features / Provider Management

Source: https://docs.lumio.vision/features/provider-management

# Provider Management

## Overview

Provider Management allows admins to globally enable or disable platform providers (Twitch, YouTube, Kick, Discord, Spotify) with granular controls per connection type. Each provider has a **kill-switch** that disables everything, plus **sub-flags** for the connection types it actually supports - login, channel, and/or bot. The specific mix of sub-flags varies per platform:

- **Twitch, YouTube, Kick** - login + channel + bot.
- **Discord** - login + bot (no channel: Discord is used for auth + the bot, not per-channel OAuth streams).
- **Spotify** - channel only (per-account OAuth for music/event integration; there is no Spotify login and no Spotify chat bot). The public `enabledPlatforms` GraphQL query filters platforms down to those with an enabled `:login` or `:bot` sub-flag, so Spotify is intentionally excluded from the "Supported Platforms" list on pricing cards while still being usable as a per-account music integration.

### Capability registry

`apps/api/src/platforms.rs` (`PLATFORMS`) is the single source of truth for what each platform can do. It declares four booleans - `has_login`, `has_channel`, `has_bot`, `has_integration` - and both the admin Providers page and the capability-aware GraphQL guards read it:

| Platform | Login | Channel | Bot | Integration |
|----------|:-----:|:-------:|:---:|:-----------:|
| `twitch` | x | x | x | |
| `youtube` | x | x | x | |
| `kick` | x | x | x | |
| `discord` | x | | x | x |
| `spotify` | | x | | |
| `shopify` | | | | x |

Shopify is registry-only: it has no login, channel or bot capability, so `GET /v1/admin/providers` and `adminProviders` filter it out and it never appears on the Provider Management page. Its enablement lives on the `integration:shopify` feature flag instead. Discord's integration capability covers `discord_guild_connections`, which is managed on its own screens, not through the sub-flag toggles.

## Feature Flag Hierarchy

Each provider has a kill-switch and sub-flags for different connection types:

```
platform:twitch              <- Kill-switch (disables everything)
+-- platform:twitch:login    <- Login via Twitch
+-- platform:twitch:channel  <- Channel Connection
+-- platform:twitch:bot      <- Bot Connection
```

The seeded flags (`seed_default_feature_flags` in `apps/api/src/db/admin.rs`) are the five provider kill-switches plus: `:login` for twitch/youtube/kick/discord, `:channel` for twitch/youtube/kick/spotify, and `:bot` for twitch/youtube/kick/discord.

### Resolution Logic

1. If the kill-switch (`platform:{provider}`) is disabled -- **everything** is blocked
2. If the kill-switch is enabled -- check the sub-flag:
   - `platform:{provider}:login` -- controls login availability
   - `platform:{provider}:channel` -- controls channel connections
   - `platform:{provider}:bot` -- controls bot connections
3. If a sub-flag doesn't exist -- **denied**. Resolution is fail-closed: `FeatureService::is_enabled` treats a key that is absent from the global cache as disabled, and `get_enabled_providers` skips any platform whose `platform:{p}:{subtype}` key is missing. An unseeded combination (e.g. `platform:spotify:bot`) is therefore never "allowed by default".

Both levels also honour per-account overrides, so `is_provider_enabled(platform, subtype, Some(account_id))` can differ from the global answer.

The global flag cache is refreshed on a 5-minute cycle, but every admin provider toggle calls `refresh_global_cache()` inline, so a toggle takes effect immediately.

### Soft-Block Behavior

When a provider or sub-flag is disabled:
- **New** connections/logins are blocked
- **Existing** connections continue working
- Token refresh continues
- Global bots keep running
- Per-account overrides are possible via the admin panel

## Architecture

### Backend

- **Platform registry** (`apps/api/src/platforms.rs`) -- `PLATFORMS` capability table plus `lookup()`, used to validate the `{platform}` path segment (an unknown slug returns `400 Unknown platform: …`) and to decide which sub-flag toggles exist.
- **FeatureService** (`apps/api/src/services/feature_service.rs`) -- Core service with `is_provider_enabled(platform, subtype, account_id)` for two-level flag checks, `get_enabled_providers(subtype)` for listing enabled platforms per connection type, `get_enabled_platforms()` for kill-switch-level queries, and `get_streaming_platforms()` backing `enabledPlatforms`.
- **GraphQL** (`apps/api/src/graphql/connections.rs`, `apps/api/src/graphql/admin.rs`) -- `enabledProviders(connectionType)`, `enabledPlatforms`, `connectionStatuses`, and the admin `adminProviders` query with its four set/toggle mutations. **Primary path used by all frontend apps.**
- **REST** (`apps/api/src/routes/features.rs`) -- Public `GET /v1/providers/enabled?type={login|channel|bot}` endpoint, kept for external SDK consumers (CLIs, bots, scripts). Frontend apps do not call this - they route through the GraphQL resolver via `serverGqlSSR` to keep the "Frontend → Next.js proxy → GraphQL" pattern consistent.
- **Admin REST** (`apps/api/src/routes/admin.rs`) -- Admin endpoints for provider stats, enable/toggle, and account connection management.

### Frontend

- **ID App** -- SSR login page (`apps/id/src/app/login/page.tsx`) and signIn callback (`apps/id/src/auth.ts`) call `enabledProviders(connectionType: "login")` via `serverGqlSSR` to gate login buttons.
- **Web App** -- Connection flow checks provider enablement before showing connect options.
- **Admin App** -- Dedicated Provider Management page for toggling flags and viewing stats.

## Admin Management

### Provider Page

The admin panel includes a dedicated **Provider Management** page at `/providers` (`apps/admin/src/app/(admin)/providers/`), gated on `providers:read`. Admins can:
- Toggle the kill-switch per platform
- Toggle individual sub-flags (Login / Channel / Bot) - only the toggles the platform's capabilities declare are rendered
- View system credential status (`system_credentials_configured`) with a link to configure credentials when unset
- View connection counts (`login_connection_count`, `channel_connection_count`, `bot_connection_count`, `integration_count`)
- Connect or disconnect the global bot for platforms with `has_bot`, which requires system credentials to be configured first

### Account Connections

On the account detail page, admins can:
- View and delete channel connections
- View and delete bot connections
- View and delete StreamElements tokens

### User Login Connections

On the user detail page, admins can delete individual login connections.

## API

### Public Endpoints

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/v1/providers/enabled?type={login\|channel\|bot}` | none (public) | List enabled providers |

### Admin Endpoints

| Method | Path | Permission | Description |
|--------|------|------------|-------------|
| GET | `/v1/admin/providers` | `providers:read` | List all providers with stats (integration-only platforms filtered out) |
| PATCH | `/v1/admin/providers/{platform}/enabled` | `providers:edit` | Set the kill-switch to an explicit value; returns the refreshed provider stats |
| PATCH | `/v1/admin/providers/{platform}/{subtype}/enabled` | `providers:edit` | Set a sub-flag to an explicit value; returns the refreshed provider stats |
| PATCH | `/v1/admin/providers/{platform}/toggle` | `features:edit` | Flip the kill-switch; returns the raw feature flag |
| PATCH | `/v1/admin/providers/{platform}/{subtype}/toggle` | `features:edit` | Flip a sub-flag; returns the raw feature flag |
| GET | `/v1/admin/accounts/{id}/connections` | `accounts:read` | List channel connections |
| DELETE | `/v1/admin/accounts/{id}/connections/{platform}` | `accounts:edit` | Delete channel connection |
| GET | `/v1/admin/accounts/{id}/bot-connections` | `accounts:read` | List bot connections |
| DELETE | `/v1/admin/accounts/{id}/bot-connections/{platform}` | `accounts:edit` | Delete bot connection |
| GET | `/v1/admin/accounts/{id}/se-tokens` | `se-tokens:read` | List SE tokens |
| DELETE | `/v1/admin/accounts/{id}/se-tokens/{token_id}` | `se-tokens:delete` | Delete SE token |
| DELETE | `/v1/admin/users/{id}/login-connections/{provider}` | `users:edit` | Delete login connection |

The `/enabled` and `/toggle` variants both exist and act on the same feature flags. `/enabled` is idempotent (you send the target state) and is what the admin UI uses; `/toggle` flips the current value and is guarded by the broader `features:edit` rather than `providers:edit`.

`GET /v1/admin/accounts/{id}/connections` carries no `utoipa::path` annotation, so it is absent from `apps/api/openapi.json` even though the route is live.

### GraphQL

| Type | Name | Guard | Description |
|------|------|-------|-------------|
| Query | `enabledProviders(connectionType: String!): [String!]!` | none | List enabled providers for `login` / `channel` / `bot` |
| Query | `enabledPlatforms: [String!]!` | none | Kill-switch-enabled platforms that also have an enabled `:login` or `:bot` sub-flag. Used by the public pricing page. |
| Query | `connectionStatuses: [ConnectionStatus!]!` | `connections:read` | Platform statuses with `enabled` field |
| Query | `botConnectionStatuses: [BotConnectionStatus!]!` | `bot-connections:read` | Bot platform statuses with `enabled` field |
| Query | `adminProviders: [ProviderInfo!]!` | `providers:read` (admin) | Providers with capabilities, connection counts and flag status - the query the admin page uses |
| Mutation | `adminSetProviderEnabled(platform, enabled): Boolean!` | `providers:edit` (admin) | Set the kill-switch to an explicit value |
| Mutation | `adminSetProviderSubtypeEnabled(platform, subtype, enabled): Boolean!` | `providers:edit` (admin) | Set a sub-flag to an explicit value |
| Mutation | `adminToggleProvider(platform): ProviderInfo!` | `providers:edit` (admin) | Flip the kill-switch, return refreshed `ProviderInfo` |
| Mutation | `adminToggleProviderSubtype(platform, subtype): ProviderInfo!` | `providers:edit` (admin) | Flip a sub-flag, return refreshed `ProviderInfo` |

Admin mutations use `AdminPermissionGuard` (admin-role permissions), not the account-scoped `PermissionGuard`.

### WebSocket

Provider enablement has no WebSocket channel - there is no `providers` arm in `channel_gate_for`. Clients pick up a flag change on their next query; the server-side cache is refreshed inline on every toggle.

## Per-Account Overrides

Admins can override provider flags per account using the existing account feature override system. On the account detail page, toggle any `platform:*` or `platform:*:*` flag in the Feature Overrides tab.

## Key Files

| Path | Description |
|------|-------------|
| `apps/api/src/services/feature_service.rs` | Core feature flag resolution logic |
| `apps/api/src/routes/features.rs` | Public providers REST endpoint |
| `apps/api/src/routes/admin.rs` | Admin provider management endpoints |
| `apps/api/src/db/admin.rs` | Feature flag DB operations and seed data |
| `apps/api/src/graphql/connections.rs` | GraphQL queries with provider enablement |
| `apps/api/src/platforms.rs` | `PLATFORMS` capability registry (login / channel / bot / integration) |
| `apps/api/src/graphql/admin.rs` | `adminProviders` + the four admin provider mutations |
| `apps/admin/src/app/(admin)/providers/provider-management.tsx` | Admin Provider Management UI |

## See Also

- [Bot Connections](/features/bot-connections) -- Custom bot identities per account
- [Connections](/features/connections) -- Channel connection OAuth flow
- [Token Refresh](/features/token-refresh) -- Automatic token refresh worker

---

## Features / Token Refresh

Source: https://docs.lumio.vision/features/token-refresh

# Token Refresh

## Overview

The Token Refresh Worker is the **single, authoritative component** responsible for refreshing OAuth access tokens for all platform connections. It runs as a background task inside the API server, continuously monitoring token expiry across `channel_connections`, `login_connections`, and `bot_connections`. Discord **login** tokens are refreshed; its global **bot** token is static, while server mappings store no OAuth token.

All workers and services that need a fresh token read it from the database using the utility functions in `apps/api/src/oauth.rs`. They never hold tokens in-memory across operations or call refresh logic inline.

## Token Lifecycle

```
OAuth Provider (Twitch, YouTube, etc.)
    |
    | (user connects channel / logs in)
    v
DB: channel_connections / login_connections
    - access_token  (AES-256-GCM encrypted)
    - refresh_token (AES-256-GCM encrypted)
    - expires_at
    |
    | (background, always running)
    v
Token Refresh Worker (apps/api/src/workers/token_refresh.rs)
    - Wakes 10 min before next expiry
    - Calls platform token endpoint
    - Re-encrypts new tokens
    - Writes back to DB
    |
    | (on each API call)
    v
get_fresh_connection_token() / get_fresh_oauth_token()
    - Reads encrypted tokens from DB
    - Decrypts with config.auth.token_encryption_key
    - Returns FreshToken to caller
```

## Which Tables Are Refreshed

| Table | Purpose | Function to read |
|-------|---------|-----------------|
| `channel_connections` | Platform API tokens (Twitch, YouTube, Kick, Spotify) | `get_fresh_connection_token()` |
| `login_connections` | OAuth login session tokens (used to authenticate users on sign-in) | `get_fresh_oauth_token()` |
| `bot_connections` | Bot identity tokens (refreshed for OAuth bot platforms; the Discord global bot token is static) | `get_fresh_bot_token()` |

In all three tables, rows flagged `reconnect_required = true` are excluded - both
from the refresh pass and from the "next expiry" calculation. A connection in
that state needs the user to re-authorize; retrying its refresh token would only
burn requests.

## Cluster Safety

Every API replica starts its own Token Refresh Worker, but only one may refresh a
given cycle. Before each pass the worker takes a **non-blocking Postgres advisory
lock** (`pg_try_advisory_lock`, key `0x746F6B65` = `"toke"`); a replica that
does not get the lock skips the cycle immediately without holding a connection.

This matters because several providers (Google, Kick, Discord, …) **rotate the
refresh token on use**. Two replicas refreshing the same row would replay an
already-consumed refresh token, and the provider may invalidate the whole token
family - permanently breaking that connection's auth. The lock is released after
the pass, and a crashed replica releases it automatically on disconnect.

## Single-Flight Per Connection

The cluster lock above stops two **replicas** running the refresh pass at once,
but it is not the only refresher of a given row. A login connection is also
refreshed **on demand** by `services::login_token::get_valid_account_login_token`
when the send path needs a token whose expiry is within 60 seconds - and that
lazy path and the worker's 10-minute window overlap in the last minute before
expiry. For a provider that rotates the refresh token on use (**Kick** is OAuth
2.1 and always returns a new refresh token), the loser of that race replays an
already-consumed token, the provider rejects it, and the connection is flagged
`reconnect_required` - the exact opposite of an automatic refresh.

There are therefore **two distinct advisory locks**, and they must not be
confused:

| Lock | Key | Blocking? | What it serialises |
|------|-----|-----------|--------------------|
| Global / session | `pg_try_advisory_lock(0x746F6B65)` - a **constant** | non-blocking | one replica per refresh cycle |
| Per connection | `pg_advisory_xact_lock(hashtextextended(connection_id, 0))` - the **row UUID** | blocking | the two refreshers of a single row (the worker pass and the login-lazy path) |

Every refresh path takes the **per-connection** lock before hitting the provider,
via `oauth::lock_connection_for_refresh(kind, connection_id)`, and then **re-reads
the expiry under the lock**: if another flight already refreshed the row while it
waited (a successful refresh pushes `expires_at` far into the future), it skips
instead of calling the provider again. The worker's on-demand login twin
(`services::login_token`) takes the **same** key, so the two serialise against
each other and exactly one flight refreshes a given row. The refreshed tokens are
persisted **inside** the lock transaction, whose commit releases the lock
atomically with the write - so no token write happens outside the lock, and the
`COALESCE(refresh_token)` update can never let a race loser clobber the winner's
freshly rotated token. Connection-row UUIDs are unique across the three tables,
so the single lock space needs no per-table namespacing.

## Failure Backoff

A refresh that fails bumps the row's `updated_at`. The refresh query then skips
any row matching `expires_at < now() AND updated_at > now() - interval '1 hour'` - that is, an **already-expired** token whose refresh was attempted within the
last hour. This keeps a permanently broken connection (revoked grant, deleted
app credential) from being retried on every 5-minute cycle. Tokens that are not
yet expired are retried normally.

## Supported Platforms

| Platform | Token Endpoint | Auth Style |
|----------|---------------|------------|
| Twitch | `https://id.twitch.tv/oauth2/token` | Body params |
| YouTube / Google | `https://oauth2.googleapis.com/token` | Body params |
| Kick | `https://id.kick.com/oauth/token` | Body params |
| Spotify | `https://accounts.spotify.com/api/token` | `Authorization: Basic` header |
| Discord | `https://discord.com/api/v10/oauth2/token` | Body params |

## When Tokens Are Refreshed

The worker uses a **smart sleep** strategy to minimize wasted wakeups:

1. On startup: immediately runs a full pass to catch any already-expired tokens.
2. After each pass: queries the minimum `expires_at` across both tables and sleeps until **10 minutes before** that expiry.
3. The sleep is capped at **5 minutes** so the worker never goes dormant too long.
4. If a token is already within the 10-minute window (or already expired), the worker wakes in 5 seconds.

A token is considered in need of refresh when:

```
expires_at < now() + interval '10 minutes'
```

Only tokens with a `refresh_token` present are eligible. Tokens without a refresh token (e.g., non-expiring API keys) are skipped silently.

## Encryption

All tokens in the database are encrypted at rest using **AES-256-GCM**. The encryption key comes from:

```toml
# apps/api/config/local.toml
[auth]
token_encryption_key = "<base64-encoded 32-byte key>"
```

Generate a key with:

```bash
openssl rand -base64 32
```

The encryption key can also be set via the `LUMIO__AUTH__TOKEN_ENCRYPTION_KEY` environment variable (the `LUMIO__SECTION__KEY` convention used by `lo_config`).

The worker decrypts tokens before sending them to the platform endpoint and re-encrypts the new tokens before writing them back to the database.

**Rotating the key invalidates every stored secret.** The ciphertext carries no key-version tag, so a value only decrypts under the exact key that wrote it. Changing `token_encryption_key` - or deploying a build that derives a different key from the same config (e.g. an env override that had been silently dropped) - makes **all** previously stored secrets unreadable at once: every `access_token`/`refresh_token` on `channel_connections` and `bot_connections`, and every `client_id`/`client_secret` in `app_credentials`. When the worker cannot decrypt a token - or the account's `app_credentials` client_id/secret needed to talk to the provider - it never sends the raw ciphertext upstream; it treats the failure as terminal, flags the connection `reconnect_required`, and fires the best-effort audit + email. **Remediation:** the owner re-enters app credentials in the platform tab’s **App** section and reconnects the affected channels; there is no automatic re-encryption migration.

## OAuth App Credentials

For `channel_connections` and OAuth `bot_connections`, refresh follows the row's pinned `credential_source`.

| `credential_source` | OAuth app pair | Token row |
|---------------------|----------------|-----------|
| `account` | `client_id` + `client_secret` from `app_credentials` matched by `(account_id, platform)` | `channel_connections` or `bot_connections` |
| `system` | global config pair resolved by `CredentialResolver::system_pair(platform)` | `channel_connections` or `bot_connections` |

The access token and refresh token are always stored encrypted on the connection row. `account` app credentials are also encrypted in the database; `system` app credentials come from config. The pin exists because a refresh token minted by one OAuth app cannot be refreshed by another.

If a row is pinned to `system` but the matching global key pair is absent at refresh time, the refresh fails clearly and the row is handled like any other refresh failure. If a row is pinned to `account` but the account's `app_credentials` row is absent, the account must save credentials and reconnect.

For `login_connections`, the `client_id` and `client_secret` are the **config-level** credentials set in `[auth]` (e.g., `twitch_client_id`, `google_client_id`, `discord_client_id` / `discord_client_secret`), resolved by `services::login_token::get_provider_credentials`. These are NOT stored in `app_credentials`. Discord rotates refresh tokens; the worker and the on-demand login path use the same single-flight lock. A provider with no configured credentials is skipped.

## Utility Functions

Both functions live in `apps/api/src/oauth.rs` and are the correct way for any worker or feature to obtain a decrypted, ready-to-use token.

### `get_fresh_connection_token`

Reads and decrypts a channel connection's access token and refresh token, then resolves the OAuth app pair from the pinned `credential_source`.

```rust
use crate::oauth::get_fresh_connection_token;

let token = get_fresh_connection_token(&db, connection_id, &resolver).await?;
// token.access_token  -- decrypted, ready for API use
// token.client_id     -- matching OAuth app client ID
// token.client_secret -- matching OAuth app client secret
// token.expires_at    -- optional expiry timestamp
```

Use this for: Twitch chat workers, YouTube polling, Spotify and Kick - workers that call a platform API on behalf of a channel. Discord has no channel connection.

### `get_fresh_oauth_token`

Reads and decrypts a login connection's access token from `login_connections`. `client_id` and `client_secret` are returned as empty strings - the caller must supply the login config credentials separately.

```rust
use crate::oauth::get_fresh_oauth_token;

let token = get_fresh_oauth_token(&db, login_connection_id, &encryption_key).await?;
// token.access_token -- decrypted login token
// token.client_id    -- always "" (use config credentials)
```

Use this for: features that need the user's login token (e.g., reading scoped login-level platform data).

### `get_fresh_bot_token`

Reads and decrypts a bot identity token from `bot_connections`, resolving the OAuth app pair from the row's pinned `credential_source`. Rows with `reconnect_required = true` are not returned. For Discord the returned `client_id` / `client_secret` are empty strings, because Discord bot tokens are static and are never refreshed.

```rust
use crate::oauth::get_fresh_bot_token;

let token = get_fresh_bot_token(&db, bot_connection_id, &resolver).await?;
// token.access_token   -- decrypted bot identity token
// token.refresh_token  -- decrypted, None when the platform issues none
```

Use this for: anything acting as a bot identity rather than as the channel.

## How to Use in a New Worker

When writing a new worker or feature that calls a platform API:

**Do this:**

```rust
// In your worker's run loop or per-request handler:
let token = crate::oauth::get_fresh_connection_token(
    &db,
    connection_id,
    &resolver,
).await?;

// Use token.access_token directly
let response = platform_api_client
    .some_request(&token.access_token)
    .await?;
```

**Never do this:**

```rust
// DO NOT hold OAuthTokens in-memory across loop iterations
// DO NOT call tokens.try_refresh() inline in a worker
// DO NOT implement your own refresh logic
let mut tokens = OAuthTokens { ... };
tokens.try_refresh(&http).await?; // WRONG — Token Refresh Worker handles this
```

This is enforced in code where it used to be violated: `lo-spotify-api`'s client-side
refresh helper is marked `#[deprecated]` with the note "Use
`crate::oauth::get_fresh_connection_token` in `apps/api` instead. Inline refresh
races with the Token Refresh Worker." `OAuthTokens::try_refresh` and
`refresh_oauth_token` have no callers outside `workers/token_refresh.rs`.

The Token Refresh Worker guarantees that `channel_connections.access_token` is always fresh by the time your worker reads it. You can safely read the token from the DB on each API call without worrying about expiry.

## Architecture

```
apps/api/src/workers/token_refresh.rs  -- Background worker (runs_token_refresh_worker)
apps/api/src/oauth.rs                  -- Utility functions + OAuthTokens struct
```

### Worker Internals

| Function | Purpose |
|----------|---------|
| `run_token_refresh_worker()` | Entry point, starts the loop, handles cancellation |
| `refresh_expiring_tokens_if_leader()` | Takes the **global/session** advisory lock; runs the pass only on the winning replica |
| `next_expiry_in_secs()` | Queries MIN(expires_at) across the three tables to determine smart sleep duration |
| `refresh_expiring_tokens()` | Finds all expiring tokens and refreshes each one under the **per-connection** single-flight lock |

### oauth.rs Internals

| Function | Purpose |
|----------|---------|
| `get_fresh_connection_token()` | Read + decrypt channel connection token, resolve credentials by pinned `credential_source` |
| `get_fresh_oauth_token()` | Read + decrypt login connection token |
| `get_fresh_bot_token()` | Read + decrypt bot connection token, resolve credentials by pinned `credential_source` |
| `refresh_oauth_token()` | Execute the HTTP token refresh request |
| `lock_connection_for_refresh()` | Take the **per-connection** single-flight lock and re-read the expiry under it |
| `refresh_still_needed()` | Whether a re-read expiry still needs refreshing within the window (the under-lock re-check) |
| `update_connection_tokens()` | Write refreshed tokens back to `channel_connections` (inside the lock tx) |
| `update_oauth_tokens()` | Write refreshed tokens back to `login_connections` (inside the lock tx) |
| `update_bot_connection_tokens()` | Write refreshed tokens back to `bot_connections` (inside the lock tx) |
| `token_needs_refresh()` | Returns `true` if token expires within 5-minute margin |
| `OAuthTokens::try_refresh()` | Used internally by the worker for channel connections only; persists via the caller's lock-tx executor |

## Key Files

| File | Purpose |
|------|---------|
| `apps/api/src/workers/token_refresh.rs` | Token Refresh Worker implementation |
| `apps/api/src/oauth.rs` | Utility functions: `get_fresh_connection_token`, `get_fresh_oauth_token`, `refresh_oauth_token` |
| `apps/api/src/credentials.rs` | `CredentialResolver`, source-aware global/account credential lookup |
| `apps/api/src/crypto.rs` | AES-256-GCM encrypt/decrypt used by all token operations |
| `apps/api/config/default.toml` | `[auth] token_encryption_key` config key |

---

## Features / YouTube Live Chat Streaming

Source: https://docs.lumio.vision/features/youtube-streaming

# YouTube Live Chat Streaming

## Overview

Lumio receives YouTube live chat messages via InnerTube - YouTube's own internal polling endpoint (`youtubei/v1/live_chat/get_live_chat`). This transport costs **0 Data API quota** and delivers the full range of chat event types. gRPC streamList and REST polling are available as optional fallbacks but are disabled by default.

## Architecture

### Chat Transport

| Mode | Cost | Default |
|------|------|---------|
| **InnerTube** (primary) | 0 quota | Always active |
| gRPC streamList (fallback) | ~0 quota | Disabled (`grpc_fallback_enabled = false`) |
| REST Data API v3 (fallback) | 5 units per poll | Disabled (`rest_fallback_enabled = false`) |

The worker starts every stream task in InnerTube mode. gRPC is lazy-connected only if enabled and InnerTube fails. REST polling is a last resort.

**Fallback cascade:** InnerTube → gRPC (if enabled) → REST (if enabled). Each transition triggers after 3 consecutive failures within 60 seconds.

### How InnerTube Chat Works

InnerTube uses YouTube's own live chat polling contract:

1. **Bootstrap** - The worker resolves the InnerTube API key and client version through the credential resolver, then fetches the live chat embed page (`youtube.com/live_chat?v={video_id}&is_popout=1`) to extract the initial `continuation` token. Continuations are cached in Redis so restarts don't re-scrape the embed page.
2. **Poll loop** - `get_live_chat` is called with the continuation token. The response carries the next continuation token and a server-recommended polling interval. The worker honors that interval (minimum 1 s, default 3 s).
3. **All event types flow through InnerTube** - text messages, SuperChats, SuperStickers, memberships, gift memberships, message deletions, user bans, poll events, and members-only mode changes are all returned in the same response.
4. **Missing continuation** - a response without a next continuation token is ambiguous: YouTube omits it both when the chat is over and when it rotates the token, which typically happens at go-live. The worker therefore drops the cached token and bootstraps a fresh one from the embed page; only a **second consecutive** response without a token ends the task. Any response that does carry a token restores the full re-bootstrap budget, so a later rotation is recovered as well. The explicit chat-ended event remains the unambiguous terminal signal.
5. **Poll failures** - when the InnerTube failure threshold is reached (3 failures within 60 s), the cached continuation is discarded together with its Redis entry, so the next iteration re-bootstraps instead of replaying a token YouTube keeps rejecting.

The Redis continuation entry is deleted on every terminal path - chat ended, no token after a re-bootstrap, and the failure threshold. A respawned task therefore never resumes a dead token.

InnerTube is unauthenticated for chat reception - no OAuth token required.

### Broadcast Discovery

Broadcast discovery runs independently of chat reception:

1. **Primary: InnerTube `browse` endpoint** - Queries `youtubei.googleapis.com/youtubei/v1/browse` for the channel's public Streams tab. Current `lockupViewModel` entries identify live broadcasts by the `…_LIVE` badge style and scheduled broadcasts by the badge text `Upcoming`; the request pins `hl=en` and UTC. The parser also accepts legacy `videoRenderer` entries. **0 Data API quota.** The response supplies video IDs, titles, available viewer counts, and scheduled times, but no `liveChatId`. Unlisted and private broadcasts are not discovered here.
2. **liveChatId resolution** - For broadcasts without a known chat ID, the worker calls Data API v3 `liveBroadcasts.list?part=snippet,status&id=…` (1 unit per call, up to 50 IDs). Known IDs from tracked streams or `channel_status` are reused. An unresolved ID is retried after at least 10 minutes; API errors use a separate backoff. The Data API's `scheduledStartTime` takes precedence over the time parsed from the Streams tab. An upcoming broadcast still appears on the dashboard without a chat ID, but has no reader task or Multichat dropdown entry until the ID resolves. A live broadcast waits for its ID before publication.
3. **Fallback: Data API v3** - If InnerTube browse fails entirely, the worker lists `active` and `upcoming` broadcasts separately, with pagination. This path is gated by `rest_fallback_enabled` and costs at least 2 units per discovery cycle.

The ignored `innertube_smoke` test checks public Streams-tab discovery against live YouTube responses. It reports each channel's live and upcoming counts and upcoming video IDs. Supply additional channel IDs through `SMOKE_YOUTUBE_CHANNELS=UC…,UC…` when checking a specific channel:

```sh
SMOKE_YOUTUBE_CHANNELS=UC1234567890123456789012 cargo test -p lo-youtube-api --test innertube_smoke -- --ignored --nocapture
```

### InnerTube Credential Rotation

InnerTube requests need YouTube's current WEB-client API key and client version. Lumio resolves both through the same centralized resolver:

1. **Override** - `api_key_override` / `client_version_override`, only when an operator intentionally pins a value.
2. **Redis** - cached values from the shared refresher worker.
3. **Scrape** - fresh `youtube.com` scrape; successful results are written back to Redis.
4. **Compiled constant** - cold-boot last resort from `lo_youtube_api::innertube`.

The override layer is a deliberate pin. When either override is non-empty, Redis and scrape-based auto-rotation are bypassed for that value until the override is removed.

**Redis keys:**

| Key | Shape | TTL |
|-----|-------|-----|
| `lumio:yt:innertube_key` | JSON string with the last scraped InnerTube API key | 24 h |
| `lumio:yt:innertube_version` | JSON string with the last scraped InnerTube client version | 24 h |
| `lumio:yt:innertube_refresh:leader` | `SET NX` leader lock for the shared refresher replica | ~90% of `refresh_interval_secs` |
| `lumio:yt:continuation:{account_id}:{live_chat_id}` | next-poll continuation token for one active chat | 1 h |

The shared `innertube_credentials` worker runs once on API startup and then every `refresh_interval_secs` (default 21 600 s / 6 h). One API replica wins the Redis leader lock per interval, scrapes `youtube.com`, refreshes both credential keys, and logs value changes. The 24 h credential TTL is intentionally longer than the refresh interval, so normal account workers read warm Redis entries instead of scraping independently.

**Keeping the cold-boot layer fresh.** The compiled constant and the
`youtube.innertube_observer.*_cold_boot` seed in `apps/api/config/default.toml`
only matter when override, Redis and scrape all miss - but a stale value there
turns a cold boot into a failed one. The `InnerTube Drift Check` workflow
(`.github/workflows/innertube-drift-check.yml`) runs daily, compares both
checked-in values against live `youtube.com`, and on drift force-pushes the
bump onto a single `next`-based branch, `chore/innertube-drift-bump`. It never
writes the `*_override` pins.

The branch - not a pull request - is that workflow's deliverable. GitHub
Actions cannot open pull requests in this organization, because the setting
that would allow it also lets workflows *approve* pull requests. So the job
refreshes an already-open drift PR when one exists, and otherwise posts a
one-click compare link to its job summary and to the InnerTube Discord channel
for a maintainer to open. A scrape failure still fails the job loudly.

If Redis or scraping fails, the system fails open: account workers still try their own scrape and then fall back to the compiled constant. If an InnerTube poll returns a credential-rotation error (`400` or `403`, excluding `quotaExceeded`), the stream task bypasses Redis, force-scrapes both values, writes fresh hits back to Redis, and retries the poll exactly once. If the fresh scrape returns the same values that just failed, the retry is skipped and the task falls through to the normal InnerTube failure counter; there is no hot retry loop against `youtube.com`.

**Discovery intervals:**

| State | Interval |
|-------|----------|
| Idle (no active broadcasts) | 60 s |
| Active (broadcasts running) | 60 s |

InnerTube costs 0 quota, so frequent polling is safe. Each cycle refreshes viewer counts, likes, total views, and detects new or ended broadcasts.

### Badge + Emote Enrichment

Member badge images and channel-custom emotes are extracted inline from InnerTube chat responses - no separate observer is needed:

- **Member badges** - Each message's `authorBadges` array is parsed for custom-thumbnail badges. The badge image URL and tier label are stored in the `MembershipBadgeCache` (LRU + Redis) and attached to rendered messages.
- **Channel emotes** - Custom emojis with a `channelId/emoteId` pattern are extracted from emoji renderers and upserted into the durable [emote catalog](../developer-guide/emote-catalog.md) via `EmoteCatalog::upsert`. Rows are keyed on the broadcaster whose chat the emote appeared in, with the hosting channel kept in `owner_id`.

### Broadcast Statistics

The worker fetches like counts and total view counts via InnerTube endpoints at **0 quota cost**, once per 60-second discovery cycle per live broadcast:

- **`updated_metadata` endpoint** - Current like count per broadcast
- **`player` endpoint** - Lifetime view count per broadcast

These are stored in `channel_status` (`like_count`, `total_views`) and displayed on the dashboard and popout viewer badge.

#### InnerTube proxy pool

These two endpoints - and only these two - are routed through a pool of
Lumio-operated **InnerTube proxy** hosts when one is configured. The proxy is the
Rust binary in `apps/innertube-proxy`, shipped as a ghcr container and run on a
**trusted (non-datacenter) IP**: YouTube's `player` endpoint answers
`LOGIN_REQUIRED` from datacenter *and* Cloudflare-edge IPs alike, so the request
has to originate somewhere YouTube trusts. Chat polling, `browse` discovery and
the credential scrape do **not** go through the proxy.

Failover lives in the API, not in front of the hosts:

- The pool (`InnerTubeProxy` in `crates/lo-youtube-api/src/innertube/browse.rs`) holds an ordered host list, one shared bearer token, and a sticky `last_good` index.
- A request starts at `last_good` and rotates forward through the list until a host answers usefully. The host that answers becomes the new sticky start, so a dead host is skipped on later calls with no background health-check and no load balancer.
- Failover triggers on a transport error, a non-2xx status, **or** a `LOGIN_REQUIRED`-shaped body. Only `player` responses carry `playabilityStatus`, so `updated_metadata` bodies are never misclassified.
- When every host fails, the call returns nothing and the statistic falls through to the channel-feed fallback below.

The two transports use different route spellings: the proxy exposes `/player`
and `/updated-metadata` (hyphenated), while a direct call uses
`youtubei/v1/player` and `youtubei/v1/updated_metadata` (underscored). Proxied
requests authenticate with `Authorization: Bearer <token>`; direct requests
instead send browser-shaped `User-Agent`, `Accept-Language`, `Origin` and
`Referer` headers.

With no proxy configured the API calls YouTube directly - the normal local-dev
setup, where the statistics endpoints may return nothing from a datacenter IP.

#### Channel-feed fallback

Both InnerTube endpoints are undocumented and fail silently: any change to their response shape yields `None`, which would write `NULL` and make the badge disappear. A second, quota-free source covers that gap - the public channel Atom feed at `https://www.youtube.com/feeds/videos.xml?channel_id={YT_CHANNEL_ID}`, whose entries carry a `media:community` block:

```xml
<media:community>
  <media:starRating count="41" average="5.00" min="1" max="5"/>
  <media:statistics views="603"/>
</media:community>
```

`starRating count` is the like count; `statistics views` is the cumulative view count (**not** concurrent viewers - those keep coming from broadcast discovery). The sibling `average` has been a constant `5.00` since YouTube removed public dislikes and is ignored.

Rules the worker applies (`ChannelFeedCache` in `apps/api/src/workers/youtube.rs`):

- **InnerTube stays primary.** The feed is consulted only for a value InnerTube did not deliver; when both numbers are present no request is made at all.
- **One GET per channel, at most every 15 minutes.** YouTube serves the feed with `cache-control: public, max-age=900`, so a faster cadence would only re-read the same edge-cached bytes. It can never replace the 60-second InnerTube poll.
- **Matched strictly on `videoId`.** Uploads, Shorts and live broadcasts share the same 15-entry feed, so "newest entry" is not necessarily the stream.
- **Also covers non-live broadcasts.** Upcoming broadcasts and premieres never hit InnerTube, so the feed is their only statistics source.
- **Early warning.** A fill happening at all means InnerTube returned nothing where the public feed has a number - the earliest signal that an InnerTube path changed. The worker logs it per fill.
- **Retries a partial outage on fresh connections.** YouTube's feed servers sometimes answer `404` on some connections and serve the feed on others; a kept-alive connection repeats its first answer, a new one is a new draw. The feed therefore uses its own client without connection pooling, and a `404` or `5xx` is retried up to 4 requests in total within one fetch. Transport errors, other statuses and unparseable bodies are not retried.
- **Degrades quietly when the feed is down.** A fetch whose last request still fails (YouTube then serves a generic HTML error page instead of Atom) or an unparseable body keeps the previous snapshot and is retried only after the 15-minute interval. Only the first failure of a run logs a warning, the recovery logs once at info, and repeats stay at debug, so a feed that stays down does not log once per channel every 15 minutes (YouTube served `404`/`500` for every channel for several hours on 2026-10-05, and from 2026-10-12 on answered most requests with `404` - per channel between none and about 40 % of fresh connections still got the feed). The feed is undocumented and best-effort; a channel it does not serve simply keeps whatever InnerTube delivers. Every attempt counts into `youtube_channel_feed_fetches_total{outcome}` (see [Metrics](../developer-guide/metrics.md)) - `http_error` with no `ok` means YouTube stopped serving the feed.


The feed needs no authentication and no PubSubHubbub subscription; it is a plain scheduled GET (see [Webhooks](./webhooks.md#youtube-pubsubhubbub)). A live smoke test guards the assumptions:

```sh
cargo test -p lo-youtube-api --test channel_feed_smoke -- --ignored --nocapture
```

### Multi-Stream Support

YouTube allows multiple simultaneous live streams per channel. The worker manages them all:

1. **Discovery** finds all active and upcoming broadcasts.
2. A separate **stream task** is spawned per broadcast that has a `liveChatId` (each with its own InnerTube continuation state). A scheduled broadcast without a chat ID is still recorded for the dashboard.
3. Task lifecycle is managed per-broadcast: new → spawn, ended → cancel.
4. Every discovery cycle **refreshes the tracked state** - broadcast status, title, and scheduled start - for broadcasts that already have a task. A broadcast keeps its `videoId` when it goes live, so the status a task was spawned with would otherwise stay frozen for the task's whole lifetime.
5. Active streams are stored in Redis at `lumio:youtube:active_streams:{account_id}` (TTL 120 s) for the frontend.

**The `upcoming` → `live` transition** is therefore visible everywhere the tracked state is published, within one discovery cycle:

- `youtubeActiveStreams` (GraphQL and REST) reports `live`, which is what the chat send path needs to resolve a `liveChatId`.
- The Multichat stops rendering the broadcast as a waiting room.
- When the broadcast later disappears, the cleanup branch sees `live` and archives the `channel_status` row as offline. Rows are only deleted for broadcasts that disappear while still `upcoming` - a cancelled or rescheduled premiere.

A scheduled start is carried over as long as discovery reports one, and cleared once the broadcast is no longer `upcoming`.

Messages from all streams appear together in the Multichat.

Scheduled broadcasts with a `liveChatId` have a pre-stream **waiting-room chat**. The worker spawns a reader task for that chat just like a live one. Outgoing sends and moderation also target it: when no broadcast is `live` yet, `liveChatId` resolution falls back to the single open `upcoming` waiting-room chat (a `live` broadcast always takes precedence). A scheduled broadcast without a chat ID remains visible on the dashboard while its chat ID is retried.

## Configuration

All settings live in the `[youtube]` section of `config/*.toml` or as environment variables.

| Setting | ENV override | Default | Description |
|---------|-------------|---------|-------------|
| `grpc_fallback_enabled` | `LUMIO__YOUTUBE__GRPC_FALLBACK_ENABLED` | `false` | Enable gRPC streamList as fallback when InnerTube fails |
| `rest_fallback_enabled` | `LUMIO__YOUTUBE__REST_FALLBACK_ENABLED` | `false` | Enable REST polling as fallback when gRPC also fails; also gates Data API broadcast discovery fallback |
| `innertube_proxy_urls` | `LUMIO__YOUTUBE__INNERTUBE_PROXY_URLS` (comma-separated) | _(empty)_ | Ordered list of InnerTube proxy hosts for the `player` + `updated_metadata` endpoints |
| `innertube_proxy_url` | `LUMIO__YOUTUBE__INNERTUBE_PROXY_URL` | _(unset)_ | Single-host alias, folded into the resolved host list. Prefer `innertube_proxy_urls`. |
| `innertube_proxy_token` | `LUMIO__YOUTUBE__INNERTUBE_PROXY_TOKEN` | _(unset)_ | Shared bearer token presented to every host in the pool |

The two URL settings are merged into one deduplicated, order-preserving list
(`innertube_proxy_urls` first, then `innertube_proxy_url`); blank entries are
dropped. The pool is only built when the resolved list is non-empty **and** a
token is set - configuring one without the other logs a warning and leaves the
proxy disabled. Duplicate entries are collapsed with a warning.

The `[youtube.innertube_observer]` subsection controls badge caching and InnerTube credentials:

| Setting | ENV override | Default | Description |
|---------|-------------|---------|-------------|
| `api_key_override` | `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__API_KEY_OVERRIDE` | _(empty)_ | Emergency pin for the InnerTube API key; disables auto-rotation for the key while set |
| `client_version_override` | `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__CLIENT_VERSION_OVERRIDE` | _(empty)_ | Emergency pin for the InnerTube client version; disables auto-rotation for the version while set |
| `refresh_interval_secs` | `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__REFRESH_INTERVAL_SECS` | `21600` | Shared credential refresher interval (6 h) |
| `cache_ttl_seconds` | `LUMIO__YOUTUBE__INNERTUBE_OBSERVER__CACHE_TTL_SECONDS` | `1209600` | Member + tier-badge Redis entry TTL (14 d) |

The `liveChatId` resolution via Data API (`liveBroadcasts.list`) is always permitted regardless of `rest_fallback_enabled`; an unresolved ID is retried after at least 10 minutes.

## API Surface

| Protocol | Operation | Permission |
|----------|-----------|------------|
| GraphQL | `youtubeActiveStreams` - live + upcoming broadcasts with a chat ID for the account | `chat:read` |
| REST | `GET /v1/youtube/active-streams` - same Redis-backed list | `chat:read` |
| GraphQL | `youtubeMembershipTiers` - the channel's membership tiers | see [Memberships](./memberships.md) |
| REST | `GET /v1/youtube/memberships/tiers` | see [Memberships](./memberships.md) |

There is no YouTube-specific WebSocket channel type. Chat messages and events
reach clients on the shared `chat:{account_id}` stream (`chat:read` +
`feature:multichat`) and `events:{account_id}` (`events:read`).

Neither active-streams operation carries a feature gate; both read the same
Redis-backed tracked state (`lumio:youtube:active_streams:{account_id}`) that
discovery publishes.

## Events Supported

### Chat + Moderation

| Event type | Description |
|------------|-------------|
| `TEXT_MESSAGE_EVENT` | Regular chat message |
| `TOMBSTONE` | Silent removal (no-op) |
| `MESSAGE_DELETED_EVENT` | Message deleted - marked in DB, broadcast via WebSocket |
| `MESSAGE_RETRACTED_EVENT` | Message retracted - same handling as deleted |
| `USER_BANNED_EVENT` | User banned - moderation log entry with ban type and duration |

### Monetization

| Event | Lumio event type | Key fields |
|-------|-----------------|------------|
| `SUPER_CHAT_EVENT` | `youtube:superchat` | `amount_micros`, `currency`, `amount_display_string`, `user_comment`, `tier` |
| `SUPER_STICKER_EVENT` | `youtube:supersticker` | Same + flat `stickerName` (sticker name, both ingest paths) and `stickerUrl` (image, InnerTube path only); the gRPC/REST path also keeps nested `superStickerMetadata` (`stickerId`, `altText`) |

### Membership

| Event | Lumio event type | Key fields |
|-------|-----------------|------------|
| `NEW_SPONSOR_EVENT` | `youtube:member` | `member_level_name`, `is_upgrade` |
| `MEMBER_MILESTONE_CHAT_EVENT` | `youtube:member` | `member_level_name`, `member_month`, `user_comment` |
| `MEMBERSHIP_GIFTING_EVENT` | `youtube:gift_membership` | `gift_memberships_count`, `gift_memberships_level_name` |
| `GIFT_MEMBERSHIP_RECEIVED_EVENT` | `youtube:gift_membership_received` | `member_level_name`, `gifter_channel_id` |

Gift memberships use the same bundling pattern as Twitch gift subs: the header `gift_membership` event collects recipient names from individual `gift_membership_received` events, then broadcasts with a `giftRecipients` list. Individual received events are stored in DB but excluded from the event panel via `exclude_bundled`.

### Interactive

| Event | Lumio event type | Key fields |
|-------|-----------------|------------|
| `POLL_EVENT` (gRPC), `showLiveChatActionPanelAction` / `updateLiveChatPollAction` / `closeLiveChatActionPanelAction` (InnerTube) | `youtube:poll` | `raw.poll_id`, `raw.status`, `raw.question`, `raw.options[]` |

`youtube:poll` is live-only: it is broadcast on the account events channel and never written to the event history. YouTube reports a running poll again on every vote change, so the worker sends one frame per update and a final frame with `status: "closed"`; there is no separate end event.

Every frame is a full stream event (`id`, `account_id`, `platform: "youtube"`, `type`, `created_at`, `raw`). All frames of one poll share the same `id` and `created_at`, so the dashboard chat shows **one row per poll** and treats vote updates as duplicates, the Events page updates its poll row in place, and the alert box keeps its live tally from every frame. All three read the poll through `apps/web/src/lib/youtube-poll.ts` (`readYouTubePoll`), which turns `tally` into vote counts and shares and falls back to `vote_ratio` when there are no counts. A new poll in the same stream gets a new `id`. The identity is kept in the stream task's memory: InnerTube polls are keyed on YouTube's `liveChatPollId`, gRPC polls (which carry no poll id) on the question, since YouTube runs one poll at a time.

Both transports produce the same `raw` shape:

| Field | Value |
|-------|-------|
| `poll_id` | InnerTube `liveChatPollId`; the event `id` when the transport has none |
| `status` | `active`, `closed` or `unknown` |
| `question` | Poll question as plain text |
| `options[]` | `{ option_text, tally, vote_ratio }` - gRPC reports `tally` (vote count), InnerTube reports `vote_ratio` (0 to 1); the other is `null` |

The frame carries the poll only in `raw`; there are no top-level copies of `status`, `question` or `options`, and the raw InnerTube action is not forwarded. An InnerTube action panel that is not a poll, or a close for a poll the stream task never saw open, publishes nothing.

## Chat Sending + Moderation

Chat sending and moderation use the **user's login OAuth connection** (not the channel connection). InnerTube is read-only.

| Operation | Endpoint | Token source |
|-----------|----------|-------------|
| Send message | `POST /youtube/v3/liveChat/messages` | `get_provider_token("google")` |
| Ban / timeout | `POST /youtube/v3/liveChat/bans` | `get_provider_token("google")` |
| Delete message | `DELETE /youtube/v3/liveChat/messages?id={message_id}` | `get_provider_token("google")` |

All OAuth tokens are managed by the centralized Token Refresh Worker.

## Quota Impact

| Operation | Units | Frequency |
|-----------|-------|-----------|
| **InnerTube chat polling** | **0** | Per poll interval (~3 s per active stream) |
| **InnerTube broadcast discovery** | **0** | Every 60 s |
| **InnerTube statistics (likes, views)** | **0** | Every 60 s per broadcast |
| liveChatId resolution (Data API) | 1 per call (up to 50 IDs) | For broadcasts without a known ID; unresolved IDs retry after at least 10 min |
| REST broadcast discovery fallback | At least 2 | Every 60 s, one page each for `active` and `upcoming` (only when InnerTube fails + `rest_fallback_enabled`) |
| Chat sending | 200 | Per message sent |
| Moderation action | 200 | Per action |
| Channel enrichment | 1 | On demand, cached |

## Key Files

| File | Purpose |
|------|---------|
| `crates/lo-youtube-api/src/innertube/mod.rs` | InnerTube `get_live_chat` polling + API key/continuation bootstrap |
| `crates/lo-youtube-api/src/innertube/parser.rs` | Parse `get_live_chat` responses into `InnerTubeChatEvent` variants |
| `crates/lo-youtube-api/src/innertube/events.rs` | `InnerTubeChatEvent` enum definition |
| `crates/lo-youtube-api/src/innertube/browse.rs` | InnerTube browse (broadcast discovery, viewer counts, likes) + `InnerTubeProxy` pool and failover |
| `apps/innertube-proxy/` | Rust InnerTube proxy binary (`/player`, `/updated-metadata`), run on a trusted IP |
| `crates/lo-youtube-api/src/innertube/scraper.rs` | Scrape API key + client version from `youtube.com` |
| `apps/api/src/services/innertube_credentials.rs` | Central API key + client version resolver, Redis persistence, one-shot rotation retry |
| `apps/api/src/workers/innertube_credentials.rs` | Shared 6 h credential refresher worker |
| `crates/lo-youtube-api/src/streaming.rs` | gRPC streamList client (fallback) |
| `crates/lo-youtube-api/src/client.rs` | REST Data API v3 client (fallback + moderation) |
| `apps/api/src/workers/youtube.rs` | Multi-stream worker: broadcast discovery, per-stream task lifecycle, InnerTube chat loop |
| `apps/api/src/workers/youtube_poll.rs` | `youtube:poll` envelope, per-poll identity tracker, InnerTube poll normalisation |
| `apps/api/src/graphql/youtube.rs` | `youtubeActiveStreams` GraphQL query |
| `apps/api/src/routes/youtube_streams.rs` | `GET /v1/youtube/active-streams` REST endpoint |
| `apps/api/src/graphql/channel_status.rs` | `channelStatus` query (includes `broadcastStatus`, `likeCount`, `totalViews`, `scheduledStart`, `liveChatId`) |
| `apps/web/src/hooks/use-youtube-streams.ts` | Frontend hook polling active streams |
| `apps/web/src/app/(main)/(app)/dashboard/chat/multichat.tsx` | Broadcast sub-menu + reply context |

---

## Features / Extensions

Source: https://docs.lumio.vision/features/extensions

# Extensions

Extensions add features to Lumio accounts: widgets for overlays, bot modules for chat moderation, automation nodes, themes, and integrations. They are discovered and installed from the Extension Store.

## Visibility levels

| Visibility | Description |
|------------|-------------|
| `system` | Built-in extensions maintained by Lumio. Always available, cannot be uninstalled. |
| `public` | Community extensions published by verified developers. Anyone can install them. |
| `paid` | Community extensions with a price. Purchase required to install. |
| `unlisted` | Not shown in Store search. Installable via direct link. |
| `private` | Hidden from public discovery. A published extension is installable only by an account with an access grant or an invited tester. |

Developers can set `private`, `unlisted`, `public`, or `paid`. The `system` value and the `system-` slug prefix are reserved for Lumio's built-in extensions. Create and update requests reject other visibility values and developer slugs beginning with `system-` (case-insensitive). A developer- or team-owned extension that already carries `system` visibility or a `system-` slug is never treated as a built-in extension. The API logs a warning for each such extension at startup so an operator can review it; the check does not change the extension.

## Installation

REST and GraphQL install requests require a published extension. Public, paid, unlisted, and system extensions can pass the visibility check; private extensions additionally require an access grant for the installing account or a tester invitation for the acting user. Payment and account permissions still apply where required. An extension that does not pass this check returns `404 Extension not found`. Revoking a private access grant also prevents reinstalling through that grant.

Buying a paid extension (`POST /v1/extension-purchases`) runs the same check before a Stripe Checkout session is created, and before the free-access shortcut installs. An account that cannot install the extension gets `404 Extension not found` and is not sent to payment. When Stripe reports the completed payment, the API checks again before it installs the extension. If the check fails at that point, for example because the access grant was revoked after checkout, the payment is recorded but the extension is not installed. The same applies when the extension or its version is deleted or unpublished while the buyer is still on the Stripe page: the payment is recorded without the deleted extension or version and nothing is installed. In both cases Lumio refunds the full amount automatically, right when the payment is reported; a subscription is cancelled at once, without proration, and its first payment is refunded. The purchase then shows as `refunded`. Lumio also e-mails the buyer that the extension was no longer available and that the full amount was refunded, because Stripe sends its own receipt only when that is enabled in the Stripe Dashboard. A payment that is not installed because of a temporary error is not refunded automatically. A recorded purchase does not give access to a private extension. A paid checkout also requires the buyer's withdrawal-waiver declaration (`accept_withdrawal_waiver: true`, text B for one-time purchases, text C for subscriptions) and sends an order confirmation after payment; see [Billing → Withdrawal waiver and order confirmation](./billing.md#withdrawal-waiver-and-order-confirmation). Purchase is available only over REST: checkout ends in a redirect to Stripe and a signed webhook, so there is no GraphQL mutation for it.

Draft and testing versions can be inspected by their developer, but an extension must have published status before the install endpoint accepts it.

Installing an extension the account already has returns `409 Extension is already installed` (GraphQL: `Extension is already installed`).

## Uninstalling and reinstalling

Uninstalling (`DELETE /v1/extension-installs/{id}`, GraphQL `uninstallExtension`) takes the extension off the account at once. Its widgets, overlay layers and bundled sounds are deleted. The install no longer appears in install lists, the store's installed badge, or install lookups. Its functions, actions and storage answer `Extension install not found`, and bots and workers stop running its handlers and triggers.

By default the extension's stored data is kept for 30 days and deleted afterwards; `delete_data_immediately` deletes it right away. Deleting the data only ever removes this account's data: an extension keeps one database schema for every account that installs it, so uninstalling deletes this account's rows from it, and the schema itself is removed only with the extension's last install. Every uninstall is recorded in the account's audit log as `account:extension_uninstalled`, including whether the data was deleted immediately. Installing the same extension again within those 30 days restores the install on the latest published version, with its saved configuration and stored data. Update settings start fresh (auto-update on, no pinned version), and widgets, overlay layers and sounds that were deleted at uninstall are not restored. Built-in system extensions cannot be uninstalled, and Lumio's automatic system-extension setup never restores an install that was uninstalled.

## System extensions

System extensions replace the former built-in plugin system. They provide the same functionality (chat moderation modules, overlay widgets) but run through the standard extension infrastructure (V8 isolates, Extension Supervisor iframes).

### Built-in widgets

| Extension | Slug | Default Install | Description |
|-----------|------|-----------------|-------------|
| Chat Box | `system-chat-box` | Yes | Live chat feed from connected platforms |
| Alert Box | `system-alert-box` | Yes | Animated alerts for follows, subs, raids |
| Event List | `system-event-list` | Yes | Scrolling list of recent events |
| Text | `system-text` | Yes | Labels, titles, and text overlays |
| Image | `system-image` | Yes | Upload or URL-based image overlays |
| Timer | `system-timer` | Yes | Countdown / stopwatch timer |
| Spotify Now Playing | `system-spotify-now-playing` | No | Displays the currently playing Spotify track |
| Browser Source | `system-obs-browser-source` | No | Headless OBS integration events |

### Built-in bot modules

| Extension | Slug | Default Install | Description |
|-----------|------|-----------------|-------------|
| Link Protection | `system-link-protection` | Yes | Block or filter URLs in chat |
| Spam Protection | `system-spam-protection` | Yes | Detect excessive caps, symbols, emote spam |
| Word Filter | `system-word-filter` | Yes | Block banned words, phrases, or regex patterns |
| Timed Messages | `system-timed-messages` | Yes | Send messages on a rotating schedule |

### Properties

- `visibility = 'system'`
- No developer or team owner (`developer_id` and `team_id` are NULL)
- System-extension lookups require both owner fields to be NULL as well as the reserved slug, so developer-owned extensions are not selected as built-ins.
- Always free (`pricing_type = 'free'`)
- Cannot be uninstalled (can be disabled via config)
- Cannot be deleted by users or developers
- 10 of 12 are auto-installed for new accounts on creation
- `lumio.config.json` is the single source of truth - the API reads each manifest at compile time via `include_str!` (no hardcoded Rust structs)
- All manifests include an `icon` field (Lucide icon name)
- In local dev, bundles are uploaded from the filesystem; in production, deployed via CI (`lumio deploy --system`)

## Config schema

The `config_schema` field in `lumio.config.json` defines user-facing settings. The `SchemaEditor` component auto-generates a settings panel from this schema. `CONFIG_FIELD_TYPES` in `packages/extension-types/src/config.ts` defines the 18 supported field types:

| Type | Description |
|------|-------------|
| `string` | Single-line text input |
| `number` | Numeric input |
| `boolean` | Toggle switch |
| `color` | Color picker with hex input |
| `select` | Dropdown with predefined options |
| `textarea` | Multi-line text input |
| `slider` | Range slider with min/max/step |
| `font` | Font family picker (Google Fonts catalog) |
| `icon` | Icon picker (Lucide, emoji, emotes, uploads) |
| `image` | Image upload or URL |
| `sound` | Sound file upload or URL |
| `multiselect` | Multiple selection from options |
| `group` | Collapsible group of nested fields |
| `divider` | Visual separator |
| `info` | Read-only informational text |
| `channel` | Multi-platform channel picker |
| `designer` | Fullpage designer surface field |
| `presets` | Selectable preset bundles that write several other fields at once |

### Field properties

| Property | Applies to | Description |
|----------|------------|-------------|
| `label` | All | Display label |
| `default` | All value types | Default value |
| `required` | All value types | Validation requirement |
| `min` / `max` / `step` | `slider`, `number` | Numeric range constraints |
| `placeholder` | `string`, `textarea` | Input placeholder text |
| `rows` | `textarea` | Number of visible rows |
| `unit` | `slider` | Unit suffix (e.g. "px", "ms") |
| `collapsed` | `group` | Start collapsed |
| `visible_when` | All | Conditional visibility based on other field values |
| `fields` | `group` | Nested child field definitions |
| `content` | `info` | Informational text content |
| `options` | `select`, `multiselect` | Available options array |
| `multiple` | `multiselect` | Allow multiple selections |
| `presets` | `designer`, `presets` | Predefined preset configurations |

A separate `designer_schema` array in `lumio.config.json` defines fields for the fullpage designer surface.

### Server-side validation

Config values are validated against the `config_schema` before writing to `extension_installs.config`. Validates type match, required fields, select options, color hex format, slider range bounds, and rejects unknown keys. Both GraphQL and REST enforce validation.

## Widget editor

An extension widget instance is bound to a live installation of that extension in the active account. The instance takes its extension identity from the installation; an installation from another account or one already uninstalled cannot be used. Each widget has its own access grants: no grant, `viewer`, and `editor` allow it in the widget list; `none` hides it. Copying requires Editor access to the source and `widgets:create`. `widgets:access-read` lets an account member see every widget but does not grant copy access; `widgets:access-grant` bypasses the per-widget copy check.

Two rendering paths produce the same `@lumio/ui` components:

1. **config_schema** -- The host-side `SchemaEditor` component auto-generates form fields directly from the schema definition
2. **editor.tsx** -- SDK Editor Components (EditorInput, EditorTextarea, EditorSelect, EditorCheckbox, EditorSlider, EditorColorPicker, EditorGroup, EditorLabel, EditorDivider, EditorInfo, EditorFontRow, EditorButton) serialize via the Worker Reconciler and render as `@lumio/ui` on the host

Extensions can use config_schema only, editor.tsx only, or both (schema fields render first, custom editor below).

### Advanced settings

The `AdvancedSettings` panel provides:

- **Layout**: Width, height, rotation, optional X/Y positioning
- **Appearance**: Opacity
- **Corner Radius**: Linked (all corners) or individual per-corner control
- **Effects**: Text shadow, layer blur, background blur
- **Strokes**: Border styling
- **Custom CSS**: Fullpage Monaco Editor modal

### Extension designer

The `ExtensionDesigner` is a fullpage overlay with a split pane (preview + settings). It supports both `designer_schema` (host-side form from `lumio.config.json`) and `designer.tsx` (Worker pipeline via SDK Editor Components).

## Font proxy

DSGVO-compliant font serving through Lumio infrastructure. No browser requests go to Google.

| Endpoint | Description |
|----------|-------------|
| `GET /v1/fonts/{family}/css` | CSS stylesheet with `@font-face` rules pointing to self-hosted woff2 URLs |
| `GET /v1/fonts/{family}/{weight}.woff2` | Proxied font file, cached via `lo-storage` |

Both endpoints are public scope (no auth required) with immutable cache headers.

## Store integration

System extensions appear in the Store alongside community extensions:

- **Category filter:** Top-3 category chips (All, Built-in, Widgets) plus a "More" dropdown for remaining categories. Sort by Popular, Recent, or Top Rated.
- **Built-in filter:** A dedicated "Built-in" category shows all system extensions across categories, sorted before community extensions.
- **Installed badge:** Each card shows a green corner check-mark when the extension is already installed on the current account.
- **Detail page:** Shows "Built-in by Lumio" instead of a developer panel, with category badge, Lucide icon, and install/uninstall actions.
- **Pagination:** Load More button fetches the next 20 results.
- **Install:** Normal install flow. System extensions cannot be uninstalled.
- **Icons:** An `icon_key` that names a Lucide icon (all system extensions) renders that icon without a request. An uploaded icon loads through the dashboard proxy `/api/extensions/{slug}/icon`, which serves only store-visible extensions (`icon-data` below). Drafts and private extensions therefore show their letter placeholder in the store, the installed list, the developer's extension list and overview, the bot-module list and the widget picker, never a broken image.

## Bundle files

Bundle files support JavaScript, CSS, HTML, source maps, raster images, SVG, fonts, media, JSON, and Lottie. Every served file has `X-Content-Type-Options: nosniff`. HTML, SVG, JSON, source maps, Lottie, and other non-passive content also have `Content-Security-Policy: sandbox` and `Content-Disposition: attachment`; the dashboard bundle proxy applies the same headers. SVG can still be loaded as an image resource.

## Discovery API

| Endpoint | Description |
|----------|-------------|
| `GET /v1/extensions?visibility=system&category=widget` | List system widget extensions |
| `GET /v1/extensions?visibility=system&category=bot_module` | List system bot module extensions |
| `GET /v1/extensions/{slug}` | Store detail for one extension |
| `GET /v1/extensions/{slug}/reviews` · `POST /v1/extensions/{slug}/reviews` | Read / write store reviews |
| `GET /v1/extension-installs` · `POST /v1/extension-installs` · `DELETE /v1/extension-installs/{id}` | Per-account install lifecycle |
| `GET /v1/extension-installs/{install_id}/storage` · `POST …/storage` | Per-install extension storage (`useExtensionStorage()`) |
| `GET /v1/extension-installs/{id}/logs` | Per-install handler logs of a bot-module or automation-node install: `bot-modules:read` (bot module) or `automations:read` (automation node), resolved from the install's category; every rejection is `404 Install not found`. Messages are scrubbed; automation `inputData` is returned as shape only |
| `GET /v1/store/extensions/{slug}/icon` · `.../screenshots` | Store media assets |
| `GET /v1/store/extensions/{id}/icon-data` | Icon image bytes (PNG/JPEG/WebP) of a store-visible extension; every extension `icon_url` points here |
| `GET /v1/platforms/metadata` | Static platform info |
| `platformMetadata` (GraphQL) | Same as REST, public query |

### GraphQL counterpart

Every store operation is also a GraphQL field. All store fields combine the
`feature:extensions` flag with an `extension-store:*` permission;
`extensionInstallLogs` is gated by the install's category permission instead:

| Field | Kind | Permission |
|-------|------|------------|
| `storeExtensions` · `storeExtension` | Query | `feature:extensions` + `extension-store:read` |
| `installedExtensions` | Query | `feature:extensions` + `extension-store:read` |
| `extensionVersions` · `extensionReviews` · `extensionBundleUrl` | Query | `feature:extensions` + `extension-store:read` |
| `uninstallImpact` | Query | `feature:extensions` + `extension-store:uninstall` |
| `installExtension` | Mutation | `feature:extensions` + `extension-store:install` |
| `uninstallExtension` | Mutation | `feature:extensions` + `extension-store:uninstall` |
| `configureExtension` · `setExtensionAutoUpdate` · `pinExtensionVersion` | Mutation | `feature:extensions` + `extension-store:configure` |
| `extensionInstallLogs` | Query | `bot-modules:read` (bot-module install) or `automations:read` (automation-node install); same guard, redaction and `Install not found` error as REST |
| `reviewExtension` | Mutation | `feature:extensions` + `extension-store:review` |
| `extensionStorage` | Query | `feature:extensions` + `extension-store:read` (or the install's extension token, or an overlay/widget token that renders the install) |
| `setExtensionStorage` | Mutation | `feature:extensions` + `extension-store:configure` (or the install's extension token); overlay and widget tokens never write |

### WebSocket

| Channel | Gate | Feature flag |
|---------|------|--------------|
| `ext-storage:{install_id}` | The install's extension token, `extension-store:read` in the account that owns the install, or an overlay/widget token that renders the install - the read rule of `extensionStorage` and its REST twin | `feature:extensions` |
| `ext-logs:{extension_id}` | Extension owner (developer or team member) | `feature:extension_development` |
| `ext-install-logs:{install_id}` | `bot-modules:read` (bot-module install) or `automations:read` (automation-node install), resolved from the install's category like the GraphQL/REST twins | `feature:bot_module_extensions` |

---

## Admin / Abuse Reports

Source: https://docs.lumio.vision/admin/abuse-reports

# Abuse Reports

The Abuse Reports queue collects copyright abuse reports submitted by end users against a specific track. Admins triage each report and mark it **resolved** (the report was valid) or **rejected** (the report was spurious). Resolving a report also writes a global block for that track; rejecting it removes any block a prior resolution created.

## Where to find it

**Admin sidebar → Abuse Reports** (`/abuse-reports`).

## Quick start

1. Open **Admin → Abuse Reports**.
2. Filter by status using the tabs - default is **Pending**.
3. Read the **Reason** text and follow the **Proof** link, if provided.
4. Click **Resolve** to accept the report (and block the track globally), or **Reject** to dismiss it.
5. Check the **All** tab to audit past decisions.

## Detailed walkthrough

### Status filters

A tab bar at the top toggles between:

- **Pending** - default; unreviewed reports.
- **Resolved** - reports an admin accepted and acted on.
- **Rejected** - reports an admin dismissed as invalid.
- **All** - everything.

### Report rows

Reports render as cards, not table rows. Each card shows:

- **Song - Artist** - the reported track, as the card headline.
- **Reported by** - the reporter's display name and email address.
- **Reason** - free-text field the user submitted.
- **Proof** - optional URL (YouTube link, screenshot host, etc.). Rendered as a clickable link when present, passed through a URL sanitiser that only allows `http`/`https`.
- A status pill (`pending` / `resolved` / `rejected`).
- Submission timestamp.

**Resolve** and **Reject** buttons appear only on cards whose status is `pending`. Resolved and rejected cards are read-only - the resolving admin (`resolved_by`) and the `resolved_at` timestamp are stored but not rendered.

### Decision actions

Both **Resolve** and **Reject** call the same `PATCH` endpoint with a different `status` value, then refetch the list so the card moves to the matching tab.

Beyond flipping the status, the backend acts on the verdict:

- **Resolve** inserts a global block for the reported song / artist / Spotify track ID.
- **Reject** deletes the block again when the report carries a Spotify track ID, undoing a prior resolution.

## Common scenarios

- **Copyright false-positive** - user reports a song flagged as unsafe that they believe is actually safe; investigate on the Copyright Review page, then resolve the abuse report.
- **Coordinated report spam** - if multiple users submit near-identical reports against the same track, cross-reference with the song in the Copyright Reports queue before acting.
- **Bad-faith report** - reject with no action and the row moves to the **Rejected** tab for later audit.

## Permissions

| Action | Permission |
|--------|-----------|
| View reports (all statuses) | `support:read` |
| Resolve / reject a report | `support:edit` |

Dashboard entry requires `admin:access`. System admins (`is_system: true`) get every admin permission implicitly.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List abuse reports (filtered) | - (REST only) | `GET /v1/admin/abuse-reports?status={pending\|resolved\|rejected}` (omit `status` for all) |
| Submit an abuse report (user side; public, Turnstile `abuse`, 5 per IP and 100 in total per hour) | `submitAbuseReport` | `POST /v1/abuse-reports` |
| Resolve / reject a report | - (REST only) | `PATCH /v1/admin/abuse-reports/{id}` with `{ status: "resolved" \| "rejected" }` |

Abuse reports are a REST-only surface today - no GraphQL resolver is exposed.

## Tips & gotchas

- There is no "undo" button - once resolved or rejected, the buttons disappear from the card. Flipping a resolved report back to rejected (or the reverse) requires a direct `PATCH` against the endpoint.
- The **Proof** link is user-supplied and untrusted. Open it in an incognito window, never paste it into an authenticated tab.
- The UI does not surface how many times the reported entity has been reported previously. Cross-reference manually using [Copyright Reports](./copyright-reports.md).
- Closed reports are deleted automatically three years after they were resolved or rejected (`abuse_reports.retention_years`, see [Installation → Abuse report retention](../getting-started/installation.md#abuse-report-retention)). Pending reports are never deleted, however old.
- The list endpoint pages at 25 items by default (max 100 via `limit`); the UI reads only the first page and renders no pagination controls.

## Related

- [Copyright Reports](./copyright-reports.md) - user reports against specific tracks
- [Copyright Recommendations](./copyright-recommendations.md) - user suggestions that a track is safe
- [Audit Log](./audit-log.md) - full audit trail including support actions

---

## Admin / Accounts

Source: https://docs.lumio.vision/admin/accounts

# Accounts

The Accounts view is the per-account command centre for Lumio operators. It lets you browse every account in the system, drill into a single account to inspect its members and plan, override numeric/boolean limits, toggle feature-flag overrides, set user-scope permission overrides, and forcibly detach channel or bot connections when something goes wrong.

## Where to find it

**Admin sidebar → Accounts**. The list lives at `/accounts`; detail pages live at `/accounts/{id}`.

## Quick start

1. Open **Admin → Accounts** and search by account name or owner display name.
2. Click a row to open the account detail page.
3. Change the plan via **Plan Management** - the dropdown lists every plan defined on the [Plans](./plans.md) page - and click **Update Plan**.
4. Scroll to **Account Limits** to override plan defaults per field. Leave a field blank to fall back to the plan default.
5. Optionally open **Feature Overrides** to flip individual features ON/OFF for this account only.

## Detailed walkthrough

### Accounts list (`/accounts`)

- **Search** - debounced search against name and owner display name.
- **Columns** - Name, Owner, Plan (coloured badge), Members count, Created date.
- **Pagination** - 25 accounts per page, "Page X of Y (N accounts)" footer.
- **Row click** - navigates to `/accounts/{id}`.

### Account detail (`/accounts/[id]`)

The detail page stacks these cards:

1. **Account Information** - name (editable inline, requires `accounts:edit`; while the channel takes its name from a connection, the channel shows that connection's name and the next connection sync overwrites the edit), Account ID, Owner display name, Created/Updated timestamps. A **Delete Account** button (requires `accounts:delete`) opens a confirmation dialog before permanently deleting the account and all its data, including an uploaded channel picture.
2. **Plan Management** - current plan badge, a `<select>` populated from the live plan list, and an **Update Plan** button that stays disabled until the selection differs from the current plan. Plans also define a `max_accounts` field that limits how many accounts the plan owner can create. (The `enterprise` tier was dropped in migration `20260415000009_drop_enterprise_plan`; existing accounts were moved to Pro.)
3. **Members** - table of all users in the account showing Name (linked to `/users/{user_id}`), Email, Role, Owner flag, Joined date, Actions. **Add Member** (requires `accounts:edit`) opens a dialog that requires both a user ID and a role from this account. Roles load when the dialog opens; no role is preselected, and the Owner/system role is not offered. The Add button stays disabled until both fields are selected. The dialog reports a role-loading error or an empty assignable-role list. Each non-owner member row has a **Remove** button with a confirmation dialog.
4. **Account Limits** - per-account overrides for numeric and boolean plan limits. Fields: `max_overlays`, `max_widgets`, `max_storage_bytes`, `max_upload_size_bytes`, `max_integrations`, `chat_retention_days`, `max_setting_presets`, `custom_bot_allowed`, `obs_remote_allowed`, `copyright_detection_allowed`, plus a free-text **Notes** field. `max_setting_presets` is the per-user [setting-preset](../features/setting-presets.md) quota override (`0` = unlimited; blank inherits the plan) - because presets resolve to the best account a user can reach, raising it lifts every member of this account. The three boolean fields are tri-state dropdowns (plan default / Yes / No); empty numeric fields fall back to the plan default. **Save Limits** persists the whole form in one PUT, and the card shows the last-updated timestamp next to the button. An operator limit change emits the `system:account_limits_updated` audit event.
5. **Channel Connections** - table showing Platform, Channel Name, Connected Since, Actions. Actions per row (all gated on `accounts:edit`): **Disconnect** (with confirmation dialog) and a reconnect-flag toggle. When the reconnect flag is set, an amber warning icon appears next to the platform badge. See [Reconnect Flags](../features/connections.md#reconnect-flags) for what the flag does. Disconnecting the connection that is the channel's name/picture source switches the channel to its own details (the connection's last channel name, the initial as picture) and notifies the owner in-app - see [Channel name and picture](../features/accounts.md#channel-name-and-picture).
6. **Bot Connections** - same layout, showing Platform, Bot Type, Bot Username, Connected Since, Actions. Same actions: Disconnect and reconnect-flag toggle.
7. **Feature Overrides** - see below.
8. **Permission Overrides** - per-account overrides for user-scope permissions. See [User Roles](./user-roles.md#per-account-permission-overrides).

Extension dev mode is a **user**-scoped flag and has no account-scoped surface; set it from the [Users](./users.md) detail page, which is the surface wired to the API.

Disconnecting a connection is immediate: the backend row is removed and the encrypted token discarded; for YouTube the revenue data goes too. The account's chatter profiles, moderator notes, moderation and AutoMod logs, chat and events for that platform stay; they belong to the channel and follow plan retention until the channel is dissolved. The reconnect flag is non-destructive and can be toggled on and off; it forces the user to re-authorize without deleting the connection data.

### Feature Overrides card (`feature-overrides.tsx`)

Rendered below the account detail card stack. Each row is a feature flag with:

- **Feature** name.
- **Override** - `ON`, `OFF`, `Global OFF`, or unset.
- **Resolved** - the effective state after the plan and global kill-switch are applied.
- **Actions** - ON / OFF buttons to set an override, plus a clear action (DELETE on `/accounts/{id}/features/{feature_id}`) to remove the override and fall back to plan defaults.

### StreamElements tokens

The API exposes per-account StreamElements tokens (`GET` / `DELETE` under `/v1/admin/accounts/{id}/se-tokens`, GraphQL `adminSeTokens` / `adminDeleteSeToken`), but the shipped account detail page renders no SE-tokens card. Use the API directly, or the account owner's own StreamElements settings.

### Resolved limit overrides

A second PUT endpoint exists at `/v1/admin/accounts/{id}/resolved-limits` (GraphQL `adminSetAccountLimits`). It takes the same fields as the limits form but writes through the resolved-limits path. The shipped detail page saves through `PUT /v1/admin/accounts/{id}/limits`; the resolved-limits path is API-only.

## Common scenarios

- **Comp a customer with higher limits** - keep them on Pro and use the per-account Limits card to bump storage, overlay caps, or chat retention above the plan defaults.
- **Investigate a chargeback** - open the account, review members and connections, then disconnect the channel connections if the account is being rotated.
- **Temporarily disable a flaky integration for one customer** - set a feature override to `OFF` without touching the global kill-switch.
- **Recovery after an OAuth leak** - disconnect the affected channel connection; the user will be prompted to reconnect.

## Permissions

| Action | Permission |
|--------|-----------|
| View account list / detail, limits, features, connections | `accounts:read` |
| Edit account name, manage members, set reconnect flags | `accounts:edit` |
| Change plan / limits / per-account feature overrides | `accounts:edit` |
| Disconnect channel connections | `accounts:edit` |
| Disconnect bot connections | `accounts:edit` |
| Delete account | `accounts:delete` |
| Read per-account permission overrides | `accounts:overrides-read` |
| Set / clear per-account permission overrides | `accounts:overrides-edit` |
| List / delete SE tokens (API only) | `se-tokens:read` / `se-tokens:delete` |

All of these additionally require `admin:access` to enter the dashboard. System admins (`system_admin.is_system = true`) implicitly have every permission.

`platforms:read` / `platforms:edit` exist in the admin permission registry but no admin account endpoint enforces them today - connection deletion is gated on `accounts:edit`.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List accounts | `adminAccounts` | `GET /v1/admin/accounts` |
| Get account detail | `adminAccount` | `GET /v1/admin/accounts/{id}` |
| List account roles for Add Member | `adminAccountRoles` (`accounts:read`) | `GET /v1/admin/accounts/{id}/roles` |
| Update account name | `adminUpdateAccountName` | `PATCH /v1/admin/accounts/{id}` |
| List login connections | `adminAccountLoginConnections` | - |
| Delete account | `adminDeleteAccount` | `DELETE /v1/admin/accounts/{id}` |
| Update plan | `adminUpdateAccountPlan` | `PATCH /v1/admin/accounts/{id}/plan` |
| Add member with an account-owned role | `adminAddAccountMember(accountId, userId, roleId)` (`accounts:edit`) | `POST /v1/admin/accounts/{id}/members` with required `user_id` and `role_id` |
| Remove member | `adminRemoveAccountMember` | `DELETE /v1/admin/accounts/{id}/members/{user_id}` |
| Get limits | `adminAccountLimits` | `GET /v1/admin/accounts/{id}/limits` |
| Save limits | `adminUpsertAccountLimits` / `adminSetAccountLimits` | `PUT /v1/admin/accounts/{id}/limits` |
| Save resolved limits | `adminSetAccountLimits` | `PUT /v1/admin/accounts/{id}/resolved-limits` |
| Get feature overrides | `adminAccountFeatures` | `GET /v1/admin/accounts/{id}/features` |
| Set feature override | `adminSetAccountFeature` | `PUT /v1/admin/accounts/{id}/features` |
| Clear feature override | `adminClearAccountFeature` | `DELETE /v1/admin/accounts/{id}/features/{feature_id}` |
| List channel connections | `adminAccountChannelConnections` | `GET /v1/admin/accounts/{id}/connections` |
| Delete channel connection | `adminDeleteAccountChannelConnection` | `DELETE /v1/admin/accounts/{id}/connections/{platform}` |
| Delete account login connection | `adminDeleteAccountLoginConnection` | - |
| Set channel reconnect flag | `adminSetChannelReconnectFlag` | `PUT /v1/admin/channel-connections/{id}/reconnect-flag` |
| List bot connections | `adminAccountBotConnections` | `GET /v1/admin/accounts/{id}/bot-connections` |
| Delete bot connection | `adminDeleteAccountBotConnection` | `DELETE /v1/admin/accounts/{id}/bot-connections/{platform}` |
| Set bot reconnect flag | `adminSetBotReconnectFlag` | `PUT /v1/admin/bot-connections/{id}/reconnect-flag` |
| List SE tokens | `adminSeTokens` | `GET /v1/admin/accounts/{id}/se-tokens` |
| Delete SE token | `adminDeleteSeToken` | `DELETE /v1/admin/accounts/{id}/se-tokens/{token_id}` |
| List permission overrides | `adminAccountPermissionOverrides` | `GET /v1/admin/accounts/{id}/permission-overrides` |
| Set permission override | `adminSetAccountPermissionOverride` | `PUT /v1/admin/accounts/{id}/permission-overrides` |
| Remove permission override | `adminRemoveAccountPermissionOverride` | `DELETE /v1/admin/accounts/{id}/permission-overrides/{permission}` |

## Tips & gotchas

- Empty fields in the limits form are semantically different from `0`. An empty field inherits the plan default; a zero disables the feature for that account.
- **Notes** on the limits form is the audit trail. Fill it in with a ticket ID or Slack link when you override anything non-trivial.
- Plan changes are immediate - there is no Stripe sync here; billing adjustments still go through the Stripe dashboard.
- Deleting a channel connection does **not** revoke the token at the platform. Use it for recovery, not revocation.

## Related

- [Users](./users.md) - user records that own or belong to accounts
- [Plans](./plans.md) - plan definitions and default feature grid
- [Feature Flags](./feature-flags.md) - global kill-switches that override everything here
- [Providers](./providers.md) - per-platform kill-switches

---

## Admin / Admin Roles

Source: https://docs.lumio.vision/admin/admin-roles

# Admin Roles

Create and manage admin roles, assign permissions to them, and control which admin users hold each role.

## Overview

Admin roles let administrators delegate specific sections of the admin panel to team members without granting full system access. Each role carries a set of granular permissions and can be assigned to any number of admin users.

## Accessing the Page

Navigate to **Admin > Admin Roles** (`/admin-roles`). Both the sidebar entry and the page itself require `admin-roles:read`, on top of the `admin:access` dashboard gate.

The list is a table with **Name**, **Permissions** (count), **Members** (count), **Type** (`System` / `Custom` badge), and **Actions**.

## Permissions

| Permission | Description |
|---|---|
| `admin-roles:read` | View the admin roles list |
| `admin-roles:create` | Create new admin roles |
| `admin-roles:edit` | Edit existing roles (name, description, permissions, members) |
| `admin-roles:delete` | Delete non-system roles |

## Creating a Role

1. Click **Create Role** (requires `admin-roles:create`).
2. Enter a **name** (required, max 100 characters) and an optional **description**.
3. Use the **permission picker** to select which admin permissions the role grants. Permissions come from the backend registry via `/api/admin-permissions`, grouped by the category derived from the part of the permission string before the `:`, each with a tri-state "select all in category" checkbox.
4. Click **Create Role** to save.

## Editing a Role

Click any row in the table, or the pencil in the Actions column, to open the edit dialog (requires `admin-roles:edit`).

All fields - name, description, and permissions - are editable for all roles, including system roles. **Save Changes** stays disabled until something actually changed and sends only the changed fields.

## `admin:access` Permission

Every role automatically includes the `admin:access` permission. The picker skips it - it cannot be selected or deselected. It is required for any admin user to access the admin panel at all.

## Two-factor authentication required

Admin access requires two-factor authentication. A user whose admin roles grant any admin permission, but who has no 2FA factor (an authenticator app or a passkey), cannot use any of it:

- **Admin panel** - opening it sends the user to the web app at `/dashboard?admin_mfa=required`. The dashboard opens the **Admin access needs two-factor** dialog with a note that the user came from the admin app. A sign-in on the way drops the query; the dialog then still opens, only without that note. The admin login page keeps its message for `/login?error=mfa_required` (old links and bookmarks), with a link to the same dashboard address.
- **Web app** - while `adminMfaRequired` is true, every dashboard page load opens the same dialog: why admin access needs a second factor, and **Set up two-factor**, which opens **Settings › Security › Sign-in & 2FA** at the two-factor section and starts the choice between a passkey and an authenticator app. **Later** closes it for the rest of the browser session (`sessionStorage`); the redirect from the admin panel opens it again. When the settings window closes after the setup started, the dashboard reads `me` again: with a factor the dialog is gone, without one it returns. It never appears in popouts or overlays.
- **API** - every admin resolver and admin REST route refuses the session with `ADMIN_MFA_REQUIRED` (REST: `403`, GraphQL: `extensions.code`). GraphQL and REST use the same check and the same message.
- **Everything else keeps working** - the same session keeps its channels, account permissions and user-level permissions in the web app.

The check runs in the API's auth middleware on every request of a session that holds admin grants. It is fail-closed: if the factor state cannot be read, the request is answered `503 authorization_unavailable` instead of being served with admin rights. It takes effect at once in both directions: turning on 2FA unlocks the admin panel on the next request, and removing the last factor locks it on the next request. `me { adminMfaRequired }` / `GET /v1/users/me` `admin_mfa_required` report the state; a refusal is an authorization decision and writes no audit event. System keys are not affected - they carry no user and are provisioned in the config.

## `devtools:read` Permission

Grants the **Dev & Admin** menu in the web app (`lumio.vision`, production included): a wrench icon left of **Logout** in the dashboard sidebar and the shortcut **Ctrl + Alt + Shift + D**. Its first tool previews a seasonal look in the admin's own browser only (see [Preferences → Seasonal Look](/user-guide/preferences#seasonal-look)). The web app shows the menu only to users whose admin roles give them both `admin:access` and `devtools:read`; it is seeded to `system_admin` and can be added to further admin roles here. Nothing the menu does is sent to the server, so it writes no audit event.

## System Roles

Roles with **is_system: true** (shown with a "System" badge) are protected:

- They are **editable** - you can change their name, description, and permissions.
- They are **not deletable** - the Delete Role button in the dialog's Danger Zone is disabled, with "System roles cannot be deleted." shown as both a tooltip and a note underneath. The server refuses the delete as well.

The built-in `system_admin` role is an example of a system role.

## Member Management

The edit dialog includes a **Members** section:

- Lists all admin users currently holding the role with their name, email, and avatar.
- Use the **search box** to find users by name or email and add them to the role. The search is debounced and excludes users who already hold the role.
- Click the remove button next to any member to unassign them.

## API

| Action | GraphQL | REST |
|--------|---------|------|
| List roles | `adminRoles` | `GET /v1/admin/admin-roles` |
| Get a role | `adminRole` | `GET /v1/admin/admin-roles/{id}` |
| Create a role | `adminCreateRole` | `POST /v1/admin/admin-roles` |
| Update a role | `adminUpdateRole` | `PATCH /v1/admin/admin-roles/{id}` |
| Delete a role | `adminDeleteRole` | `DELETE /v1/admin/admin-roles/{id}` |
| List role members | `adminRoleMembers` | `GET /v1/admin/admin-roles/{id}/members` |
| Assign a member | `adminAssignUserRole` | `PUT /v1/admin/admin-roles/{id}/members/{userId}` |
| Unassign a member | `adminUnassignUserRole` | `DELETE /v1/admin/admin-roles/{id}/members/{userId}` |
| Permission registry for the picker | `allAdminPermissions` | `GET /v1/admin/admin-permissions` |

Assigning and unassigning members is gated on `admin-roles:edit`, not on a dedicated permission.

A role's permission list is validated against the backend registry on create and update, so a wildcard such as `accounts:*` can never be persisted into an admin role.

## Related

- [RBAC Permissions](../developer-guide/rbac-permissions.md)
- [API Reference: Permissions](../api-reference/permissions.md)

---

## Admin / API Keys

Source: https://docs.lumio.vision/admin/api-keys

# API Keys

The API Keys view lets Lumio operators inspect and manage **any** account's or user's API keys for support and incident response - listing keys, editing a key's label and scopes, rotating a leaked secret, and revoking a key. It covers both key kinds: personal **user API keys** (`lm_usr_`, stored in `api_keys`) that carry a single member's identity, and account **service keys** (`lm_svc_`, stored in `account_service_keys`) that belong to the account and outlive the member who minted them.

This is the **operator** surface, gated on the admin-scope `account-apikeys:*` family. It is distinct from the account-scope `apikeys:*` family a member uses to manage their **own** keys under **Settings → Channel → Access → API Keys** - holding one never grants the other.

## Where to find it

There is no standalone sidebar entry. The API-keys panel is reached in two places:

- **Admin → [Accounts](./accounts.md) → account detail** - lists **both** kinds for that account: its members' personal `lm_usr_` keys and the account's `lm_svc_` service keys.
- **Admin → [Users](./users.md) → user detail** - lists that user's personal `lm_usr_` keys only (a service key has no owning user).

## Quick start

1. Open **Admin → Accounts**, drill into an account (or **Admin → Users** → a user), and scroll to the **API Keys** panel.
2. Each key renders as a card showing its kind badge (`personal` / `service`), label, non-secret prefix, scopes, and created / last-used dates. The secret itself is never shown.
3. Use **Edit** to change a key's label and scopes, **Rotate** to regenerate its secret, or **Revoke** to delete it.
4. **Rotate** reveals the new full key exactly once - copy it and hand it back to the account. Everything else on the card is non-secret.

## Detailed walkthrough

### API Keys panel

One card per key. Each card shows:

- **Kind** - a `personal` (`lm_usr_`) or `service` (`lm_svc_`) badge.
- **Label** - the human-friendly name, with the key's non-secret prefix in monospace.
- **Scopes** - the key's permission list, as chips.
- **Owner / account** - for a personal key, the owning user; the account it is bound to for both kinds.
- **Created** and **Last used** - dates; "Last used" is omitted when the key has never been used.

Card actions are each gated on their own permission: **Edit** (`account-apikeys:edit`), **Rotate** (`account-apikeys:rotate`), **Revoke** (`account-apikeys:delete`).

### Editing a key (label + scopes)

**Edit** (gated on `account-apikeys:edit`) updates a key's label and scope list. Scope edits are validated against the assignable-scope registry for the key's **kind** (the same ZAF-1170 registry the dashboard picker uses): an unknown, deny-listed, or user-scoped-on-a-service-key scope is rejected before the write.

An operator can never push a key **above its own principal**:

- For a **personal** key, the scopes are additionally capped to the key **owner's** own grantable permissions - an operator cannot grant a member's key a permission the member does not hold.
- For a **service** key, the account is the principal, so the ceiling is the registry (minus the deny-list).

### Rotating a key

**Rotate** (gated on `account-apikeys:rotate`) regenerates the key's secret in place: the key id, label, and scopes are unchanged, but the old secret stops working immediately and a **new full key is returned exactly once**. The plaintext is shown in a one-time reveal - copy it and hand it back to the account through a secure channel. It is never shown again, never returned by the list, and never logged.

### Revoking a key

**Revoke** (gated on `account-apikeys:delete`) hard-deletes the key row. Any subsequent request using that key returns `401`. The delete is **idempotent** - revoking an already-gone key resolves to the same not-found result rather than erroring.

## Permissions

The panel is gated on the admin-scope `account-apikeys:*` family - admin-scope (global) permissions checked against the caller's **admin role**, seeded to `system_admin`, and enforced by `AdminPermissionGuard` (GraphQL) / `require_admin_permission` (REST). They are **not** the account-scope `apikeys:*` permissions a member uses on their own keys.

| Action | Permission |
|--------|-----------|
| View any account's / user's keys | `account-apikeys:read` |
| Edit a key's label + scopes | `account-apikeys:edit` |
| Rotate a key's secret | `account-apikeys:rotate` |
| Revoke (delete) a key | `account-apikeys:delete` |

Dashboard entry requires `admin:access`. System admins implicitly hold every `account-apikeys` permission.

## API

`{kind}` is `personal` (`lm_usr_`) or `service` (`lm_svc_`); the GraphQL enum `ApiKeyKind` uses `PERSONAL` / `SERVICE`.

| UI action | GraphQL | REST |
|-----------|---------|------|
| List an account's keys (both kinds) | `adminAccountApiKeys(accountId)` | `GET /v1/admin/accounts/{account_id}/api-keys` |
| List a user's keys (personal only) | `adminUserApiKeys(userId)` | `GET /v1/admin/users/{user_id}/api-keys` |
| Edit a key (label + scopes) | `adminUpdateApiKey(kind, id, label, permissions)` | `PATCH /v1/admin/api-keys/{kind}/{id}` |
| Rotate a key's secret | `adminRotateApiKey(kind, id)` | `POST /v1/admin/api-keys/{kind}/{id}/rotate` |
| Revoke a key | `adminDeleteApiKey(kind, id)` | `DELETE /v1/admin/api-keys/{kind}/{id}` |

The two rotate results return `{ key, apiKey }` (personal) / `{ key, serviceKey }` (service) - the full key string plus the updated non-secret metadata. Every operator action emits a **system-scope** audit event (`system:api_key_updated` / `system:api_key_rotated` / `system:api_key_revoked`) with the operator as the actor; these rows never surface in the target account's or user's own audit log.

## Tips & gotchas

- **The rotated secret is shown once.** The card only ever displays the non-secret prefix; a secret lost after the one-time reveal cannot be recovered - rotate again.
- **Operator edits cannot escalate a key.** A personal key stays capped to its owner's permissions and a service key to the account's registry ceiling, so an operator can never grant a scope the principal itself does not hold.
- **`account-apikeys:*` ≠ `apikeys:*`.** The former is admin-scope (this page); the latter is account-scope (the member's own **Settings → Channel → Access → API Keys**). Holding one does not unlock the other.
- **Revoke is idempotent and has no confirmation.** One click deletes the key.
- **Personal keys carry a member identity; service keys do not.** That is why the user-detail panel lists only personal keys, and why service-key scopes are capped to the account rather than a user.

## Related

- [Accounts](./accounts.md) - the account-detail page that surfaces this panel
- [Users](./users.md) - the user-detail page that surfaces personal keys
- [System Keys](./system-keys.md) - internal service-to-service keys (`lm_sys_`), a separate operator surface
- [Audit Log](./audit-log.md) - the `system:api_key_*` operator events these actions emit
- [Permissions](../api-reference/permissions.md#admin-account--user-api-keys) - the `account-apikeys:*` family

---

## Admin / Audit Log

Source: https://docs.lumio.vision/admin/audit-log

# Audit Log

View the audit log for system activity tracking.

## Overview

The audit log records privacy-critical and permission-critical actions written
to `audit_events`. Every row has an explicit `scope` (`user`, `account`, or
`system`) and an event-type string.

Rows store entity **ids**, not names. Each event additionally carries a
`resolved_names` list that resolves the UUIDs it references - the actor plus an
allowlist of metadata ids - to display names at read time, so the admin view can
show a name alongside every UUID (a deleted/unknown entity keeps only its raw
UUID). See [Read-time UUID → name resolution](../developer-guide/audit-events.md#read-time-uuid--name-resolution-zaf-1233).

The table below highlights operator-relevant events; it is a selection, not the
complete event catalog. For every recorded type and its scope, see the
[full event catalog](../features/audit-log.md#event-catalog).

| `type` | Scope | Written by | Trigger |
|--------|-------|-----------|---------|
| `chat_pii_erasure` | `account` / `system` | Chat-PII erasure ([Chat](../features/chat.md#erasure-gdpr-art-17)) | Account dissolution (`account`), a data-subject erasure on one channel's instruction (`system`, `target: "account"`), a single-record erasure on one channel's instruction (`system`, `target: "record"`), or a Lumio-only erasure (`system`, `target: "lumio"`) |
| `youtube_member_erasure` | `system` | YouTube member-badge erasure ([Member Badges](../features/memberships.md)) | A member-channel erasure on one channel's instruction |
| `account:role_created` | `account` | Role management ([Roles](../user-guide/roles-and-permissions.md)) | A new role is created |
| `account:role_updated` | `account` | Role management | A role's name/description/color/permissions change |
| `account:role_deleted` | `account` | Role management | A non-system role is deleted |
| `account:member_role_assigned` | `account` | Member management | A member is assigned a different role |
| `account:member_removed` | `account` | Member management | A member is removed from the account |
| `account:invite_created` / `account:invite_revoked` / `account:invite_accepted` / `account:invite_declined` | `account` | Member management and the recipient's bell | An account invite is created, revoked, accepted, or declined. Bell accept/decline records `source: "notification"`; invite email and code are never stored |
| `developer:team_invite_accepted` / `developer:team_invite_declined` | `user` | Developer-team invite acceptance and the recipient's bell | Bell acceptance records `source: "notification"`; decline records `invite_deleted` and the same source. The invite code and email are never stored |
| `account:dissolved` | `account` | Account settings, or the account security worker | An account is irreversibly dissolved; `via` in metadata is `immediate` (owner, no grace period) or `scheduled` (end of the grace period); `deleted_history_row_count` counts the deleted stream-history rows; `deleted_object_count` / `pending_object_count` count its stored files deleted / left queued for retry |
| `account:dissolution_scheduled` | `account` | Channel settings ([Danger zone](/user-guide/channel-settings)) | The owner schedules the account's dissolution; `grace_days` and `scheduled_for` in metadata |
| `account:dissolution_cancelled` | `account` | Channel settings | The owner cancels a scheduled dissolution; `scheduled_for` (the cancelled date) in metadata |
| `account:identity_changed` | `account` | Channel settings | The channel's name/picture source, own name or own picture changed; `changed` (`source` / `name` / `avatar`), `source_kind`, `source_platform` in metadata |
| `account:connection_added` | `account` | Channel connections ([Connections](../features/connections.md)) | A channel connection is authorized (OAuth callback / exchange) |
| `account:connection_removed` | `account` | Channel connections | A channel connection is disconnected |
| `account:integration_connected` / `account:integration_disconnected` | `account` | Shopify | A Shopify store is linked, or disconnected by a member, from the Shopify admin (no actor) or by Shopify's `app/uninstalled` (no actor) |
| `account:shopify_settings_updated` | `account` | Shopify | A Shopify setting changed, from Lumio (actor = the member) or from the Shopify admin (no actor) |
| `account:shopify_order_name_hidden` | `account` | Shopify | A member hid the buyer name of one Shopify order |
| `account:shopify_data_request` / `account:shopify_customer_redacted` / `account:shopify_shop_redacted` | `account` | Shopify | A Shopify compliance request was handled: a customer data request was forwarded to the owner, a customer's order events were deleted, or a store's events were deleted (no actor) |
| `account:youtube_revenue_data_deleted` | `account` | YouTube Analytics revenue cleanup ([History](../features/stream-history.md)) | Stored revenue rows are deleted; metadata contains `platform`, `reason`, `rows`, never amounts. Available in the admin audit filter. |
| `account:discord_guild_connected` / `account:discord_guild_disconnected` | `account` | Connections → Discord | A Discord server is connected through the verified bot invite, or disconnected. A takeover of a server whose bot was removed writes `connected` for the new account and `disconnected` (no actor) for the previous one, both with `reason: taken_over` |
| `account:discord_guild_bot_removed` | `account` | Discord bot (system) | The bot was removed from a connected server on Discord's side; the connection is marked, not deleted |
| `account:discord_guild_reconnected` | `account` | Connections → Discord | A connected server is invited again; its settings stay |
| `account:obs_config_saved` / `account:obs_config_deleted` | `account` | Connections → Services (OBS) | The account's OBS WebSocket config is saved or removed; `mode`, `remote_host`, `port`, `has_password` in metadata - never the password |
| `account:extension_kill_switch_set` | `account` | Bot modules ([Bot modules](../features/bot-modules.md#kill-switch)) | The account's extension kill switch is set or cleared (`killed` in metadata) |
| `account:extension_moderation` | `account` | Extensions ([useLumioAction → Chat](https://developers.lumio.vision/sdk/hooks/use-lumio-action#chat)), bot modules | An extension moderated chat through the account's bot (`source` = `extension` or `bot_module`, `extension_id`, `install_id`, `action`, `platform`, `target_user_id`, `duration_secs` in metadata; no actor user, never the reason). A bot module's `chat:delete` is not audited |
| `billing:withdrawal_declared` / `billing:cancellation_declared` | `system` for public, `account` or `user` for signed-in withdrawal | [Contract declarations](./contract-declarations.md) | A withdrawal or public cancellation was received. Public declarations have no user actor. |
| `account:subscription_cancel_requested` / `extension:subscription_cancel_requested` | `account` | Contract declarations | A signed-in plan or extension subscription cancellation was requested; metadata identifies the declaration without its free-text reason. |
| `billing:withdrawal_processed` / `billing:cancellation_processed` | `system` | Contract declarations | An operator closed a withdrawal or cancellation as processed or rejected. |
| `billing:declaration_matched` / `billing:declaration_retention_extended` | `system` | Contract declarations | An operator matched a public case or raised its retention date. |
| `billing:withdrawal_waiver_accepted` | `account` | Billing ([Billing](../features/billing.md#withdrawal-waiver-and-order-confirmation)) | A paid checkout completed after the buyer ticked the withdrawal-waiver declaration; `kind`, `text_version`, `accepted_at` and the checkout session in metadata. Proof for § 356 BGB, next to the row in `withdrawal_waiver_consents` |
| `account:extension_uninstalled` | `account` | Extensions ([Extensions](../features/extensions.md#uninstalling-and-reinstalling)) | An extension is uninstalled from the account; `delete_data_immediately` in metadata tells whether its data was deleted at once or kept for 30 days |
| `account:history_revenue_settings_updated` | `account` | Stream history ([History](../features/stream-history.md)) | Revenue assumptions changed; metadata lists the changed field names (no values), with no event for an unchanged write |
| `account:history_shared_link_created` / `account:history_shared_link_revoked` / `account:history_shared_link_extended` | `account` | Stream history ([History](../features/stream-history.md)) | A history report share link (`lm_share_*`) is created, revoked, or extended (`session_id`, `link_id` and effective non-secret `options` in metadata; never the token string/hash or password) |
| `account:history_session_deleted` | `account` | Stream history | A stored stream-history session is deleted (GDPR Art. 17); `session_id` in metadata |
| `account:webhook_target_blocked` | `account` | Automations ([Webhook call targets](../features/automations.md#webhook-call-targets)) | A manual automation run reached a `webhook_call` node whose target the webhook target filter refused; `automation_id`, `reason` and `scheme` in metadata, never the host, path or query |
| `user:login` | `user` | Auth handlers (REST + GraphQL `exchangeToken`) and apps/id ingest | A web, native, or GraphQL-exchange login succeeds |
| `user:login_failed` | `user` | Auth handlers (REST + GraphQL `exchangeToken`) | Provider-token validation or PKCE verification fails |
| `user:oauth_granted` | `user` | apps/id ingest | A signed-in user grants or reconnects OAuth access |
| `user:api_key_created` / `user:api_key_updated` / `user:api_key_revoked` | `user` | User API-key management | A member mints, renames, or revokes a personal `lm_usr_*` API key; emitted by GraphQL `createUserApiKey`/`updateUserApiKey`/`deleteUserApiKey` and REST `POST`/`PATCH`/`DELETE /v1/api-keys` (only `api_key_id` + `key_prefix` in metadata, never the key or its hash) |
| `system:feature_flag_updated` | `system` | Admin feature/provider controls | A global feature flag or provider kill-switch changes |
| `system:plan_created` / `system:plan_updated` / `system:plan_deleted` | `system` | Admin plan management | A billing plan is created, edited, or deleted |
| `system:plan_feature_updated` | `system` | Admin plan management | A plan↔feature mapping changes |
| `system:account_plan_changed` | `system` | Admin account controls, or Stripe billing webhook | An admin reassigns an account's plan, or a Stripe subscription event changes it (`"via":"stripe"` in metadata, actor NULL) |
| `system:account_feature_override` | `system` | Admin account controls | An admin sets or clears an account feature override |
| `system:account_limits_updated` | `system` | Admin account controls | A platform operator changes an account's numeric limit overrides; metadata records the target account, write path, and submitted limits, never free-text notes |
| `system:account_deleted` | `system` | Admin account controls | A platform operator deletes an account (`DELETE /v1/admin/accounts/{id}` / `adminDeleteAccount`); the deleted account id, `"reason":"operator_delete"`, `deleted_history_row_count` (stream-history rows deleted) and `deleted_object_count` / `pending_object_count` ride in metadata. Owner self-service dissolve is the separate account-scope `account:dissolved` |
| `system:orphaned_storage_swept` | `system` | Admin storage repair | A platform operator applies the orphaned extension upload sweep (`POST /v1/admin/storage/orphaned-extension-uploads/sweep` / `adminSweepOrphanedExtensionUploads` with `apply: true`, `admin:privacy-erase`); `"kind":"extension_uploads"`, `orphaned_object_count` and `queued_object_count` ride in metadata. A dry run records nothing |
| `extension:purchase_auto_refunded` | `system` | Stripe payment webhook ([Webhooks › Automatic refund](../features/webhooks.md)) | A paid extension checkout that cannot be delivered (extension or version deleted or unpublished during checkout: `cause: "detached"`; account lost access: `cause: "not_installable"`) was refunded in full; actor NULL. `purchase_id`, `cause`, `amount`, `currency` and `stripe_refund_id` ride in metadata, never buyer data. A refund Stripe refused records nothing and is only in the API error log |
| `privacy:chatter_objection_added` / `privacy:chatter_objection_removed` | `system` | Chatter objection ([Chat › Objection](../features/chat.md#objection-gdpr-art-21)) | A platform operator records or lifts a chatter's GDPR Art. 21 objection; `platform`, `"reason":"objection"` and `already_erased` ride in metadata, never the user id or login |
| `privacy:channel_suppression_withdrawn` | `system` | Channel erasure withdrawn ([Chat › Erasure](../features/chat.md#erasure-gdpr-art-17)) | A platform operator withdraws one channel's erasure instruction for one chatter; the channel's later reports name the chatter again. `target`, `account_id`, `instruction_reference` and `platform` ride in metadata, never the user id or login |
| `system:system_key_created` / `system:system_key_revoked` | `system` | Admin credential management | A system API key (`is_system=true`) is minted or revoked (never `full_key`/`key_hash`) |
| `system:connection_upserted` / `system:connection_deleted` | `system` | Admin credential management | A system OAuth (login-provider) connection is created/updated or deleted (raw `client_secret` and ciphertext never stored) |
| `system:user_role_created` / `system:user_role_updated` / `system:user_role_deleted` | `system` | Admin user-role management | A cross-account user role is created, edited, or deleted |
| `system:user_role_assigned` / `system:user_role_unassigned` | `system` | Admin user-role management | A cross-account user role is assigned to or removed from a user |
| `system:user_permission_override_set` / `system:user_permission_override_removed` | `system` | Admin user-role management | A per-user permission override is set or removed |
| `system:account_permission_override_set` / `system:account_permission_override_removed` | `system` | Admin account controls | A platform operator sets or removes an account-level permission override (`PUT` / `DELETE /v1/admin/accounts/{id}/permission-overrides` / `adminSetAccountPermissionOverride` / `adminRemoveAccountPermissionOverride`); target `account_id` + `permission` (+ `granted`/`reason` on set) ride in metadata |
| `oauth_client:created` / `oauth_client:updated` / `oauth_client:deleted` | `system` | Admin developer-application management | A developer OAuth client is created, edited, or deleted (`oauth-clients:{create,edit,delete}`); metadata carries the DB row id (`client_id_ref`), not the OAuth `client_id` string, and never the `client_secret` |
| `admin_role:created` / `admin_role:updated` / `admin_role:deleted` | `system` | Admin admin-role management | An operator admin role is created, edited, or deleted (`admin-roles:{create,edit,delete}`) on the `admin_roles` table (distinct from user roles); `role_id` / `role_name` / `permissions` in metadata |
| `admin_role:assigned` / `admin_role:unassigned` | `system` | Admin admin-role management | An admin role is assigned to or removed from a user (`admin-roles:edit`); `role_id` + `target_user_id` in metadata |
| `system:global_bot_connection_upserted` / `system:global_bot_connection_deleted` | `system` | Admin bot-connection management | A global (nil-UUID) bot connection is upserted (manual Discord token or OAuth exchange) or deleted (`bot-connections:{create,delete}`); `platform` / `connection_id` / `bot_username` / `source` in metadata, never the token |
| `system:user_deleted` | `system` | Admin user management | A platform operator deletes a user and all their data (`users:delete`, `DELETE /v1/admin/users/{id}` / `adminDeleteUser`); `target_user_id` in metadata |
| `system:user_login_connection_deleted` | `system` | Admin user management | A platform operator removes one of a user's login identities (`adminDeleteUserLoginConnection` / `DELETE /v1/admin/users/{id}/login-connections/{provider}`); `target_user_id` + `provider` in metadata |
| `system:user_setting_preset_deleted` | `system` | Admin user management | A platform operator deletes one of a user's setting presets; metadata records the target user, preset id, and kind, never the preset payload |
| `developer:funds_deletion_released` | `system` | Admin developer management | A platform operator releases an unpayable developer balance as a liability and deletes the user or profile (`developer-funds:release-deletion`); `released_balance_id`, `amount`, `currency`, `release_case` in metadata |
| `developer:funds_released_claim_started` | `system` | Admin developer management | A platform operator records that a person presented the claim code of a released balance; the record is then kept until the claim is settled (`developer-funds:settle`); `released_balance_id`, `amount`, `currency` in metadata. Once per record |
| `developer:funds_released_settled` | `system` | Admin developer management | A platform operator credits a released balance to the person's new, verified developer profile (`developer-funds:settle`); `released_balance_id`, `developer_id`, `amount`, `currency` in metadata |
| `developer:payout_requested` | `user` | Developer payouts | A developer requested a payout, or a closing payout was created for a profile deletion (`source`); payout id, method, amount, masked destination in metadata |
| `system:developer_deleted` / `system:developer_team_deleted` | `system` | Admin developer management | A platform operator deletes a developer or developer team (`developer-verification:edit` / `developer-limits:edit`); `developer_id` / `team_id` in metadata |
| `system:developer_team_member_added` / `system:developer_team_member_removed` / `system:developer_team_member_role_changed` | `system` | Admin developer management | A platform operator adds/removes a developer-team member or changes their role (`developer-limits:edit`); `team_id`, `member_id`/`target_user_id`, `role_id` in metadata |
| `system:developer_revenue_split_set` | `system` | Admin developer management | A platform operator sets a developer's revenue split (`developer-limits:edit`); `developer_id` + `split` in metadata |
| `system:developer_limits_updated` | `system` | Admin developer management | A platform operator updates a developer or extension limit - one merged event discriminated by `limit_scope` (`developer`\|`extension`) in metadata (`developer-limits:edit`) |
| `system:developer_limit_request_reviewed` | `system` | Admin developer management | A platform operator reviews a developer limit request (`developer-limits:edit`); `request_id`, `status`, `developer_id`, `extension_id`, `limit_key`, `has_review_notes` in metadata - never the free-text `review_notes` |
| `system:user_email_changed` | `system` | Admin user management | A platform operator changes a user's email (`users:edit`), only on a real change; `target_user_id` + `had_previous_email` in metadata - never the address. Distinct from the user-self `user:email_changed` |
| `system:user_account_creation_override_set` | `system` | Admin user management | A platform operator sets a user's account-creation override (`users:edit`); `target_user_id` + `override` (`allow`\|`deny`\|`default`) in metadata |
| `system:user_max_accounts_override_set` | `system` | Admin user management | A platform operator sets a user's max-accounts override (`users:edit`) - GraphQL-only; `target_user_id` + `max_accounts` in metadata |
| `system:account_connection_deleted` / `system:account_bot_connection_deleted` | `system` | Admin account controls | A platform operator deletes an account's channel / bot connection (`accounts:edit`); `target_account_id` + `platform` in metadata. Deleting a Discord server connection (`discord-guilds:delete`) writes `system:account_bot_connection_deleted` with `platform: discord` and `guild_id` |
| `system:account_login_connection_deleted` | `system` | Admin account controls | A platform operator deletes an account's login (identity) connection (`accounts:edit`) - GraphQL-only; `target_account_id` + `provider` in metadata |
| `crawler:scope_changed` | `system` | Admin crawler controls | A platform operator changes the crawl scope |
| `crawler:watchlist_added` / `crawler:watchlist_removed` | `system` | Admin crawler controls | A platform operator adds or removes a channel from the crawler watchlist |
| `copyright:moderation_approved` / `copyright:moderation_dismissed` | `system` | Admin Copyright Review | A platform operator (`copyright:moderate`) approves a report into the global safe or blocked list or dismisses it. Metadata includes `spotify_track_id`, `list`, `source`, and `decision`, without song title, artist, or reporter identity. Dismissal is recorded only when a report was dismissed |
| `system:account_member_added` / `system:account_member_removed` | `system` | Admin account controls | A platform operator adds a user to / removes a member from an account (`accounts:edit`); `target_account_id`, `target_user_id` (+ `role_id` on add) in metadata; only a real add / removal is recorded |
| `system:coupon_created` / `system:coupon_updated` / `system:coupon_deactivated` | `system` | Admin coupons | A platform operator creates, updates or deactivates a coupon (`coupons:{create,edit}`); `coupon_id` + `discount_type` (create) or `changed_fields` (update) in metadata - never the coupon code |
| `system:account_se_token_deleted` | `system` | Admin account controls | A platform operator deletes an account's StreamElements token (`se-tokens:delete`); `target_account_id` + `token_id` in metadata - never the token |
| `system:developer_verification_approved` / `system:developer_verification_rejected` | `system` | Admin developer verification | A platform operator approves or rejects a developer KYC verification (`developer-verification:edit`); `verification_id` (+ `target_account_id` on approve) in metadata - never the rejection reason |
| `system:developer_credit_note_cancelled` | `system` | Admin developer credit notes | A platform operator records a developer objection to a credit note or corrects it (`billing:edit`); `credit_note_id`, `cancellation_id`, `cancellation_number`, `reason`, `developer_id`, `reissued_id`, `reissued_number` in metadata - never the supplier's details |
| `system:developer_payout_scheduled` / `system:developer_payout_sent` / `system:developer_payout_completed` / `system:developer_payout_failed` | `system` | Developer payouts | The payout cycle created or sent a developer payout, or it was marked paid / failed by an operator (`billing:edit`), the cycle or the PayPal webhook (`source`); payout id, method, amount, status, masked destination in metadata - never the full PayPal e-mail, IBAN or payee details |
| `system:extension_version_approved` / `system:extension_version_rejected` | `system` | Admin extension review | A platform operator approves or rejects an extension version (`extension-review:edit`); `version_id`, `extension_id` (+ `new_status` on approve) in metadata - never the notes or reason |
| `system:user_extension_dev_mode_set` | `system` | Admin developer management | A platform operator toggles a user's extension dev mode (`developer-limits:edit`); `target_user_id` + `enabled` in metadata |
| `system:api_key_updated` / `system:api_key_rotated` / `system:api_key_revoked` | `system` | Admin [API Keys](./api-keys.md) | A platform operator edits (label + scopes), rotates the secret of, or revokes any account's/user's API key (`account-apikeys:{edit,rotate,delete}`); metadata `kind` (`personal`\|`service`), `api_key_id`, target `account_id`, target `user_id` (personal only), plus `permissions` (update) or `old_key_prefix`+`new_key_prefix` (rotate) - never the key. Never mirrored into the target's own log |
| `system:support_code_viewed` | `system` | Admin user support | A platform operator views a user's support code; metadata contains `target_user_id`, never the code |
| `system:support_code_checked` | `system` | Admin user support | A platform operator checks a user's support code; metadata contains `target_user_id` and `result` (`match` or `no_match`), never the code |
| `system:user_mfa_reset` | `system` | Admin user management | A platform operator resets a user's two-factor authentication; metadata contains `target_user_id` and the required operator `reason` |

The erasure events are hard-delete trails proving *after the fact* that a
subject's data was removed. The `account:role_*` events capture role and
permission changes within an account, and `account:connection_*` events capture
channel connections being added or removed. The `user:*` rows capture personal
security activity, and the `system:*` rows capture operator actions on global
entitlements. See [Event types](#event-types) for the exact metadata each
emitted event carries.

## Scope

Every audit event carries an explicit **`scope`** - one of `user`, `account`, or
`system` - stored as a first-class column and set by the writer, never inferred
at read time from which of `account_id` / `user_id` is populated. Scope
partitions the log into three audiences:

| Scope | Audience | Example |
|-------|----------|---------|
| `user` | The individual user, self-only | Personal-security rows keyed to the authenticated user |
| `account` | An account's members, RBAC-gated to that account | Role/permission change, member-role assignment, channel connection |
| `system` | Platform operators | Instructed GDPR chat erasures and platform-operator rows |

Each scope has its own reader: `user` → `myAuditLog` / `GET /v1/me/audit-log`
(self-only, a first-party session or the user's own API key, no permission);
`account` → `accountAuditLog` / `GET /v1/account/audit-log` (the **account-scope**
`audit-log:read` permission); `system` → the admin log documented on this page
(`adminAuditLog` / `GET /v1/admin/audit-log`, the **admin-scope** `audit-log:read`).

The two erasure types span these scopes: an instructed subject erasure an
operator carries out for one channel writes exactly one `system`-scoped row
(`account_id = null`; the target account is in `metadata.account_id`), and the
account-deletion chat sweep writes a single `account`-scoped row.

> **Note:**
> The top-level `scope` column is distinct from the `"scope": "account"` key that
> appears inside the account-deletion row's `metadata`, which describes the
> *breadth of the erasure operation*, not the audit audience. The instructed
> erasure rows carry no such key. The column is authoritative for filtering.

## Event types

### `chat_pii_erasure`

Written whenever chat PII is hard-deleted for privacy reasons, and for the
Lumio-only erasure. Three paths produce it:

- **Account deletion** — channel dissolution (immediate or at the end of the
  grace period) and the operator delete (`DELETE /v1/admin/accounts/{id}` /
  GraphQL `adminDeleteAccount`) — writes **one account-scoped** event as it
  purges the account's chat messages, platform events, chatter profiles
  (`platform_users`), moderator notes and moderation log. The actor is the
  owner for a dissolution and the operator for an admin delete:

  ```json
  { "scope": "account", "account_id": "<uuid>",
    "deleted_message_count": 0, "deleted_event_count": 0,
    "deleted_platform_user_count": 0, "deleted_user_note_count": 0,
    "deleted_moderation_log_count": 0, "deleted_automod_message_count": 0 }
  ```

- **Instructed data-subject erasure** (`POST /v1/admin/privacy/chat/erase` /
  GraphQL `eraseChatSubjectData`, gated by `admin:privacy-erase`) acts in the
  one instructing account only (channel data belongs to the channel — founder
  ruling ZAF-2626), and writes exactly **one system-scoped** event
  (`account_id = null`, the operator as actor) per request:

  ```json
  // top-level scope = system
  { "target": "account",
    "account_id": "<uuid>", "case_id": "<uuid>",
    "instruction_reference": "TICKET-123",
    "reason": "Channel instruction by e-mail",
    "initiated_by": "channel",                               // or "subject"
    "subject_kind": "platform_user", "platform": "twitch",  // lumio_user: platform null
    "deleted_message_count": 0,
    "deleted_platform_user_count": 0, "deleted_user_note_count": 0,
    "deleted_automod_message_count": 0,
    "deleted_automod_moderation_log_count": 0,
    "deleted_moderation_log_count": 0,
    "scrubbed_history_session_count": 0, "deleted_account_bot_count": 0,
    "removed_held_queue_entry_count": 0,
    "suppressed": true }
  ```

  `account_id` is the instructing (target) account, `instruction_reference`
  the ticket or e-mail id and `reason` the reason the operator supplied (both
  required). `initiated_by` records who
  initiated the erasure: `channel` (the channel itself; it may withdraw it
  later) or `subject` (the person asked for it; never withdrawable). `case_id` is Lumio's id of
  this erasure; its first 8 characters are the case number in the channel
  owner's confirmation e-mail (below), so support finds the event from the
  number the owner quotes. The subject itself is never
  recorded: no platform user id, Lumio user id, login, name or message text —
  `subject_kind` (`platform_user` / `lumio_user`) and `platform` are all that
  identifies the request mode. The two profile counts are the subject's chatter
  profile (`platform_users`) and the moderator notes about them in that
  account. `deleted_automod_message_count` and
  `deleted_automod_moderation_log_count` are the subject's AutoMod history log
  and its `automod_allow` / `automod_deny` moderation-log rows;
  `deleted_moderation_log_count` is every other moderation-log row that
  targeted the subject (bans, timeouts, unbans, deletes, treatment changes).
  The two moderation-log counts never include the same row, and rows in which
  the subject was the acting moderator are kept.
  `scrubbed_history_session_count` is the number of the account's
  stream-history sessions whose frozen top chatters, links, commands,
  keywords, announcements or pins named the subject and were rewritten;
  `deleted_account_bot_count` is the subject's bot-list entry removed.
  `removed_held_queue_entry_count` is the subject's still-open messages closed
  in the channel's live AutoMod held queue (best-effort, 0 when Redis is
  unreachable). `suppressed: true` records that the
  subject was added to the account's suppression list
  (`account_chatter_suppressions`) in the same operation (no separate event).
  No per-account rows are written, and the event lists no other accounts.

  After the deletes Lumio e-mails the channel's **owner** a confirmation
  (ZAF-2640 F9): channel, date, what was deleted (the kinds with a count above
  0) and the case number. It never names the person, their platform or the
  `instruction_reference`, which may identify them. No mail is sent when
  nothing was deleted, when the channel has no owner or the owner no e-mail
  address. The mail is best-effort: a failure is logged and never fails the
  erasure. It is a required notice with no in-app entry and no opt-out.

- **Lumio-only erasure** (`POST /v1/admin/privacy/lumio/erase` / GraphQL
  `eraseChatSubjectAtLumio`, gated by `admin:privacy-erase`) touches no
  channel's data: it writes the person's `erasure` entry in the global Lumio
  list (`chatter_suppressions`, acting on the Lumio Stats leaderboard) and, on
  YouTube, clears Lumio's member cache across every account. One
  **system-scoped** event (`account_id = null`) per request, again without the
  person's id or login:

  ```json
  // top-level scope = system
  { "target": "lumio", "instruction_reference": "TICKET-123",
    "reason": "Art. 17 request",
    "subject_kind": "platform_user", "platform": "youtube",
    "suppressed": true, "erased_key_count": 0 }
  ```

- **Record erasure** (`POST /v1/admin/privacy/records/erase` / GraphQL
  `eraseChatRecord`, gated by `admin:privacy-erase`) erases one record in one
  channel on that channel's instruction: one chat message, moderator note,
  moderation-log entry, AutoMod-log entry, bot-list entry, or one person's
  entries in one stream report. One **system-scoped** event per erased record,
  with the record's internal id, the instruction reference and the operator's
  reason, never a name, message text or platform user id (`platform` only for
  a stream report). A record that is not found writes no event:

  ```json
  // top-level scope = system
  { "target": "record", "record_kind": "chat_message",
    "record_id": "6f0c…", "account_id": "5c1e…", "case_id": "3f9c…",
    "instruction_reference": "TICKET-123", "reason": "Channel instruction",
    "platform": null, "deleted_record_count": 1,
    "moderation_log_text_removed_count": 1, "deleted_moderation_log_count": 0,
    "held_queue_entry_removed": false, "scrubbed_entry_count": 0 }
  ```

### `privacy:chatter_objection_added` / `privacy:chatter_objection_removed`

Written by the chatter objection path (GDPR Art. 21:
`POST /v1/admin/privacy/chat/objections` / GraphQL `addChatterObjection`,
gated by `admin:privacy-objection-create`; `DELETE
/v1/admin/privacy/chat/objections/{platform}/{user_id}` / GraphQL
`removeChatterObjection`, gated by `admin:privacy-objection-delete`). One
system-scoped row (`account_id = null`, the operator as actor) per change:

```json
{ "platform": "twitch", "reason": "objection", "already_erased": false }
```

The chatter's user id and login are deliberately left out. `already_erased` is
`true` when the chatter's entry in the global Lumio list (`chatter_suppressions`)
is already an erasure entry. An objection acts on Lumio Stats only and deletes
nothing. A lift that fails (nothing recorded, or an erasure entry) records
nothing.

### `privacy:channel_suppression_withdrawn`

Written when a channel withdraws its erasure instruction for one chatter
(`POST /v1/admin/privacy/chat/erase/withdraw` / GraphQL
`withdrawChannelChatterSuppression`, gated by `admin:privacy-erase-withdraw`).
The chatter's entry in that account's `account_chatter_suppressions` is
deleted, so the channel's reports frozen afterwards name them again; nothing
the erasure deleted comes back. One system-scoped row (`account_id = null`, the
operator as actor):

```json
{ "target": "account", "account_id": "…", "instruction_reference": "T-123",
  "platform": "twitch" }
```

The chatter's user id and login are left out. Only an erasure the channel
initiated can be withdrawn. A withdrawal that fails (unknown account, no entry
for the chatter, or a 409 because the person asked for the erasure) records
nothing.

### `youtube_member_erasure`

Written by the YouTube member-channel erasure
(`DELETE /v1/admin/privacy/youtube/member/{member_channel_id}?account_id=…&instruction_reference=…&initiated_by=…`
/ GraphQL `eraseYoutubeMemberData`, gated by `admin:privacy-erase`). It clears
Lumio's own cached member records in Redis across every account (Lumio's
YouTube API client cache, not channel data) and erases the member's channel
data in the instructing account only, exactly as the `chat_pii_erasure`
subject erasure above. It writes exactly **one system-scoped** event
(`account_id = null`) per request, with the same metadata as the
`chat_pii_erasure` subject event (`subject_kind: "platform_user"`,
`platform: "youtube"`) plus `erased_key_count`:

```json
// top-level scope = system
{ "target": "account",
  "account_id": "<uuid>", "case_id": "<uuid>",
  "instruction_reference": "TICKET-123", "initiated_by": "channel",
  "subject_kind": "platform_user", "platform": "youtube",
  "erased_key_count": 0, "deleted_message_count": 0,
  "deleted_platform_user_count": 0, "deleted_user_note_count": 0,
  "deleted_automod_message_count": 0,
  "deleted_automod_moderation_log_count": 0,
  "deleted_moderation_log_count": 0,
  "scrubbed_history_session_count": 0, "deleted_account_bot_count": 0,
  "removed_held_queue_entry_count": 0,
  "suppressed": true }
```

The member channel id is never recorded. The channel owner gets the same
confirmation e-mail as for `chat_pii_erasure`; it lists the channel membership
only when the instructing channel itself had the member cached.

Both event types record the acting admin in `user_id` and their request IP in
`ip_address` (GeoIP-enriched into `country` / `city` - see
[Location data](#location-data)). Their origin is request-derived (the admin
REST route or its GraphQL twin), so they also record the `user_agent`.

### `account:role_*` (role & permission changes)

Emitted whenever an account's roles or member-role assignments change, via both
GraphQL (`createRole` / `updateRole` / `deleteRole` / `updateMemberRole`) and
their REST counterparts (`POST /v1/roles`, `PATCH /v1/roles/{id}`,
`DELETE /v1/roles/{id}`, `PATCH /v1/accounts/{id}/members/{membership_id}/role`).
Both protocols write **identical** rows. Every event is `account`-scoped,
carries the acting `user_id` (the actor), the tenant `account_id`, and the
request `ip_address` (GeoIP-enriched). These rows surface **only** in the account
log - never the actor's personal (`user`-scoped) log (overlap rule).

- `account:role_created` / `account:role_updated` / `account:role_deleted`:

  ```json
  { "role_id": "<uuid>", "role_name": "Moderators", "slug": "moderators" }
  ```

- `account:member_role_assigned`:

  ```json
  { "membership_id": "<uuid>", "target_user_id": "<uuid>",
    "role_id": "<uuid>", "role_name": "Moderators",
    "personal_keys_affected": 2, "popout_tokens_affected": 1 }
  ```

  The two counts are the member's live personal API keys and popout tokens.
  Their scopes follow the new role from the next request; a count is `null`
  when it could not be read.

The audit insert is **best-effort**: a failed write is logged and swallowed, so
the role mutation itself never fails on the audit side-channel.

### `account:connection_*` (channel connections)

Emitted whenever a channel connection is added or removed. **Add**
(`account:connection_added`) happens at OAuth completion, which is REST-only: the
session-bound JSON exchanges (`POST /connections/channel/{platform}/exchange` and
the unified `POST /connections/oauth/{platform}/exchange`). There is no
GraphQL "add connection" mutation to mirror, because authorization is an HTTP
redirect flow. **Remove** (`account:connection_removed`) has full parity:
GraphQL `disconnectChannel` and REST `DELETE /v1/connections/channel/{platform}`
write identical rows. Every event is `account`-scoped, carries the tenant
`account_id`, the request `ip_address` (GeoIP-enriched), and the platform:

```json
{ "platform": "twitch" }
```

The acting `user_id` is recorded on the authenticated paths (exchange, disconnect).
The unauthenticated browser-redirect callback carries no caller identity, so its
actor is `null`. Like the role events, these rows surface **only** in the account
log (overlap rule) and the insert is **best-effort** - a failed write never fails
the connection mutation.

For YouTube, `account:connection_added` also records `optional_scopes_granted` as the list of optional scope names granted by Google; `[]` means none were granted. It contains neither a token nor the complete grant.

### `account:youtube_revenue_data_deleted`

This account-scoped event records deletion of stored YouTube Analytics revenue rows. It appears only when at least one row was removed. The actor is the user who triggered deletion, or absent for a worker cleanup. The metadata contains no revenue amount:

```json
{ "platform": "youtube", "reason": "scope_removed", "rows": 12 }
```

`reason` is `disconnected`, `scope_removed`, `revoked`, `auth_unconfirmed_30d`, `video_deleted`, `account_deleted`, or `report_deleted`. The admin viewer includes this event type in its label and type filter.

### `user:*` (personal security events)

User-scope rows are personal security events. They always use
`account_id = null`; when the event can be tied to a known Lumio user, `user_id`
is the subject who can see the row in **My Activity**. If a failed login cannot
be mapped to a known Lumio user, the row is still `scope=user` but has
`user_id = null`, so it is visible only in the admin audit log.

- `user:login` - successful login. apps/id emits the web login path through
  `POST /v1/internal/audit-ingest`; the Rust `POST /v1/auth/token/exchange`
  handler emits the native PKCE redemption path directly; the GraphQL
  `exchangeToken` mutation emits its own success inline (`method:
  graphql_exchange`) - it has no first-party caller, so apps/id ingest never
  covers it.

  ```json
  { "method": "graphql_exchange", "provider": "twitch", "is_new_user": false }
  { "method": "pkce" }
  ```

- `user:mfa_enabled` / `user:mfa_disabled` - the first or last 2FA method; `method` identifies an authenticator app (`totp`) or passkey. `user:mfa_factor_added` / `user:mfa_factor_removed` record a further method being added or removed; metadata includes method type, factor ID and resulting count, never the user-chosen label.

- `user:login_failed` - rejected login emitted by the Rust REST `/auth` handlers
  and the GraphQL `exchangeToken` mutation (at parity) when provider-token
  validation fails or PKCE verification fails.

  ```json
  { "provider": "twitch", "reason": "provider_token_invalid" }
  { "reason": "pkce_verification_failed" }
  ```

- `user:oauth_granted` - provider link/reconnect consent from a signed-in user,
  emitted by apps/id through the ingest endpoint.

  ```json
  { "provider": "youtube", "reconnect": true, "connection_id": "<uuid>" }
  ```

- `user:api_key_created` / `user:api_key_updated` / `user:api_key_revoked` - a
  member mints, renames, or revokes a personal `lm_usr_*` API key, via GraphQL
  `createUserApiKey` / `updateUserApiKey` / `deleteUserApiKey` and REST `POST` /
  `PATCH` / `DELETE /v1/api-keys`. Metadata carries only the non-secret
  `api_key_id` + `key_prefix`; never the key or its hash.

  ```json
  { "api_key_id": "<uuid>", "key_prefix": "lm_usr_ab12" }
  ```

apps/id forwards the end-user IP and user-agent to the ingest endpoint; the Rust
auth handlers capture them from the request. Both paths GeoIP-enrich the IP
fail-open.

### `system:*` (platform-operator actions)

Emitted for platform-operator actions on the **global entitlement surface**,
reachable from the admin app. Every event is `system`-scoped, carries the acting
admin as `user_id` and the request `ip_address` (GeoIP-enriched), and - unlike the
account events - carries **no** tenant `account_id` column. A target account (for
the per-account overrides) is recorded in `metadata` instead, so a system row can
never surface in that account's own audit log; it appears only on this admin
system surface. GraphQL and REST write identical rows, and the insert is
**best-effort** (a failed write never fails the admin mutation).

- `system:feature_flag_updated` - a global feature-flag toggle. Emitted by GraphQL
  `adminUpdateFeatureFlag` / `adminUpdateFeatureFlagDetail`, REST
  `PATCH /v1/admin/feature-flags/{id}` / `PUT /v1/admin/feature-flags/{id}/detail`,
  and the platform provider kill-switches - GraphQL
  `adminSetProviderEnabled` / `adminSetProviderSubtypeEnabled` /
  `adminToggleProvider` / `adminToggleProviderSubtype` and REST
  `PATCH /v1/admin/providers/{platform}[/{subtype}]/toggle` and `…/enabled`, which
  flip the same `platform:*` flags. The provider paths add `"via": "provider"` plus
  the `platform` (and `subtype`) to the metadata; `enabled` is always the resulting
  flag state.

  ```json
  { "flag_id": "<uuid>", "flag_key": "platform:twitch", "enabled": false,
    "via": "provider", "platform": "twitch" }
  ```

- `system:plan_created` / `system:plan_updated` / `system:plan_deleted` - plan
  lifecycle, via GraphQL `adminCreatePlan` / `adminUpdatePlan` / `adminDeletePlan`
  and REST `POST /v1/admin/plans`, `PATCH /v1/admin/plans/{id}`,
  `DELETE /v1/admin/plans/{id}`.

  ```json
  { "plan_id": "<uuid>", "slug": "pro", "name": "Pro" }
  ```

- `system:plan_feature_updated` - a plan↔feature mapping change, via GraphQL
  `adminSetPlanFeature` and REST `PUT /v1/admin/plans/{id}/features`.

  ```json
  { "plan_id": "<uuid>", "feature_id": "<uuid>", "enabled": true }
  ```

- `system:account_plan_changed` - an admin reassigns an account's plan, via GraphQL
  `adminUpdateAccountPlan` and REST `PATCH /v1/admin/accounts/{id}/plan`.

  ```json
  { "account_id": "<uuid>", "plan_id": "<uuid>" }
  ```

- `system:account_feature_override` - an admin sets or clears a per-account feature
  override, via GraphQL `adminSetAccountFeature` / `adminClearAccountFeature` and
  REST `PUT /v1/admin/accounts/{id}/features` /
  `DELETE /v1/admin/accounts/{id}/features/{feature_id}`. The `action` field is
  `set` or `clear`.

  ```json
  { "account_id": "<uuid>", "feature_id": "<uuid>", "action": "set", "enabled": true }
  ```

- `system:orphaned_storage_swept` - a platform operator applies the orphaned
  extension upload sweep (GraphQL `adminSweepOrphanedExtensionUploads` / REST
  `POST /v1/admin/storage/orphaned-extension-uploads/sweep`, `apply: true` only).
  Metadata carries `kind`, `orphaned_object_count` and `queued_object_count`.
- `extension:purchase_auto_refunded` - the Stripe `checkout.session.completed`
  webhook refunded an undeliverable paid extension checkout. No actor. Metadata
  carries `purchase_id`, `cause` (`detached` | `not_installable`), `amount`,
  `currency` and `stripe_refund_id`.
- `system:account_deleted` - a platform operator deletes an account, via GraphQL
  `adminDeleteAccount` and REST `DELETE /v1/admin/accounts/{id}`. Emitted only on a
  real delete; the deleted account id is the target (rides in metadata, not the
  key column). Audit rows live in TimescaleDB, which the account CASCADE does not
  erase, so the record persists. Owner self-service dissolve is the separate
  account-scope `account:dissolved`.

  ```json
  { "account_id": "<uuid>", "reason": "operator_delete" }
  ```

- `system:account_permission_override_set` / `system:account_permission_override_removed` - a platform operator (`accounts:overrides-edit`) grants/revokes an account-level
  permission override, via GraphQL `adminSetAccountPermissionOverride` /
  `adminRemoveAccountPermissionOverride` and REST
  `PUT /v1/admin/accounts/{id}/permission-overrides` /
  `DELETE /v1/admin/accounts/{id}/permission-overrides/{permission}`. System-scoped
  because it is a cross-account operator action on a tenant's granted-permission
  surface; the target account is the metadata `account_id` (never the key column).
  Remove emits only when a row was actually removed. The `set` path additionally
  records `granted` and the operator's optional `reason`; metadata never carries a
  secret.

  ```json
  { "account_id": "<uuid>", "permission": "chat:ban", "granted": true, "reason": "temporary escalation" }
  ```

## Viewing Logs

Access the audit log via **Admin > Audit Log** (`/audit-log`). A filter card at the top exposes:

- **Type** - a dropdown with an "all types" entry and the catalogued audit
  event types, including erasure, crawler, account, user, and system events.
- **User ID** - free-text.
- **Account ID** - free-text.
- **From** / **To** - date pickers.

Filters apply on **Apply**; changing a filter alone does not refetch until the button is pressed (or the page changes).

Results render as a table with **Time**, **Type**, **User ID** (truncated to the
first 8 characters), **IP**, **Device**, **Location** (city, country), and a
**Details** toggle column. The **Device** column parses the event's captured
user agent at render time into a compact device / browser / operating-system
summary with a device icon (e.g. "Chrome 141 · macOS"). It never shows a raw or
bogus value and never guesses: a user agent it cannot read - absent, a
non-browser client such as `node`/`undici`/`axios`, a legacy web-server string,
or junk - renders as the localized **Unknown** ("Unbekannt" in German), as does
a missing IP; partial hits (a known browser with an unreadable OS, or vice-versa)
still show the part that is known. Clicking a row expands it to show the raw event
`metadata` JSON and, when present, the full raw user agent string - the forensic
source of truth the Device column is derived from. The current table does not
show the top-level `scope` column; use the API-level `scope` filter when you
need to narrow the admin view by audience.

Paging is 50 events per page with Previous / Next controls and a "page X of Y (N events)" counter.

## Location data

The **Location** column (and the `country` / `city` fields on each event) is filled by the optional [GeoIP service](../getting-started/installation.md#geoip), which resolves the event's client IP to a coarse country/city via MaxMind GeoLite2. `country` holds the ISO-3166-1 alpha-2 code (e.g. `DE`) and `city` the English city name; the column renders them together as `city, country`.

Enrichment is **fail-open**: `country` / `city` are left empty whenever GeoIP is disabled, its database is unavailable, or the client IP is missing, private/loopback, on the MaxMind privacy-exclusion list, or simply not found. The IP address itself is still recorded in those cases, and the audit log is fully functional either way.

GeoIP is **disabled by default**, so out of the box these fields are empty and the column shows nothing. Enabling GeoIP requires a MaxMind license key and, optionally, honours user opt-outs through the [Privacy Exclusions API](../getting-started/installation.md#geoip); see the [GeoIP configuration](../getting-started/installation.md#geoip) for the `LUMIO__GEOIP__*` settings.

## Permissions

Reading the audit log requires the `audit-log:read` permission. The dashboard
entry itself is gated on `admin:access`. The seeded `system_admin` role carries
both permissions explicitly; `is_system: true` protects that role from edits and
deletion, but does not bypass permission checks. The erasure operations are
separately gated by `admin:privacy-erase` (see
[Roles & Permissions](../developer-guide/rbac-permissions.md#adminprivacy-erase)).

This admin page is the operator audit surface and uses the **admin-scope**
`audit-log:read` (checked against the caller's admin role). The `account`- and
`user`-scoped logs are separate surfaces: `accountAuditLog` /
`GET /v1/account/audit-log` is gated by the identically-named **account-scope**
`audit-log:read` (a distinct permission checked against the account role), and
`myAuditLog` / `GET /v1/me/audit-log` is self-only, gated purely by a first-party
session with no permission. An account grant never unlocks this admin log, and
vice-versa.

## Storage

Audit events are persisted in TimescaleDB and queried via the admin API (`GET /v1/admin/audit-log`, GraphQL `adminAuditLog`). The admin UI reaches it through its own Next.js proxy route at `/api/audit-log`.

Each event exposes its `scope` on both protocols. The admin query accepts an
optional **`scope`** filter - `GET /v1/admin/audit-log?scope=system` or the
`scope` field on the `adminAuditLog` filter input - to narrow results to a single
audience (`user` | `account` | `system`); an unrecognized value is ignored. The
admin log is a superuser view, so with no `scope` filter it returns rows from
every scope. The admin Next.js proxy and UI do not currently forward a `scope`
filter.

---

## Admin / Billing

Source: https://docs.lumio.vision/admin/billing

# Billing

The Billing admin view is an at-a-glance dashboard of plan distribution and active subscriptions. It does **not** manage individual Stripe subscriptions, refunds, or manual overrides - those actions are still performed inside the Stripe Dashboard. This page is a monitoring surface only, with deeper subscription and coupon tooling living on dedicated admin pages.

## Where to find it

The page lives at `/billing`. It has **no sidebar entry** - navigate to it directly, or reach billing work through [Coupons](./coupons.md), [Subscriptions](./subscriptions.md), and [Plans](./plans.md), which are all in the sidebar's **Commerce** section.

## Quick start

1. Open `/billing`.
2. Scan the KPI cards at the top for total / free / pro / enterprise account counts.
3. Read the **Subscriptions** card for a count of active Stripe subscriptions and a link reminder that Stripe Dashboard is the source of truth for details.
4. For coupon work, jump to [Coupons](./coupons.md).
5. For plan-level configuration, jump to [Plans](./plans.md).

## Detailed walkthrough

### KPI grid

Four KPI cards:

- **Total Accounts** - every account in the system.
- **Free Accounts** - accounts on the `free` plan slug.
- **Pro Accounts** - accounts on the `pro` plan slug.
- **Enterprise Accounts** - a leftover tile from the dropped `enterprise` tier (removed by migration `20260415000009_drop_enterprise_plan`). It has no accounts behind it.

The page is a server component (`page.tsx` is `async`) and renders counts via a `getPlanStats()` helper. That helper returns hard-coded zeros - it is not wired to the admin API - so every card reads `0`. The translations and layout are final.

### Subscriptions card

A single card titled **Subscriptions** shows:

- "{count} active subscriptions" - a read-only count.
- A static footnote: "Detailed subscription management is available in the Stripe Dashboard."

There are no buttons, no refund flow, and no manual subscription editing here.

### Coming-soon banner

`apps/admin/messages/{en,de}.json` carries `billing.comingSoon` and `billing.comingSoonDescription` copy for a richer billing view. Neither string is rendered by the shipped page.

## Common scenarios

- **"How many paying customers do we have right now?"** - the Pro KPI reads `0` regardless; count Pro badges on the [Subscriptions](./subscriptions.md) or [Accounts](./accounts.md) list instead.
- **Refund / cancel a subscription** - not possible here. Go to Stripe Dashboard.
- **Find or cancel a developer credit note** - use [Credit Notes](./credit-notes.md) (`/credit-notes`).
- **Apply a manual coupon to an account** - use [Coupons](./coupons.md) to create the coupon, then apply it from the Stripe customer record.
- **Override a plan without Stripe** - use [Accounts](./accounts.md) → Plan Management and Limits. That change is independent of Stripe.

## Permissions

| Action | Permission |
|--------|-----------|
| Open the billing page | `billing:read` |

Entry also requires `admin:access`. System admins have this implicitly.

`billing:edit` exists in the admin permission registry but no endpoint or UI element enforces it today.

## API

There is no dedicated billing analytics endpoint. When `getPlanStats()` is wired up it will aggregate the admin accounts listing.

| UI action | GraphQL | REST |
|-----------|---------|------|
| Count accounts by plan | `adminAccounts` | `GET /v1/admin/accounts` |

For end-user billing actions (checkout, portal, cancel, invoices), see the non-admin billing REST endpoints in `apps/api/src/routes/billing.rs`:

- `POST /v1/billing/checkout`
- `POST /v1/billing/portal`
- `GET /v1/billing/status`
- `POST /v1/billing/cancel`
- `GET /v1/billing/invoices`
- `GET /v1/billing/validate-coupon`
- `POST /v1/webhooks/stripe`

These are **not** admin-scoped - they act on the authenticated user's own subscription.

## Tips & gotchas

- KPIs read zero - `getPlanStats()` returns constants. Don't treat the numbers on this page as data.
- Stripe is the source of truth. Manual DB edits here will drift out of sync with Stripe webhooks.
- There is no manual-override or refund UI today. If you need one, file an issue - there are currently no hidden admin flows for it.

## Related

- [Coupons](./coupons.md) - discount codes issued to Stripe
- [Subscriptions](./subscriptions.md) - per-account subscription overview
- [Plans](./plans.md) - plan definition and feature grid
- [Accounts](./accounts.md) - per-account plan override (independent of Stripe)

---

## Admin / Contract Declarations

Source: https://docs.lumio.vision/admin/contract-declarations

# Contract Declarations

## Overview

Open `/contract-declarations` in the admin app to review withdrawals and cancellations across accounts. The queue is ordered oldest first and defaults to open cases. Filter by status (`open`, `processed`, `rejected` or all) and kind (withdrawal or cancellation); **Load more** appends the next page.

Each card shows the details stored at receipt time, including the declarant, contract description or snapshot, requested cancellation terms, receipt delivery state, case reference and retention date. A public declaration has no account until an operator matches it.

## Processing a case

1. For a public declaration, use **Match** to associate it with an account and a plan or paid extension purchase. Confirm the target contract before acting in Stripe.
2. Review the request. Refunds are issued manually in Stripe. For a withdrawal, record the Stripe refund reference (`re_…`) when closing it. For a cancellation, mark whether the subscription was changed in Stripe.
3. Use **Close** to mark the case processed or rejected and add a note. An open case cannot be closed twice.
4. Use **Extend retention** when a legal hold requires a later date. The date can only move forward.

An ordinary signed-in cancellation may already show `processed` because Stripe accepted the period-end change. Extraordinary and public requests wait for an operator. Closing a declaration records the decision; it does not issue a refund or make a Stripe change by itself.

## Permissions and API

`contract-declarations:read` opens the queue and reads cases. `contract-declarations:edit` gates Match, Close and Extend retention; mutations also require an interactive session. These are **admin-scoped** permissions, seeded to `system_admin`, and are unavailable in account role pickers. The REST and GraphQL operations are documented in [Contract declarations](/api-reference/rest-api#contract-declarations).

---

## Admin / Credit Notes

Source: https://docs.lumio.vision/admin/credit-notes

# Credit Notes

## Overview

Open `/credit-notes` in the admin app (sidebar **Commerce → Credit notes**) to see the self-billed credit notes (*Gutschriften*) Lumio issued for developer payouts, and their cancellations, newest first. Notes of deleted developer profiles stay listed: they are marked **Profile deleted** and kept for the 8-year retention period. **Load more** appends the next 50.

Filter by a developer profile ID (UUID) to see one developer's notes; **Show all** removes the filter.

## Card contents

Each card shows the note as issued — an issued note is never edited:

| Part | Content |
|------|---------|
| Header | Number (`GS-<year>-<6 digits>`), **Credit note** or **Cancellation**, **Cancelled {date}** once cancelled, issue date |
| Supplier | Legal name and country copied from the developer's verification at issue |
| Developer profile | The profile ID, or **Profile deleted** |
| Service period | Start and end (Europe/Berlin) |
| Amounts | Net, VAT with rate, and gross; negative on a cancellation |
| VAT treatment | Germany 19 %, Germany small business (§ 19 UStG), EU reverse charge (§ 13b UStG) or outside the EU |
| E-mail | When the note was mailed to the developer, or **Not sent yet** |
| Cancellation | Reason (payout failed, developer objection, correction), the date the objection arrived, the operator who recorded it, and the payout / cancelled note IDs |

**PDF** downloads the stored document. While it is still being generated the card says **Document is being generated** instead.

## Cancelling a credit note

**Cancel note** appears on an effective credit note (not on a cancellation or an already cancelled note). It opens a dialog:

1. Choose the reason:
   - **Developer objection** — the developer objected to the note (§ 14 Abs. 2 S. 3 UStG). Enter the date the objection was received.
   - **Correction** — the note carries wrong data, for example an outdated address or tax detail.
2. Optionally tick **Issue a corrected credit note**: Lumio issues a new note for the same payout and period from the developer's current verification.
3. **Cancel credit note** issues the cancellation note (own number, negated amounts) and, if ticked, the corrected note in one step. A confirmation names the new numbers and the list reloads.

The dialog names the reason when it is refused:

| Message | Cause |
|---------|-------|
| The corrected note would total a different amount than was paid | `CREDIT_NOTE_AMOUNT_MISMATCH`: for example the developer's VAT status changed. Settle the difference first, or cancel without re-issuing |
| The developer's tax details are incomplete | `TAX_DETAILS_REQUIRED` on the re-issue. Cancel without re-issuing, or ask the developer to complete them |
| Only an effective credit note can be cancelled | The note was cancelled in the meantime. Reload the list |
| This credit note has no payout to re-issue it for | Re-issue is not possible for this note |
| Enter the date the objection was received | An objection needs its received date |

Every cancellation emits the audit event `system:developer_credit_note_cancelled`.

## Settling payouts

SEPA payouts, and Stripe or PayPal payouts whose answer the payout cycle did not receive, wait for an operator. Mark them paid or failed on the [Developer Payouts](./developer-payouts.md) page. A failed payout cancels its credit note automatically (reason **payout failed**).

## Permissions

| Action | Permission |
|--------|-----------|
| Open the page, download PDFs | `billing:read` |
| Cancel a credit note | `billing:edit` |
| List developer payouts | `billing:read` |
| Mark a developer payout paid or failed | `billing:edit` |

See [Developer Credit Notes](../features/developer-credit-notes.md) for numbering, VAT treatment, delivery and retention.

---

## Admin / Developer Payouts

Source: https://docs.lumio.vision/admin/developer-payouts

# Developer Payouts

## Overview

Open `/developer-payouts` in the admin app (sidebar **Commerce → Developer payouts**) to see the payouts of developer revenue, newest first. Payouts of deleted developer profiles stay listed and are marked **Profile deleted**. **Load more** appends the next 50.

The monthly payout cycle sends Stripe and PayPal payouts by itself (see [Developer Payouts](../features/developer-payouts.md)). Two kinds wait for an operator. They carry the **Needs an operator** badge and a highlighted card:

- **SEPA transfer**: Lumio does not send bank transfers. Transfer the amount by bank, then mark the payout paid.
- **Unknown provider answer**: the cycle sent the payout to Stripe or PayPal but got no answer (timeout, provider error). It is never sent again. Check with the provider whether it arrived, then mark it paid or failed.

## Filters

| Filter | Effect |
|--------|--------|
| **Status** | All statuses, or one of **Pending**, **Processing**, **Paid**, **Failed** |
| **Needs an operator** | Only the payouts that wait for an operator. Status is then fixed to **Pending** |

## Card contents

| Part | Content |
|------|---------|
| Header | Amount (EUR, the credit note's gross amount), status, method (**Stripe**, **PayPal**, **SEPA transfer**), **Needs an operator**, **Profile deleted**, creation time |
| Developer profile | The profile ID, or **Profile deleted** |
| Destination | The masked destination: Stripe account, PayPal e-mail (`j***@example.com`) or IBAN (`DE89****00`) |
| Payout ID | The payout's ID |
| Sent to provider | When the cycle handed it to Stripe or PayPal, or **Not sent** |
| Paid on | When it was completed |
| Stripe transfer / PayPal batch | The provider's ID, once there is one |

Times are shown in Europe/Berlin.

## Marking a payout paid or failed

A **Pending** or **Processing** payout shows **Mark paid** and **Mark failed**. Both open a confirmation dialog with the amount, method, destination and status. Neither can be undone.

- **Mark paid** — the SEPA transfer was sent, or the provider confirmed the payout arrived. The payout becomes **Paid**.
- **Mark failed** — only after the provider or bank confirmed that nothing arrived. The amount is credited back to the developer's balance and the payout's credit note is cancelled (reason **payout failed**, see [Credit Notes](./credit-notes.md)). The developer can request the payout again.

After the action the card shows the new status and a confirmation names the credited amount and the cancellation note's number.

The dialog names the reason when it is refused:

| Message | Cause |
|---------|-------|
| The payout cycle is sending this payout right now | `PAYOUT_BEING_SENT`: the cycle handed it to the provider less than 15 minutes ago, and marking it failed now could pay it twice. Try again after 15 minutes |
| This payout was already settled | `PAYOUT_NOT_IN_FLIGHT`: it is no longer pending or processing. Reload the list |
| This payout no longer exists | The payout was not found. Reload the list |

Marking a payout paid emits the audit event `system:developer_payout_completed`, marking it failed `system:developer_payout_failed` (both with `source: operator`).

## Permissions

| Action | Permission |
|--------|-----------|
| Open the page | `billing:read` |
| Mark a payout paid or failed | `billing:edit` |

The page uses `adminDeveloperPayouts`, `completeDeveloperPayout` and `failDeveloperPayout` (REST `GET /v1/admin/developer-payouts`, `POST /v1/admin/developer-payouts/{id}/complete` and `/fail`).

---

## Admin / Bot Commands

Source: https://docs.lumio.vision/admin/bot-commands

# Bot Commands

The Bot Commands view lets operators define **global** chat commands (available to every Lumio account out of the box) and inspect **per-account overrides** that accounts have customised on top of those globals. It also supports creating bot commands scoped to a single account.

## Where to find it

**Admin sidebar → Bot Commands** (`/bot-commands`). Two tabs: **Global Commands** and **Account Commands**.

## Quick start

1. Open **Admin → Bot Commands** on the **Global** tab.
2. Click **Create Global Command**.
3. Fill in the command name (no `!` prefix), description, platforms, minimum role, cooldowns, and pick a **Response Type**: Text, Template, or Automation.
4. For Text / Template, enter the response text (template placeholders like `{user.name}` are allowed in Template mode). For Automation, paste the target automation UUID.
5. Click **Save**. The command is live across all accounts immediately.

## Detailed walkthrough

### Global tab

Lists every command fetched with `scope=global`. Commands render as rows in a card list, not a table. Each row shows:

- `!name`, plus a **Global** badge and an **Enabled: OFF** badge when the command is disabled.
- The description, underneath the name.
- One outline badge per platform.
- The minimum role.

Response type and cooldowns are stored on the command but are not surfaced in the row - open the editor to see them.

Row actions (icon buttons):

- **Edit Command** (pencil) - opens the command editor pre-filled. Gated on `bot-commands:edit`.
- **Delete Command** (trash) - native confirm ("Are you sure you want to delete the command !{name}?"). Gated on `bot-commands:delete`.

A **Create Global Command** button sits above the list, gated on `bot-commands:create`.

### Account tab

Switches the fetch to `scope=account`. A search bar filters by account - the typed value is sent as the `account_id` query parameter. Rows use the same layout as the Global tab, with the owning account name shown alongside each command.

### Command editor

Fields:

- **Command Name** - string without leading `!`.
- **Description** - free text.
- **Response Type** - one of `text`, `template`, `automation`.
- **Response Text** - for `text` / `template`.
- **Automation ID** - UUID when Response Type is `automation`. Inline UUID validation ("Invalid UUID format. Expected: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx").
- **Platforms** - multi-select: twitch, youtube, kick, discord.
- **Minimum Role** - viewer / moderator / vip / broadcaster (platform-dependent).
- **Global Cooldown (s)** and **Per-User Cooldown (s)** - integer seconds.
- **Enabled** - boolean toggle.

### Create vs update

- Create - `POST /api/bot-commands` with the full body.
- Update - `PUT /api/bot-commands/{id}` with the mutated body.
- Delete - `DELETE /api/bot-commands/{id}` (confirm dialog first).

### Account-scoped commands and overrides

Accounts can override global commands (for example, changing the response text) without forking the command. The override lives in a separate table and is fetched alongside the global when the bot dispatches.

The admin **Account Commands** tab lists account-scoped commands - it does **not** render per-command override lists. Overrides are set account-side and inspected through the API:

- `POST /v1/bot-commands/{id}/override` (GraphQL `overrideGlobalCommand`) - set or update an override.
- `DELETE /v1/bot-commands/{id}/override` (GraphQL `removeGlobalCommandOverride`) - clear the override.
- `adminBotCommandOverrides(commandId)` - read every account's override of one global command.

## Common scenarios

- **Ship a new !lurk command to everyone** - Create Global Command, Response Type Text, response `"{user.name} is now lurking"`, enabled.
- **Quickly disable a misbehaving global** - open it in the editor, toggle Enabled off, Save. Accounts won't see it.
- **Spot which accounts customised a command** - query `adminBotCommandOverrides(commandId)` directly; there is no admin UI for it.
- **Wire a command to a complex automation** - set Response Type to Automation and paste the UUID from the account's Automation Builder.

## Permissions

| Action | Permission |
|--------|-----------|
| View global / account commands | `bot-commands:read` |
| Create a command | `bot-commands:create` |
| Edit a command | `bot-commands:edit` |
| Delete a command | `bot-commands:delete` |

Dashboard entry requires `admin:access`. System admins implicitly hold every permission above.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List global commands | `adminBotCommands(scope: "global")` | `GET /v1/admin/bot-commands?scope=global` |
| List per-account commands | `adminBotCommands(scope: "account", accountId)` | `GET /v1/admin/bot-commands?scope=account&account_id=X` |
| List account overrides for a global | `adminBotCommandOverrides(commandId)` | - |
| Create global command | `adminCreateGlobalCommand` | `POST /v1/admin/bot-commands` |
| Update command | `adminUpdateBotCommand` | `PUT /v1/admin/bot-commands/{id}` |
| Delete command | `adminDeleteBotCommand` | `DELETE /v1/admin/bot-commands/{id}` |
| Account override set | `overrideGlobalCommand(commandId, input)` | `POST /v1/bot-commands/{id}/override` |
| Account override clear | `removeGlobalCommandOverride(commandId)` | `DELETE /v1/bot-commands/{id}/override` |

## Tips & gotchas

- Automation UUIDs are **account-specific**. A global command that calls an automation only fires for accounts that own that automation - typically you want Response Type Text or Template for globals.
- Platforms without the required chat scopes silently skip dispatch; the command stays listed but never runs.
- Template placeholders follow the bot's template engine.
- Editing a global with active account overrides leaves the overrides intact - they still apply on top of the new base.

## Related

- [Bot Control](./bot-control.md) - runtime pause / resume of bots
- [Providers](./providers.md) - kill-switches that disable entire bot platforms
- [Discord Guilds](./discord-guilds.md) - Discord-specific routing for slash commands

---

## Admin / Bot Control

Source: https://docs.lumio.vision/admin/bot-control

# Bot Control

Bot Control is the runtime switchboard for every chat / social bot Lumio runs on behalf of accounts. It surfaces each account × platform combination and lets operators pause or resume the bot without touching account-level configuration. Use it for incident response, platform rate-limit flare-ups, or when debugging a single account's bot behaviour.

## Where to find it

**Admin sidebar → Bot Control** (`/bot-control`).

## Quick start

1. Open **Admin → Bot Control**.
2. Filter by platform and/or search by account name or ID.
3. Find the account card and, inside it, the row for the misbehaving platform.
4. Click **Pause** to stop it immediately, or **Resume** to bring it back.
5. Watch the status badge update: **Active**, **Paused**, or **No Connection**.

## Detailed walkthrough

### Layout

The page fetches every account × platform status in one call and renders **one card per account**. The card header is the account name plus the first 8 characters of the account ID. Inside the card, each platform the account touches gets a row.

### Status badges

Each row shows one of three states, derived from `has_channel_connection` and `bot_enabled`:

- **Active** - the account has a channel connection and the bot is enabled.
- **Paused** - the connection exists but the bot is explicitly disabled. No messages are sent or received.
- **No Connection** - the account has no channel connection for this platform. Pause / Resume is hidden.

### Filters

- **Search** - client-side match against account name or account ID over the already-loaded data. Not debounced, because nothing is refetched.
- **Platform** - dropdown with "All Platforms" plus the distinct platforms actually present in the loaded data, so the option list reflects real connections rather than a fixed platform list.

### Row contents

Platform icon, platform name, bot username (or `--`), status badge, and the Pause / Resume button. Rows without a connection show the badge and no button.

### Pause / Resume

The button posts to `/api/bot-statuses/toggle` with `{ account_id, platform, enabled }`. The backend flips the bot-enabled flag and publishes the change on a Redis pub/sub bot-action channel so the relevant bot worker picks it up. The UI updates the row optimistically instead of refetching the whole list.

The Pause / Resume button is **not** permission-gated in the UI - enforcement is server-side on `bot-control:edit`. An admin holding only `bot-control:read` sees the button but the call returns 403.

## Common scenarios

- **Twitch platform incident** - filter by `twitch`; there is no select-all, so pause accounts one by one or use the [Providers](./providers.md) page to flip the global kill-switch.
- **Customer-reported bot spam** - find the account, pause it on the affected platform, investigate bot commands / modules.
- **Resume after maintenance** - filter by platform, resume each paused row.
- **Audit which accounts have a Discord bot connected** - filter by `discord`; rows with **Active** or **Paused** have a connection, **No Connection** does not.

## Permissions

| Action | Permission |
|--------|-----------|
| View bot statuses | `bot-control:read` |
| Pause / resume a bot | `bot-control:edit` |

Dashboard entry requires `admin:access`. System admins hold these implicitly.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List bot statuses | `adminBotStatuses(accountId)` | `GET /v1/admin/bot-control/statuses` |
| Pause / resume | `adminToggleBotForAccount` | `PUT /v1/admin/bot-control/{account_id}/{platform}` |

The frontend calls its own Next.js proxy routes at `/api/bot-statuses` and `/api/bot-statuses/toggle`. Filtering and searching happen entirely in the browser - neither the query string nor the platform dropdown reaches the API.

## Tips & gotchas

- Pause is per account × platform - not global. For a platform-wide halt, toggle the kill-switch on [Providers](./providers.md) instead.
- Pausing does **not** revoke OAuth tokens. The bot connection stays authenticated and resumes instantly when toggled back.
- A bot with **No Connection** cannot be paused because there is nothing to pause. It has to be connected first from the account's side.
- The toggle is idempotent - the request carries the desired `enabled` value, so calling pause on an already-paused bot is a no-op.

## Related

- [Providers](./providers.md) - platform-level kill-switches and global bot identity
- [Bot Commands](./bot-commands.md) - command registry executed by these bots
- [Discord Guilds](./discord-guilds.md) - Discord-specific guild-to-account mapping

---

## Admin / Curated Playlists

Source: https://docs.lumio.vision/admin/copyright-playlists

# Curated Playlists

Curated Playlists are system-managed Spotify playlists of verified copyright-safe songs, grouped by genre (lofi, edm, ncs, …). Lumio streamers can pull from them via the end-user safe-songs UI. The admin view is where operators create, edit, delete, and sync these playlists with Spotify.

## Where to find it

**Admin sidebar → Curated Playlists** (`/copyright-playlists`). Detail pages live at `/copyright-playlists/{id}`.

## Quick start

1. Open **Admin → Curated Playlists**.
2. Click **Create Playlist**, pick a genre slug (e.g. `lofi`), give it a name (e.g. `Lumio Safe - Lo-Fi`), and submit.
3. Click the row to open the detail page.
4. Use the search bar to find safe songs already in the catalog and click **Add** to append tracks to the playlist.
5. Click **Sync Now** to push the playlist to Spotify (or re-pull metadata). A success toast confirms the sync.

## Detailed walkthrough

### Playlist list (`/copyright-playlists`)

Columns:

- **Genre** - slug, rendered as an outline badge.
- **Playlist Name** - display name; clicking it opens the detail page.
- **Tracks** - count.
- **Spotify** - external-link icon to `open.spotify.com/playlist/…`, shown only once the playlist has a Spotify playlist ID.
- **Last Updated** - last edit / sync date.
- **Actions** - icon buttons in this order: **Edit** (pencil), **Sync** (refresh, spins while running), **Delete** (trash).

The card header reads `Curated Playlists ({N})` and carries the **Create Playlist** button. None of the row actions are permission-gated in the UI - the enforcement is server-side.

Create / Edit dialog fields:

- **Genre** (placeholder: "e.g. lofi, edm, ncs...").
- **Playlist Name** (placeholder: "Lumio Safe - Lo-Fi").

### Playlist detail (`/copyright-playlists/[id]`)

Two panels:

1. **Tracks** - the current track list for this playlist. Each row has a **Remove** button.
2. **Safe Songs Search** - lookup against the global safe-songs catalog with search box. Each match has an **Add** button.

**Sync Now** triggers a server-side reconciliation with Spotify, returning how many tracks were added and removed. After success the UI shows "Sync completed successfully."

### Sync semantics

Sync pushes the track list to the linked Spotify playlist via Spotify's API. If the playlist isn't linked yet (missing Spotify playlist ID), sync is a no-op until an operator runs the underlying import flow. Failed syncs surface an error toast and leave the local list intact.

## Common scenarios

- **Launch a new genre playlist** - create, populate with 20–50 safe songs, sync once, share the Spotify link.
- **Track request from a streamer** - search the catalog; if the track exists, add it; if not, approve it first via [Copyright Recommendations](./copyright-recommendations.md) so it enters the safe-songs table.
- **Remove a track that turned out to be unsafe** - click Remove on the detail page, then go to [Copyright Reports](./copyright-reports.md) to mark the track unsafe globally.
- **Weekly sync** - ops routine: open each playlist, click **Sync Now**.

## Permissions

Curated playlists are an account-less **global** table (`copyright_curated_playlists`), so their management is enforced at **admin (system) scope**, not account scope.

| Action | Permission |
|--------|-----------|
| Create / edit / delete / sync a playlist, add / remove tracks | `copyright:edit` - **admin scope** (`AdminPermissionGuard`) |
| List a playlist's tracks (`curatedPlaylistTracks`) | `copyright:read` |
| List playlists (`publicSystemPlaylists`) | none - public |

Every curated-playlist **mutation** - including **delete** and **sync** - is guarded by the admin-only `AdminPermissionGuard("copyright:edit")`; an account-level `copyright:edit` grant does **not** reach this surface (ZAF-734). `copyright:delete` exists but guards the safe-song / blocked-song / playlist-sync entries, not curated playlists. The `curatedPlaylistTracks` read stays on `copyright:read` because the identical rows are also served unauthenticated at `GET /v1/playlists/{id}`, so it exposes nothing new.

Dashboard entry requires `admin:access`. System admins hold every copyright permission at admin scope.

## API

Curated-playlist **management** uses GraphQL; there are no `/v1/copyright/playlists*` management endpoints. Public reads have REST twins at `GET /v1/playlists` and `GET /v1/playlists/{id}`, both gated by `feature:copyright_detection`. The paths below are the admin app's own Next.js proxy routes, which execute the GraphQL operations in the middle column.

| UI action | GraphQL | Admin proxy route |
|-----------|---------|-------------------|
| List playlists | `publicSystemPlaylists` | `GET /api/copyright/playlists` |
| Create playlist | `createCuratedPlaylist(genre, spotifyPlaylistName)` | `POST /api/copyright/playlists` |
| Edit playlist | `updateCuratedPlaylist(id, genre, spotifyPlaylistName)` | `PATCH /api/copyright/playlists/{id}` |
| Delete playlist | `deleteCuratedPlaylist(id)` | `DELETE /api/copyright/playlists/{id}` |
| Sync playlist | `syncCuratedPlaylist(id)` | `POST /api/copyright/playlists/{id}/sync` |
| List tracks in playlist | `curatedPlaylistTracks(playlistId)` | `GET /api/copyright/playlists/{id}/tracks` |
| Search safe songs | `publicSafeSongs(search, limit, offset)` | `GET /api/copyright/safe-songs?search=...` |
| Add track to playlist | `addToCuratedPlaylist(playlistId, safeSongId)` | `POST /api/copyright/playlists/{id}/tracks` |
| Remove track from playlist | `removeFromCuratedPlaylist(playlistId, safeSongId)` | `DELETE /api/copyright/playlists/{id}/tracks/{song_id}` |

A separate public REST surface lists the same playlists and provides individual playlist details for the marketing site. It requires no authentication and returns `403 FEATURE_DISABLED` when `feature:copyright_detection` is off.

## Tips & gotchas

- The genre field is free text (placeholder: "e.g. lofi, edm, ncs..."), not a validated slug. `lo-fi` and `lofi` are different values - pick one convention and stick with it.
- **Sync Now** is idempotent but not instant; it can take a few seconds on a large playlist.
- Delete is permanent and removes the mapping only - the Spotify playlist itself is **not** deleted.
- The safe-songs catalog is shared with [Copyright Recommendations](./copyright-recommendations.md); approving a recommendation there is how new candidate tracks enter the pool.
- Delete uses a native browser confirm: "Are you sure you want to delete this playlist?"

## Related

- [Copyright Reports](./copyright-reports.md) - user reports against specific tracks
- [Copyright Recommendations](./copyright-recommendations.md) - user-suggested safe songs awaiting approval
- [Copyright Review](./copyright-review.md) - combined vote-candidate review surface

---

## Admin / Copyright Recommendations

Source: https://docs.lumio.vision/admin/copyright-recommendations

# Copyright Recommendations

Copyright Recommendations are user-submitted suggestions that a specific track is copyright-safe and should be added to the curated safe-songs catalog. Users vote or flag a track via the streamer dashboard; those submissions land in this queue with `report_type = recommendation`. Admins accept (promoting the track to the safe catalog, optionally into a specific Curated Playlist) or dismiss (rejecting the suggestion).

## Where to find it

**Admin sidebar → Recommendations** (`/copyright-recommendations`).

## Quick start

1. Open **Admin → Recommendations**.
2. Default status filter is **Pending**; flip to **Confirmed** or **Dismissed** to review past decisions.
3. Read the song / artist / category for each row.
4. Click **Accept** to promote to safe songs. In the dialog, optionally pick a Curated Playlist to drop the track into.
5. Click **Dismiss** to reject the suggestion.

## Detailed walkthrough

### Status filters

A pill bar across the top: **All**, **Pending**, **Confirmed**, **Dismissed**. **Pending** is the default landing state. A `{N} total` counter sits at the right end of the bar; the list loads 50 rows at a time with no pagination controls.

### Recommendation cards

Recommendations render as cards, not table rows. Each card shows:

- **Song** - track title, with an external-link icon to `open.spotify.com/track/…` when a Spotify track ID is present.
- **Artist** - track artist.
- **Category** - the `recommendation_category` value, as an outline badge, when set.
- **Status** - coloured badge.
- **Confirmations** - `{N} confirmations`, the count of other users who upvoted the same recommendation.

Card actions, rendered only while the status is `pending`:

- **Accept** - opens the Accept Recommendation dialog.
- **Dismiss** - one-click reject.

### Accept Recommendation dialog

- Title: "Accept Recommendation".
- Song name, artist, and the outcome hint "Will be added to global safe list".
- **Add to curated playlist (optional)** - dropdown of all curated playlists; default is **None**. Rendered only when at least one curated playlist exists.
- **Accept** - runs the shared approve mutation with the optional `addToPlaylistId`.

Accepting inserts the track into the safe-songs catalog and, when a playlist is selected, also appends it to that playlist's track list.

## Common scenarios

- **Lo-fi track submitted by community** - accept and route into the `lofi` curated playlist.
- **Obvious copyrighted track mis-recommended** - dismiss; the recommendation moves to the Dismissed tab.
- **Duplicate suggestions** - the Confirmations column reveals how many users agree. Don't accept the same track twice; the second recommendation can be dismissed.
- **Batch processing** - cycle through Pending, decide one by one. There is no bulk action.
- **Filter state is not in the URL** - it lives in React state and resets on reload.

## Permissions

| Action | Permission |
|--------|-----------|
| View recommendations | `copyright:read` |
| Accept / dismiss | `copyright:moderate` |

`copyright:moderate` governs the **global**, cross-account safe/blocked lists and is distinct from `copyright:edit`. Dashboard entry requires `admin:access`. System admins implicitly hold both.

## API

Recommendations share the `copyright_reports` table with copyright reports, distinguished by the `report_type` column (`recommendation` vs `copyright`). They use the same approve / dismiss mutations as reports.

This surface is GraphQL-first. There are no `/v1/copyright/recommendations` or `/v1/copyright/reports*` REST endpoints - the paths below are the admin app's own Next.js proxy routes.

| UI action | GraphQL | Admin proxy route |
|-----------|---------|-------------------|
| List recommendations (filtered) | `adminReports(reportType: "recommendation", status, limit, offset)` | `GET /api/copyright/recommendations?status=...` |
| Accept (with optional playlist) | `approveReport(id, addToPlaylistId)` | `POST /api/copyright/reports/{id}/approve` |
| Dismiss | `dismissReport(id)` | `POST /api/copyright/reports/{id}/dismiss` |
| Curated playlists for the dropdown | `publicSystemPlaylists` | `GET /api/copyright/playlists` |

The page is server-rendered: `page.tsx` runs the `adminReports` and `publicSystemPlaylists` queries through `serverGqlSSR` and hands the results to the client list, which refetches through the proxy whenever the status filter changes.

## Tips & gotchas

- Accept is destructive-ish - the track enters the global safe catalog. Review the artist + track carefully.
- The playlist dropdown is optional, and disappears entirely when no curated playlists exist. Accepting without picking a playlist still promotes the track to the catalog; it just doesn't appear in any curated playlist yet.
- Dismissed recommendations can be re-submitted by the same user later. The UI does not dedupe across time.
- Reports and recommendations share one mutation; accepting a recommendation is implemented as `approveReport` internally.

## Related

- [Copyright Reports](./copyright-reports.md) - user reports against unsafe tracks (opposite polarity)
- [Copyright Review](./copyright-review.md) - combined vote-candidate review surface
- [Curated Playlists](./copyright-playlists.md) - where accepted tracks can be routed
- [Abuse Reports](./abuse-reports.md) - reports filed against the recommendation system itself

---

## Admin / Copyright Reports

Source: https://docs.lumio.vision/admin/copyright-reports

# Copyright Reports

Copyright Reports are user submissions flagging that a specific track is **not** copyright-safe and should be removed from the safe catalog (or never added). They sit alongside [Copyright Recommendations](./copyright-recommendations.md) in the same underlying table but with `report_type = copyright`. Admins review each pending report and either approve it (marking the track unsafe) or dismiss it (keeping the track as-is).

## Where to find it

**Admin sidebar → Copyright Reports** (`/copyright-reports`).

## Quick start

1. Open **Admin → Copyright Reports**.
2. The default filter is **All**; switch to **Pending**, **Confirmed**, or **Dismissed** to narrow the list.
3. Read the song / artist / category and confirmation count.
4. Click **Approve** to confirm the report. For `recommendation` rows the dialog also offers a Curated Playlist to drop the track into.
5. Click **Dismiss** to reject the report and leave the track as-is.

## Detailed walkthrough

### Status filters

A pill bar in this order: **All**, **Pending**, **Confirmed**, **Dismissed**. **All** is the default. A `{N} total` counter sits at the right end of the bar. The list loads 50 rows at a time and has no pagination controls.

### Report rows

Each row shows:

- **Song** - track title.
- **Artist** - track artist.
- **Category** - submission category.
- **Type** - `copyright` (this page) or `recommendation` (on the Recommendations page).
- **Status** - coloured badge (pending = secondary, confirmed = default, dismissed = outline).
- **Confirmations** - number of other users who flagged the same track.
- **Date** - submission date.
- **Actions** - **Approve** and **Dismiss**, rendered only while the row is `pending`.

The song cell also carries an external-link icon to `open.spotify.com/track/…` when the row has a Spotify track ID.

### Approve Report dialog

- Title: "Approve Report".
- Shows song name, artist, and an outcome hint: "Will be added to global blocked list" for `copyright` rows, "Will be added to global safe list" for `recommendation` rows. The dialog is shared with the Recommendations page.
- **Add to curated playlist (optional)** - dropdown, rendered only when the row type is `recommendation` **and** at least one curated playlist exists. Copyright reports don't use this field.
- **Approve** - submits.

### Confirmations signal

Tracks with high confirmation counts are higher-confidence reports. The UI does not auto-approve; every confirmation is just a signal for the admin.

## Common scenarios

- **Track flagged by 20+ streamers** - review once, approve, track is removed from the safe catalog.
- **Single-user report against a genuinely safe track** - dismiss. The track stays safe; the report moves to the Dismissed tab for audit.
- **Repeat offender artist** - approving one track doesn't auto-approve future reports for the same artist. Each track is handled individually.
- **Incorrectly approved previously** - there is no "unapprove" in the UI. Handle via DB for now.

## Permissions

| Action | Permission |
|--------|-----------|
| View reports (`adminReports`) | `copyright:read` - **admin scope** (`AdminPermissionGuard`) |
| Approve / dismiss | `copyright:moderate` |

`adminReports` reads the account-less global `copyright_reports` table and returns reports of **every** status (the public `publicReports` query is limited to pending), so it is guarded by the admin-only `AdminPermissionGuard("copyright:read")`; an account-level `copyright:read` grant does not reach it (ZAF-734). `copyright:moderate` governs the **global**, cross-account blocked/safe lists and is distinct from `copyright:edit`, which only touches an account's own lists. Dashboard entry requires `admin:access`. System admins implicitly hold all three.

## API

This surface is GraphQL-first. There are no `/v1/copyright/reports*` REST endpoints - the paths below are the admin app's own Next.js proxy routes, which execute the GraphQL operations in the middle column.

| UI action | GraphQL | Admin proxy route |
|-----------|---------|-------------------|
| List reports (filtered) | `adminReports(status, reportType, limit, offset)` | `GET /api/copyright/reports?status=...` |
| Approve | `approveReport(id, addToPlaylistId)` | `POST /api/copyright/reports/{id}/approve` |
| Dismiss | `dismissReport(id)` | `POST /api/copyright/reports/{id}/dismiss` |
| Submit a copyright vote (user side) | `confirmCopyrightReport(reportId, input)` | `POST /v1/copyright/vote` (REST) |

The page is server-rendered: `page.tsx` runs the `adminReports` query and the curated-playlist query through `serverGqlSSR` and hands the results to the client list, which refetches through the proxy whenever a filter changes.

## Tips & gotchas

- Reports and Recommendations share the `copyright_reports` table, the `adminReports` query, and the approve/dismiss mutations; routing is by the `report_type` column, not by URL.
- Approving a `copyright` report does not automatically remove the track from any existing [Curated Playlists](./copyright-playlists.md). Do the cleanup there as a second step.
- Dismissing a report does **not** penalise the reporter. There is no reporter-reputation system today.
- If the same track has both active copyright reports and active recommendations, handle the copyright one first - marking unsafe is higher-priority than promoting.
- Filter state lives in React state only - it is not reflected in the URL and is lost on reload.

## Related

- [Copyright Recommendations](./copyright-recommendations.md) - positive-polarity counterpart
- [Copyright Review](./copyright-review.md) - combined vote-candidate queue
- [Curated Playlists](./copyright-playlists.md) - where approved safe tracks live
- [Abuse Reports](./abuse-reports.md) - meta-reports against the copyright reporting system

---

## Admin / Copyright Review

Source: https://docs.lumio.vision/admin/copyright-review

# Copyright Review

Copyright Review is the fast triage surface for **pending** community submissions. It loads every pending row from the shared `copyright_reports` table and splits it into two tabs by `report_type`: `copyright` submissions (candidates to block) and `recommendation` submissions (candidates to mark safe). Unlike [Copyright Reports](./copyright-reports.md), it carries no status filter and no history - only what still needs a decision.

## Where to find it

**Admin sidebar → Copyright Review** (`/copyright-review`).

## Quick start

1. Open **Admin → Copyright Review**.
2. Pick a tab: **Blocked Candidates** or **Safe Candidates**. Each tab header carries its own count.
3. For each candidate, read the song, artist, confirmation count, and category.
4. Click **Approve** to accept the submission and move the track into the blocked/safe catalog.
5. Click **Dismiss** to reject the candidate without changing catalog state.

## Detailed walkthrough

### Tabs

The page renders a tab bar, not side-by-side columns. Only one list is visible at a time:

- **Blocked Candidates (N)** - pending rows with `report_type = copyright`. Approving marks the track copyright-blocked globally.
- **Safe Candidates (N)** - pending rows with `report_type = recommendation`. Approving marks the track copyright-safe globally.

The split is by `report_type`, not by which vote count is larger. Both tabs are populated from a single `status=pending` fetch and filtered client-side.

### Candidate cards

Each candidate renders as a card showing:

- Song title, with an external-link icon to `open.spotify.com/track/…` when a Spotify track ID is present.
- Artist.
- `{confirmation_count} copyright votes` - one confirmation counter per row, whichever tab it sits in.
- The submission category, when set.

There is no separate "safe votes" tally on a row.

### Row actions

- **Approve** - calls `POST /api/copyright/reports/{reportId}/approve` and refetches, dropping the row from the queue.
- **Dismiss** - calls `POST /api/copyright/reports/{reportId}/dismiss` and refetches.

Both proxy routes execute the same GraphQL mutations as [Copyright Reports](./copyright-reports.md) / [Copyright Recommendations](./copyright-recommendations.md); the Review page is a pending-only view over the same dataset.

### Empty state

When the active tab has no candidates: "No candidates to review."

## Common scenarios

- **High-traffic triage session** - work through both tabs, approving clear majorities and dismissing ambiguous ones.
- **Policy change** - review the Safe Candidates tab to validate community consensus before approving a new genre's picks.
- **Suspected brigading** - if a single track in Blocked Candidates has an absurd confirmation count coming from fresh accounts, dismiss and investigate via [Abuse Reports](./abuse-reports.md).
- **Cross-check with external copyright sources** - before approving a Blocked candidate, confirm the track is actually copyrighted (Spotify's own "Content ID Block" metadata is a decent heuristic).

## Permissions

| Action | Permission |
|--------|-----------|
| View candidates | `copyright:read` |
| Approve / dismiss | `copyright:moderate` |

`copyright:moderate` is a distinct permission from `copyright:edit`: it governs the **global**, cross-account blocked/safe lists, while `copyright:edit` only touches an account's own lists. Dashboard entry requires `admin:access`. System admins implicitly hold both.

## API

This surface is GraphQL-first. There are no `/v1/copyright/reports*` REST endpoints - the paths below are the admin app's own Next.js proxy routes, which execute the GraphQL operations in the middle column.

| UI action | GraphQL | Admin proxy route |
|-----------|---------|-------------------|
| List pending candidates | `adminReports(status: "pending")` | `GET /api/copyright/reports?status=pending` |
| Approve a candidate | `approveReport(id, addToPlaylistId)` | `POST /api/copyright/reports/{id}/approve` |
| Dismiss a candidate | `dismissReport(id)` | `POST /api/copyright/reports/{id}/dismiss` |

Related backend surfaces, callable directly:

| Purpose | GraphQL | REST |
|---------|---------|------|
| User-side vote submission | `confirmCopyrightReport` | `POST /v1/copyright/vote` |
| Raw vote candidates | `voteCandidates` | `GET /v1/copyright/vote-candidates` |
| Approve a raw vote candidate | - | `POST /v1/copyright/vote-candidates/{track_id}/approve` |
| Dismiss a raw vote candidate | - | `POST /v1/copyright/vote-candidates/{track_id}/dismiss` |

The `vote-candidates` REST endpoints are gated on `copyright:moderate` as well.

## Tips & gotchas

- Approve is **not** reversible from the UI. Double-check the confirmation count and confirm the correct tab (Blocked vs Safe) before clicking.
- The page is community-moderation at its rawest - brigading and sockpuppet voting are possible. Spot-check confirmation counts via the underlying reports query.
- Approving a Safe candidate here is exactly the same mutation as approving a recommendation in [Copyright Recommendations](./copyright-recommendations.md) - but without the optional playlist dropdown, so the track lands in the safe catalog and no curated playlist.
- This page surfaces only `pending` candidates. For historical review use the [Copyright Reports](./copyright-reports.md) page with a status filter.

## Related

- [Copyright Reports](./copyright-reports.md) - granular per-report view
- [Copyright Recommendations](./copyright-recommendations.md) - positive-polarity per-report view
- [Curated Playlists](./copyright-playlists.md) - where approved safe tracks live
- [Abuse Reports](./abuse-reports.md) - meta-reports against the voting system

---

## Admin / Coupons

Source: https://docs.lumio.vision/admin/coupons

# Coupons

Coupons are discount codes that end users can apply during Stripe checkout. The admin Coupons view is the CRUD surface: create new codes, see redemption counts, and deactivate codes that should no longer be usable.

## Where to find it

**Admin sidebar → Coupons** (`/coupons`).

## Quick start

1. Open **Admin → Coupons**.
2. Click **Create Coupon**.
3. Fill in a code (e.g. `LAUNCH20`), optional description, discount type (Percentage or Fixed Amount), value, optional max redemptions (leave blank for unlimited), and optional valid-until date.
4. Click **Create**. The row appears in the list with an **Active** badge.
5. To retire a code, click **Deactivate** on its row - existing subscriptions that used it keep their discount; no new redemptions are possible.

## Detailed walkthrough

### Coupons table

Columns:

- **Code** - the code string users type at checkout (case sensitive).
- **Discount** - formatted as `20%` or `$5.00` depending on discount type.
- **Redemptions** - count of successful uses, rendered as `used / max` when a max-redemptions cap is set.
- **Valid Until** - expiry timestamp or `-` if unlimited.
- **Status** - **Active** or **Inactive** badge.
- **Actions** - **Deactivate** button (hidden for already-inactive coupons).

### Create Coupon dialog (`create-coupon-dialog.tsx`)

Fields:

- **Code** - e.g. `LAUNCH20`.
- **Description** - optional free text.
- **Discount Type** - a dropdown with `Percentage` (`percent`) and `Fixed Amount` (`fixed`).
- **Discount Value** - integer. For percentage it's 1–100; for fixed amount it's cents or minor units for the configured Stripe currency.
- **Max Redemptions** - integer; leave blank for **Unlimited**.
- **Valid Until** - optional date.

Create button triggers `POST /api/coupons`; while submitting the button shows "Creating…" and is disabled.

### Deactivating

Deactivate sets the coupon's `active` flag to `false` without deleting the row. Existing redemptions remain valid via Stripe; new redemptions are rejected.

There is **no hard delete**. `DELETE /v1/admin/coupons/{id}` and the `adminDeactivateCoupon` mutation both deactivate - the row is never removed. Removing a coupon permanently requires a direct DB change.

## Common scenarios

- **Launch promotion** - create `LAUNCH20` at 20% for the first 100 redemptions, expiry in 7 days.
- **Influencer code** - percentage coupon with no expiry, unlimited redemptions.
- **Retire a leaked code** - click **Deactivate**; existing paying customers keep their discount.
- **Stripe-level refund** - not done here. Refunds are applied in the Stripe Dashboard against the invoice, not against the coupon.

## Permissions

| Action | Permission |
|--------|-----------|
| View coupon list / detail | `coupons:read` |
| Create a coupon | `coupons:create` |
| Edit / deactivate a coupon | `coupons:edit` |

Dashboard entry requires `admin:access`. System admins implicitly hold every coupons permission.

`coupons:delete` exists in the admin permission registry but no endpoint enforces it - the delete route is guarded by `coupons:edit` and performs a deactivation.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List coupons | `adminCoupons` | `GET /v1/admin/coupons` |
| Get coupon | `adminCoupon` | `GET /v1/admin/coupons/{id}` |
| Create coupon | `adminCreateCoupon` | `POST /v1/admin/coupons` |
| Update coupon | `adminUpdateCoupon` | `PUT /v1/admin/coupons/{id}` |
| Deactivate coupon | `adminDeactivateCoupon` | `DELETE /v1/admin/coupons/{id}` (soft - sets `active = false`) |
| End-user validate coupon | - | `GET /v1/billing/validate-coupon?code=X` |

## Tips & gotchas

- Codes are case sensitive. `LAUNCH20` and `launch20` are different coupons - the UI does not normalise.
- Deactivation is soft and is the only removal path. It keeps redemption history intact.
- The discount value field is raw - percentage `20` means 20%, fixed amount `500` means 500 minor units (e.g. 5.00 USD). Document the convention in the description field for future admins.
- Max redemptions is enforced at redemption time. Concurrent redemptions at the limit are a race - Stripe wins.

## Related

- [Billing](./billing.md) - account-level subscription overview
- [Subscriptions](./subscriptions.md) - per-account subscription listing
- [Plans](./plans.md) - plans the coupon can be applied against

---

## Admin / Developer Limits

Source: https://docs.lumio.vision/admin/developer-limits

# Developer Limits

Admins can configure per-developer and per-extension limits to control resource usage on the extension platform.

## Sound limits

Each extension has three configurable sound limits. Each limit resolves in priority order:

| Priority | Source | Where to set |
|----------|--------|--------------|
| 1 (highest) | Per-extension override | Admin → Hub → Extensions → the extension's row |
| 2 | Per-developer override | Admin → Hub → Developers → developer detail → "Limit Overrides" |
| 3 (lowest) | Platform default | See defaults below |

| Limit key | Default | Description |
|-----------|---------|-------------|
| `max_sounds_per_extension` | 50 | Maximum bundled sounds per extension |
| `max_sound_file_size` | 10 MB (10 485 760 bytes) | Maximum size per individual sound file |
| `max_sound_storage_bytes` | 200 MB (209 715 200 bytes) | Total sound storage across all sounds in an extension |

The two size limits are stored in **bytes**; the admin forms take and display **MB** and convert on save. Every resolved limit is returned with a `source` marker of `extension`, `developer`, or `default`.

System extensions install with limit checks skipped - they are trusted and bypass sound-limit enforcement at install time.

## Setting developer limits

1. Navigate to **Admin → Hub → Developers**
2. Click a developer to open their detail page
3. In the **Limit Overrides** section, set values for the three sound limits. Max Sounds per Extension accepts 0–500; the two size fields take MB.
4. Each field has its own **Save** button, and a **Reset** button appears once the field has a value - Reset clears the override back to the platform default.

The **Limit Overrides** section is rendered only for admins holding `developer-limits:edit`.

The override applies to all extensions owned by this developer (unless an extension has its own override).

## Setting per-extension limits

1. Navigate to **Admin → Hub → Extensions**
2. Find the extension in the list
3. Edit the limit cells inline - max sounds, file size, and storage each have their own editable cell, gated on `developer-limits:edit`

Leave a field empty to use the developer's limit or the platform default.

## How limits are enforced

- **CLI (`lumio deploy`)** - fetches the resolved limits from the API and pre-flights count, per-file size, and total storage before uploading. Blocks the deploy with a descriptive error if exceeded. It falls back to the platform defaults (50 / 10 MB / 200 MB) when the limits call fails.
- **Server (upload endpoint)** - validates the sound count, file sizes, and total storage in the manifest against the resolved limits. Returns a `PlanLimitReached` error if exceeded.
- **Server (install)** - defence-in-depth check at install time. A sound count over the resolved limit logs a warning and truncates; total storage over the resolved limit fails the whole install. Neither should trigger if upload validation ran. Skipped entirely for system extensions.

## Limit Requests

Developers can request limit increases from their own developer limits page at `/dashboard/settings/developer/limits`. Admins review them on the global **Limit Requests** page at `/developers/limit-requests`, which has **no sidebar entry** - navigate to it directly. A per-developer **Limit Requests** section also appears on each developer's detail page.

### Review workflow

1. Open `/developers/limit-requests` (or the Limit Requests section on a developer's detail page)
2. Pick a status tab and open a request to see its details, including the requested value, the current value, and the developer's reason
3. **Approve** - the requested value is applied automatically. Extension-scoped requests write the matching per-extension limit column; developer-scoped requests write a developer-level override.
4. **Reject** - opens a dialog for review notes. The notes are optional at the API level but the reject dialog asks for them.

Every status change is written to a timeline of events and broadcast to the developer over a WebSocket channel, so the developer sees the decision without reloading.

### Request statuses

| Status | Meaning |
|--------|---------|
| `open` | Submitted, waiting for admin review |
| `in_review` | An admin is reviewing the request |
| `approved` | Approved - the limit is applied automatically |
| `rejected` | Rejected - review notes explain the reason |

`open` is the submitted state. The review endpoint accepts only `in_review`, `approved`, or `rejected` - a request cannot be moved back to `open`.

## The rest of the Developers area

The sidebar's **Hub → Developers** sub-group carries four entries. Limit work happens on the developer detail page reached from the first one.

| Page | Route | Page gate |
|------|-------|-----------|
| All Developers | `/developers` | `developer-verification:read` |
| Developer Teams | `/developers/teams` | `developer-limits:read` |
| Developer Verifications | `/developers/verifications` | `developer-verification:read` |
| Developer Applications | `/developers/applications` | `developer-verification:read` |

Two more routes exist without a sidebar entry - navigate to them directly:

| Page | Route | Page gate |
|------|-------|-----------|
| Limit Requests (global) | `/developers/limit-requests` | `developer-limits:read` |
| Developer Team detail | `/developers/teams/{id}` | `developer-limits:read` |

The developer detail page at `/developers/{id}` also carries a revenue-split control (50–100% developer share) and a delete action, next to the Limit Overrides and Limit Requests sections. The delete action (on this page and in the developer list) is refused while the profile still has a revenue balance or a payout in progress (`409 DEVELOPER_FUNDS_OUTSTANDING`); the confirmation dialog then names that reason instead of closing.

When the balance **cannot** be paid out — no payout method, or the identity is not verified — and the developer asked for the deletion, an operator with `developer-funds:release-deletion` (and `developer-verification:edit`) releases it as a liability and deletes in one step (`adminReleaseFundsAndDeleteDeveloper` / `POST /v1/admin/developers/{id}/release-funds-delete`). The operator enters the support request reference and a reason; neither may contain names, e-mail addresses or contact data. The server decides the case and refuses a payable balance (`409 DEVELOPER_FUNDS_PAYABLE`, use the closing payout) and an in-flight payout (`409 DEVELOPER_FUNDS_OUTSTANDING`). The person receives a claim code by e-mail; if that mail cannot be sent, the response shows the code once so the operator can pass it on through the request channel. Lumio keeps only the amount, the case, the operator, the reference, the reason and a hash of the code (`developer_released_balances`), until the end of the third year after the release year. When the person comes back with the code, an operator with `developer-funds:settle` records the claim with **Claim code presented** on the developer list and credits the amount with **Settle a released balance** on the person's new, verified profile; see [Settling a released balance](./users.md#settling-a-released-balance). In the admin app, the delete confirmation dialog (developer list and detail page) offers **Release balance as a liability and delete** after the `DEVELOPER_FUNDS_OUTSTANDING` refusal, to operators who hold both permissions; the steps are in [Releasing an unpayable developer balance](./users.md#releasing-an-unpayable-developer-balance).

Per-extension limits are edited on the **Hub → Extensions** pages (`/extensions` and `/extensions/reviews`), both gated on `extension-review:read`, with the limit cells themselves gated on `developer-limits:edit`.

## API endpoints

| Method | Path | Permission | Description |
|--------|------|-----------|-------------|
| `GET` | `/v1/admin/developers/{id}/limits` | `developer-limits:read` | List developer limit overrides |
| `PUT` | `/v1/admin/developers/{id}/limits` | `developer-limits:edit` | Set/remove a developer limit override |
| `PATCH` | `/v1/admin/extensions/{id}/limits` | `developer-limits:edit` | Set/clear per-extension limit overrides |
| `GET` | `/v1/admin/limit-requests` | `developer-limits:read` | List all limit requests |
| `GET` | `/v1/admin/developers/{id}/limit-requests` | `developer-limits:read` | List limit requests for a developer |
| `PUT` | `/v1/admin/limit-requests/{id}` | `developer-limits:edit` | Review (approve/reject) a limit request |
| `GET` | `/v1/admin/limit-requests/{id}/events` | `developer-limits:read` | Get timeline events for a limit request |

GraphQL: `adminDeveloperLimits`, `adminSetDeveloperLimit`, `adminSetExtensionLimits`, `adminAllLimitRequests`, `adminDeveloperLimitRequests`, `adminLimitRequestEvents`, `adminReviewLimitRequest` - see [GraphQL reference](../api-reference/graphql.md#admin---developer-limits).

The admin app calls these through its own proxy routes: `/api/developers/{id}/limits`, `/api/extensions/{id}/limits`, `/api/limit-requests`, `/api/limit-requests/{requestId}`, and `/api/limit-requests/{requestId}/events`.

---

## Admin / Extension Purchases: payment without delivery

Source: https://docs.lumio.vision/admin/extension-purchases

# Extension Purchases: payment without delivery

A buyer who pays for an extension normally has it installed in the same Stripe webhook pass. When that does not happen, Lumio refunds the payment automatically if the extension can no longer be delivered (see [Webhooks › Automatic refund](../features/webhooks.md)). Two cases are left over, and nothing retries them on its own:

- the install failed because of a temporary error, which is never refunded automatically;
- the automatic refund failed, for example because Stripe refused it.

The list **Admin → Commerce → Undelivered payments** (`/undelivered-purchases`) shows these payments so support can resolve them.

## What is on the list

A purchase is listed when all of these are true:

- its status is still `completed` (not refunded or disputed);
- the extension was never installed for the buying account after the payment;
- the payment is older than one hour (younger payments may still be in progress).

Each row shows the payment time, the extension and the buying account (both shown as deleted once they no longer exist), the amount, the Stripe Checkout Session and PaymentIntent ids, and the reason:

| Reason | Meaning |
|--------|---------|
| `detached` | The extension or its version was deleted or unpublished while the checkout was open. |
| `not_installable` | The account lost access to the extension between checkout and payment. |
| `install_failed` | A temporary error stopped the install. This case is never refunded automatically. |
| `refund_failed` | The automatic refund did not go through. The cause is in the API log. |
| *(empty)* | Unknown, for purchases recorded before the reason was stored. |

Newest payments come first, and you can load more rows page by page.

Uninstalling an extension later, deleting it, or deleting the buying account never puts a purchase on the list: delivery is recorded when the install happens, not checked again afterwards.

## Resolving a row

There is no separate "resolve" button. A row leaves the list on its own when one of these happens:

- **Refund in Stripe.** Refund the PaymentIntent in the Stripe Dashboard. Stripe sends `charge.refunded`, Lumio marks the purchase refunded and debits the developer's balance.
- **Install the extension.** If the extension can still be delivered, install it for the buying account (or ask the buyer to install it from the store). Any successful install of that extension for that account marks the purchase delivered.

## Access

The list needs the admin-scope permission `extension-purchases:read`, which the `system_admin` role holds. It is read-only.

API: GraphQL `adminUndeliveredExtensionPurchases` and REST `GET /v1/admin/extension-purchases/undelivered` (see the [GraphQL](../api-reference/graphql.md) and [REST](../api-reference/rest-api.md) references).

---

## Admin / Discord Guilds

Source: https://docs.lumio.vision/admin/discord-guilds

# Discord Guilds

The Discord Guilds view is the admin registry of every Discord server (guild) that has the Lumio Discord bot installed and is linked to a Lumio account. It exists so operators can audit the full set of guild-to-account mappings and forcibly unlink a guild when support cases require it.

## Where to find it

**Admin sidebar → Discord Guilds** (`/discord-guilds`).

## Quick start

1. Open **Admin → Discord Guilds**.
2. Scan the table for the guild in question.
3. To detach a guild from its account, click the red trash button on the row.
4. Confirm the prompt. The mapping row is removed and the bot's association with the guild is dropped.

## Detailed walkthrough

### Guilds table

Columns:

- **Guild** - the guild's Discord icon (or an initial avatar) plus the guild name as reported by Discord. A **Bot removed** badge appears next to the name when `bot_removed_at` is set; the server settings remain while the bot is absent.
- **Guild ID** - Discord snowflake ID, in a monospace badge.
- **Account** - linked Lumio account name plus the first 8 characters of its account ID. It is plain text, not a link.
- **Connected At** - the date the link was established.
- **Actions** - a red trash button, gated on `discord-guilds:delete`.

A count header reads "{N} guild connection(s)".

The table is not sortable, searchable, or paginated - every mapping is rendered in one list.

### Deleting a connection

Clicking the trash button raises a native browser confirm ("Are you sure you want to delete this guild connection?"). Confirming removes the mapping row via the admin mutation. The Discord bot remains a member of the guild itself - you have to remove the bot from the Discord server separately if you want it out of the guild.

### Bootstrapping guild mappings

Guild connections are created under **Connections → Discord** in the user dashboard. The verified OAuth invite uses `authorizeBot(platform: "discord")` or `GET /v1/bot-connections/discord/authorize`, returns through `/api/connections/oauth/discord/callback`, and stores the server ID confirmed by Discord. There is no "create guild connection" button in the admin UI - it is list-and-delete only.

## Common scenarios

- **Lost admin of a Discord server** - the Lumio-owning user left and can no longer manage the bot. Delete the guild connection; the remaining server admins can re-invite the bot under a fresh account.
- **Bot removed from Discord** - the mapping is marked, with settings preserved. The original account can reconnect it. A verified invite by another account can take over a marked server; the old account's settings are cleared.
- **Account dissolution** - when closing an account, remove any remaining guild connections to stop the bot from responding in those servers.
- **Duplicate mapping** - if the same guild snowflake appears twice (shouldn't happen, but theoretically), keep the newer row and delete the older.
- **Audit** - read the Connected At column to spot recent onboardings; the column is not sortable, so scan it by hand.

## Permissions

| Action | Permission |
|--------|-----------|
| View guild connections | `discord-guilds:read` |
| Delete a guild connection | `discord-guilds:delete` |

Dashboard entry requires `admin:access`. System admins hold both implicitly.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List guild connections | `adminDiscordGuilds` | `GET /v1/admin/discord-guilds` |
| Delete guild connection | `adminDeleteDiscordGuild` | `DELETE /v1/admin/discord-guilds/{guild_id}` |

## Tips & gotchas

- The delete action only clears Lumio's DB row. To remove the bot from the Discord server itself, a Discord server admin has to kick the bot (or the bot owner can do it from the Developer Portal).
- Guild connections are keyed by Discord snowflake (guild ID), not by account. An active mapping cannot be taken over by another account; a marked, bot-removed mapping can be taken over through a verified invite.
- There is no rename / re-account UI. To change ownership, delete and re-invite.
- The Discord bot token is not set in the admin panel. The Discord bot reads it from `DISCORD_BOT__BOT__TOKEN`; the server invite app comes from `[auth].discord_bot_client_id` / `discord_bot_client_secret` in the API configuration (see [Providers](./providers.md)).

## Related

- [Providers](./providers.md) - provider kill-switches and where the Discord bot is configured
- [Bot Control](./bot-control.md) - pause / resume the Discord bot per account
- [Bot Commands](./bot-commands.md) - Discord slash commands and prefix commands

---

## Admin / Feature Flags

Source: https://docs.lumio.vision/admin/feature-flags

# Feature Flags

Manage feature flags to control feature availability across the platform.

## Overview

Feature flags let administrators globally enable or disable features without redeploying. They are used as kill-switches for platforms, widgets, integrations, features, bot modules, automation actions, copyright providers, event types, and system-level controls.

## Managing Flags

Access feature flag management via **Admin > Feature Flags** (`/feature-flags`). The page renders:

- A **search box** filtering on label and key.
- An "{enabled} of {total} enabled" summary.
- One **tab per category**, each with an `enabled/total` badge. Only categories that actually contain flags get a tab.
- Inside a tab, one row per flag showing its label, its key in monospace, and a switch.

Toggling a switch immediately persists the change via `PATCH /v1/admin/feature-flags/{id}` (GraphQL `adminUpdateFeatureFlag`).

The switch is rendered behind a `feature-flags:edit` gate - admins holding only `feature-flags:read` see a plain **On** / **Off** label instead of a control. The API itself enforces `features:edit` on the write and `features:read` on the read, so an admin needs **both** `feature-flags:edit` (to see the switch) and `features:edit` (for the call to succeed).

## Categories

The admin UI orders category tabs like this:

1. `platform`
2. `feature`
3. `widget`
4. `integration`
5. `bot_module`
6. `automation`
7. `copyright_provider`
8. `event`
9. `system`

Categories are derived from the flags actually returned, so a category with no flags gets no tab. `automation`, `copyright_provider`, and `event` are reserved category names in that ordering - no flag is seeded into them today.

## Flag Reference

### `system` category

System flags are admin-scope, user-scope flags that apply to the platform as a whole rather than to individual accounts.

| Key | Label | Description |
|-----|-------|-------------|
| `system:account_creation` | Account Creation | Controls whether users may create new streaming accounts. When disabled globally, **all** users are blocked from creating accounts. Per-user overrides (see [Users](./users.md)) can grant or deny individual users regardless of the global setting. |
| `system:copyright_public_directory` | Public Copyright Directory | Kill-switch for the unauthenticated `/music` surface on the marketing site (landing page, song browser, playlists, detail pages, reports). When off, the `/music` link disappears from header + footer and every page under `/music/*` returns 404. The account-level Copyright Manager flag (`feature:copyright_detection`) is unaffected. |
| `system:copyright_public_quick_check` | Public Copyright Quick Check | Narrower kill-switch for just the inline paste-a-URL quick-check widget on `/music`. The rest of the directory stays live when this is off. Typically used for rollout or to shed API load. |
| `system:ideas_hub` | Ideas Hub | Master switch for the Ideas Hub, including the admin moderation surfaces. |
| `system:ideas_hub_public` | Ideas Hub (Public) | Controls whether the Ideas Hub is reachable without authentication. |
| `feature:extension_development` | Extension Development | Seeded in the `system` category despite the `feature:` key prefix. Gates the extension developer surfaces. |

### `feature` category

Feature flags gate individual dashboard pages and major feature areas.

Turning a `feature:*` flag off - globally, per plan, or per account - removes the
sidebar entry **and closes the route**. Every page under the feature's URL prefix
(a deep link such as `/dashboard/widgets/{id}/designer`, not just
`/dashboard/widgets`) then renders the "feature unavailable" page naming the
layer that disabled it, and the API rejects the matching requests.

| Key | Label | Description |
|-----|-------|-------------|
| `feature:bots` | Bot Control | Chat bot sections of the Connections group (settings window) |
| `feature:bot_modules` | Bot Modules | Bot Modules configuration page |
| `feature:bot_commands` | Bot Commands | Bot Commands management page |
| `feature:music` | Music | Music feature (player page + popout, Spotify polling worker, track events, REST/GraphQL controls). Gates the entire music stack. The overlay widget and the `{song}` bot variable are gated separately by `widget:spotify_now_playing`. |
| `feature:connections` | Connections | Connections page umbrella - disabling hides the entire Connections section |
| `feature:multichat` | Multichat | Cross-platform combined chat |
| `feature:automation` | Automation Engine | Automation builder and execution |
| `feature:copyright_detection` | Copyright Manager | Account-level song lists, status lookups, reports, and moderation; no background copyright check runs |
| `feature:streamelements` | StreamElements | StreamElements tip ingestion |
| `feature:obs_remote` | OBS Remote | OBS WebSocket remote control feature - gates the OBS integration dashboard page and all OBS config endpoints |
| `feature:advanced_overlays` | Advanced Overlays | Advanced overlay builder features (e.g. multi-plan-only widget library, custom CSS) |
| `feature:overlay_folders` | Overlay Folders | Folder organisation in the overlay list |
| `feature:overlay_access` | Overlay Access Control | Per-overlay access restrictions |
| `feature:overlay_sharing` | Overlay Shared Links | Shared overlay links |
| `feature:custom_bot` | Custom Bot Account | Allows the account to register a custom bot identity per platform instead of using the shared Lumio bot |
| `feature:multi_account` | Multi-Account | Owning more than one streaming account |
| `feature:extensions` | Extensions | The extension platform |
| `feature:extension_paid` | Paid Extensions | Paid extension purchases |
| `feature:widgets` | Widget Gallery | The widget gallery |
| `feature:sounds` | Sound Uploads | Sound uploads for extensions |

Whether a flag is on for a given plan is a separate, per-plan decision made in the [Plans](./plans.md) Feature Grid - the flag here is the global kill-switch only.

### `widget` category

Widget flags gate overlay widgets that render inside a broadcast overlay.

| Key | Label | Description |
|-----|-------|-------------|
| `widget:obs_browser_source` | OBS Browser Source | OBS Browser Source widget - overlay element that renders in OBS via browser source |
| `widget:spotify_now_playing` | Spotify Now Playing | Gates the Spotify Now Playing overlay widget and the `{song}` chat-bot variable (both surfaces that embed "now playing" data in a broadcast). Does **not** gate the music player, popout, worker, or API controls - those live behind `feature:music`. |
| `widget:chat_box` | Chat Box | Chat Box overlay widget |
| `widget:event_list` | Event List | Event List overlay widget |
| `widget:sub_goal` | Sub Goal | Sub Goal overlay widget |
| `widget:viewer_count` | Viewer Count | Viewer Count overlay widget |
| `widget:stream_uptime` | Stream Uptime | Stream Uptime overlay widget |

### `integration` category

Integration flags gate third-party tool integrations displayed in the Connections integrations modal.

| Key | Label | Description |
|-----|-------|-------------|
| `integration:shopify` | Shopify | Shopify e-commerce integration. Shopify is registered as an integration-only platform, so it does not appear on the [Providers](./providers.md) page. |
| `integration:obs_websocket` | OBS WebSocket | OBS WebSocket integration entry in the integrations modal - must be enabled for users to save or delete OBS connection settings |
| `integration:streamerbot` | Streamer.bot | Streamer.bot integration |

### `platform` category

One master flag per platform (`platform:twitch`, `platform:youtube`, `platform:kick`, `platform:discord`, `platform:spotify`) plus `:login` / `:channel` / `:bot` sub-flags for the connection types each platform supports. These are what the [Providers](./providers.md) page toggles.

### `bot_module` category

`bot_module:link_protection`, `bot_module:spam_protection`, `bot_module:word_filter`, `bot_module:timed_messages`, and `feature:bot_module_extensions` (seeded into the `bot_module` category despite the `feature:` key prefix).

## Flag Taxonomy Rules

Use the correct category when adding new flags:

| Category | Use for |
|----------|---------|
| `feature:*` | Dashboard pages and major feature areas |
| `widget:*` | Overlay widgets only (things that render inside a broadcast overlay) |
| `integration:*` | Third-party integrations in the integrations modal |
| `platform:{x}` / `platform:{x}:{type}` | Streaming platforms (Twitch, YouTube, Kick, Discord) - master switch + login/channel/bot sub-flags |
| `system:*` | Admin-scope system switches with user-scope resolution (e.g., `system:account_creation`) |
| `bot_module:*` | Individual bot moderation modules (link protection, spam protection, etc.) |

## Resolution Chain

Flag resolution differs by scope:

**Account-scope flags** (`feature:*`, `widget:*`, `integration:*`, `platform:*`, `bot_module:*`):

1. `GLOBAL_OFF` - the flag is disabled globally (admin kill-switch). Stops here.
2. `PLAN_LOCKED` - the flag requires a plan the account does not have.
3. `ACCOUNT_OVERRIDE` - an explicit per-account override set by an admin.
4. Enabled (no reason set).

**User-scope flags** (`system:account_creation`):

1. `USER_OVERRIDE` - the user has an explicit per-user override (`allow` or `deny`). Stops here.
2. `GLOBAL_OFF` - the global flag is disabled. Stops here.
3. Enabled (no reason set).

The `reason` field on `FeatureStatus` reflects the first layer that returned `enabled=false`. When a flag is enabled the `reason` field is `null`.

## Permissions

- `feature-flags:read` - the admin page and sidebar entry
- `feature-flags:edit` - renders the toggle switch in the admin UI
- `features:read` - the API read (`adminFeatureFlags`, `adminFeatureFlagsDetail`, `GET /v1/admin/feature-flags`)
- `features:edit` - the API write (`adminUpdateFeatureFlag`, `adminUpdateFeatureFlagDetail`, `PATCH /v1/admin/feature-flags/{id}`)

An admin who is meant to flip flags needs `feature-flags:read` + `feature-flags:edit` for the UI **and** `features:read` + `features:edit` for the API calls behind it.

The dashboard entry itself is gated on `admin:access`. System admins (`is_system: true`) implicitly receive all admin permissions.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List flags | `adminFeatureFlags` | `GET /v1/admin/feature-flags` |
| List flags with detail (description, `default_for_accounts`) | `adminFeatureFlagsDetail` | `GET /v1/admin/feature-flags/detail` |
| Toggle a flag | `adminUpdateFeatureFlag` | `PATCH /v1/admin/feature-flags/{id}` |
| Update flag detail | `adminUpdateFeatureFlagDetail` | `PUT /v1/admin/feature-flags/{id}/detail` |

---

## Admin / Ideas (Admin)

Source: https://docs.lumio.vision/admin/ideas

# Ideas (Admin)

The Ideas section of the admin panel provides moderation tools for the Ideas Hub. Admins can review all submitted ideas, change their status, edit content, moderate comments, and manage the categories and tags that users see when submitting ideas.

## Where to Find It

**Admin sidebar → Hub → Ideas**, which is a sub-group with three entries:

| Entry | Route | Sidebar gate |
|-------|-------|--------------|
| Ideas | `/hub/ideas` | `ideas:moderate_read` |
| Categories | `/hub/ideas/categories` | `ideas:moderate_edit` |
| Tags | `/hub/ideas/tags` | `ideas:moderate_edit` |

Idea detail pages live at `/hub/ideas/{id}`. Categories and tags are their own routes, not toolbar buttons on the Ideas list.

## Ideas List

The list view at `/hub/ideas` shows all ideas across every status.

### Columns

| Column | Description |
|--------|-------------|
| (checkbox) | Row selection, plus a select-all checkbox in the header |
| Title | Idea title, with a coloured category chip underneath when the idea has a category. Clicking it opens the detail page. |
| Author | User's display name, or `-` |
| Status | Inline status dropdown for admins with `ideas:moderate_edit`; a coloured badge otherwise |
| Votes | Up-vote and down-vote counts side by side |
| Comments | Total comment count |
| Created | Creation date |
| Actions | **View**, plus a delete (trash) button for admins with `ideas:moderate_edit` |

Category is not its own column - it appears as a chip under the title.

### Statuses

Ideas move through six statuses: `open`, `planned`, `in_progress`, `testing`, `completed`, `closed`. The server validates against exactly that allowlist.

### Filtering

The toolbar exposes:

- **Search** - a search box matching on title and description; typing resets to page 1.
- **Status** - a pill bar with `All` plus each of the six statuses.

There is no category filter. Filter state lives in React state and is **not** reflected in the URL.

### Bulk Actions

Selecting rows reveals a bulk-action bar. Both bulk operations sit behind a single `ideas:moderate_edit` gate in the UI:

| Action | UI gate | Server gate |
|--------|---------|-------------|
| Change status | `ideas:moderate_edit` | `ideas:moderate_status` |
| Delete selected | `ideas:moderate_edit` | `ideas:moderate_delete` |

Bulk status change is a target-status dropdown plus **Apply**; it fans out one status PATCH per selected idea. There is no accompanying-message field. Bulk delete raises a confirmation dialog naming the number of selected ideas.

## Idea Detail

The detail page at `/hub/ideas/{id}` provides a full view of a single idea and all associated data.

### Sections

**Idea Content**

Displays the title, description, category, tags, vote totals, and comment count. Admins with `ideas:moderate_edit` get an **Edit** button that swaps the card for a single form covering title, description, category, **status**, and tags at once - there is no separate status modal, and no field for a status-change message. A **Delete** button sits next to Edit, behind a confirmation dialog.

Status changes issue `PATCH /v1/ideas/{id}/status`, which requires `ideas:moderate_status` server-side even though the button is gated on `ideas:moderate_edit` in the UI.

**Timeline**

A chronological list of timeline entries for the idea - status transitions, title/description/category/tag changes. It shows the five most recent entries with a **Load more** control for the rest. Timeline entries are read-only and cannot be removed.

**Comments**

The comment list for the idea. Each comment shows the author, the body, and a timestamp, with a delete action gated on `ideas:moderate_edit` in the UI and `ideas:moderate_comment` (or `ideas:comment_delete` for one's own comment) server-side. Deletion goes through `DELETE /v1/ideas/comments/{id}`. A comment with replies stays as a tombstone (no author, no text) so the replies keep their place; the list shows it as **This post was deleted.** without a delete action, and it goes by itself once its last reply is gone. An idea with comments by others likewise stays as a tombstone: the list and the detail title it **Deleted idea**, the detail shows **This post was deleted.** instead of the description and hides the vote counts, and edit, delete and the status change are not offered (the API refuses them with `Idea was deleted`). See [Ideas Hub → Deletion and tombstones](../features/ideas-hub.md#deletion-and-tombstones).

Vote counts are derived from the `idea_votes` table; there is no manual override.

## Category Management

A dedicated page at `/hub/ideas/categories`, reached from the sidebar (**Hub → Ideas → Categories**). The sidebar entry and the page are gated on `ideas:moderate_edit`; the API enforces `ideas:edit` for create/update and `ideas:delete` for delete.

### Category List

A table with **Color**, **Label**, **Name (slug)**, **Sort Order**, and **Actions**. Rows are edited in place.

### Creating a Category

Click **Add Category** to open an inline row form:

| Field | Description |
|-------|-------------|
| Label | Display label shown to users (placeholder: "e.g. Feature Request") |
| Name | Machine-readable slug (placeholder: "e.g. feature_request") |
| Color | Colour used for the category chip in the UI |
| Sort Order | Integer; lower sorts first |

There is no description field.

### Editing a Category

Click the edit action on a row; the label, name, colour, and sort order become editable in place.

### Deleting a Category

Deleting raises a confirmation dialog carrying the warning "Categories with existing ideas cannot be deleted. Reassign the ideas first." The database enforces this with `ON DELETE RESTRICT` on the `category_id` FK, and a failed delete surfaces the error "Failed to delete. The category may still have ideas assigned."

## Tag Management

A dedicated page at `/hub/ideas/tags` (**Hub → Ideas → Tags**), gated on `ideas:moderate_edit` in the sidebar and page. The API enforces `ideas:create` for creating a tag and `ideas:delete` for removing one.

### Tag List

A search box, a "Tag name…" input with an **Add Tag** button, and a paginated list of tags. Each row shows the tag name and a delete (trash) button. Usage counts are not shown.

### Creating a Tag

Type a name into the input next to the search box and click **Add Tag**. Tags are also created by users inline when submitting an idea.

### Deleting a Tag

Click the trash button on any tag row. A confirmation dialog ("Are you sure you want to delete the tag …?") is shown first. Deleting removes the tag and its `idea_tag_assignments` join rows; the ideas themselves are not affected.

There is no rename flow - delete and recreate.

## Permissions

All Ideas admin actions require `admin:access` (the dashboard-entry gate). In addition:

| Action | UI gate | Server gate |
|--------|---------|-------------|
| Open the ideas list and detail pages | `ideas:moderate_read` | - (the list and detail queries are open to any authenticated user) |
| Change idea status | `ideas:moderate_edit` | `ideas:moderate_status` |
| Edit any idea's content | `ideas:moderate_edit` | `ideas:moderate_edit` (or `ideas:edit` for one's own idea) |
| Delete any idea | `ideas:moderate_edit` | `ideas:moderate_delete` (or `ideas:delete` for one's own idea) |
| Delete any comment | `ideas:moderate_edit` | `ideas:moderate_comment` (or `ideas:comment_delete` for one's own comment) |
| Open the categories / tags pages | `ideas:moderate_edit` | - |
| Create / update a category, create a tag | `ideas:moderate_edit` | `ideas:edit` (categories), `ideas:create` (tags) |
| Delete a category or tag | `ideas:moderate_edit` | `ideas:delete` |

`ideas:moderate_read` is a UI-only gate: it controls the sidebar entry and the admin pages, not the underlying read queries.

Category and tag mutations are guarded by the **admin-scope** `ideas:edit` / `ideas:create` / `ideas:delete` permissions, not by `ideas:moderate_*` - grant both to a moderator who should manage taxonomy.

System admins (`is_system = true`) implicitly have all permissions.

## API

| UI Action | GraphQL | REST |
|-----------|---------|------|
| List ideas | `ideas(filter, sort, limit, offset)` | `GET /v1/ideas` |
| Get idea detail | `idea(id: UUID!)` | `GET /v1/ideas/{id}` |
| Edit idea content | `updateIdea(id, input)` | `PATCH /v1/ideas/{id}` |
| Change status | `updateIdeaStatus(id, status)` | `PATCH /v1/ideas/{id}/status` |
| Delete idea | `deleteIdea(id: UUID!)` | `DELETE /v1/ideas/{id}` |
| List comments | `ideaComments(ideaId)` | `GET /v1/ideas/{id}/comments` |
| Delete comment | `deleteIdeaComment(id: UUID!)` | `DELETE /v1/ideas/comments/{id}` |
| Timeline | `ideaTimeline(ideaId)` | - |
| List categories | `ideaCategories` | `GET /v1/ideas/categories` |
| Create category | `createIdeaCategory(input: CreateIdeaCategoryInput!)` | `POST /v1/ideas/categories` |
| Update category | `updateIdeaCategory(id: UUID!, input: UpdateIdeaCategoryInput!)` | `PATCH /v1/ideas/categories/{id}` |
| Delete category | `deleteIdeaCategory(id: UUID!)` | `DELETE /v1/ideas/categories/{id}` |
| List tags | `ideaTags` | `GET /v1/ideas/tags` |
| Create tag | `createIdeaTag(name)` | `POST /v1/ideas/tags` |
| Delete tag | `deleteIdeaTag(id: UUID!)` | `DELETE /v1/ideas/tags/{id}` |

There is no `/v1/ideas/admin/*` route prefix - admin and end-user operations share the same paths and are separated by permission checks. The admin app reaches them through its own `/api/ideas/*` proxy routes.

There is no pin feature: no pin control in the admin UI, no `pinIdea` mutation, and no pin endpoint.

## Related

- [Feature Flags](./feature-flags.md) - the `system:ideas_hub` and `system:ideas_hub_public` kill-switches, which every ideas endpoint checks before doing anything
- [Ideas Hub feature doc](../features/ideas-hub.md) - architecture, data model, WebSocket channels
- [Ideas Hub user guide](../user-guide/ideas-hub.md) - user-facing functionality

---

## Admin / OAuth Clients

Source: https://docs.lumio.vision/admin/oauth-clients

# OAuth Clients

The OAuth Clients view is where operators register third-party applications that can obtain Lumio access tokens on behalf of users via standard OAuth 2.0 flows - for example, a native desktop overlay tool using PKCE, or a server-to-server integration using client-credentials. It is **not** the surface for configuring Lumio's own OAuth to Twitch / YouTube / etc. (that is [System Connections](./system-connections.md)).

## Where to find it

**Admin sidebar → OAuth Clients** (`/oauth-clients`).

## Quick start

1. Open **Admin → OAuth Clients**.
2. Click **Create Client**.
3. Fill in the Name, pick the Client Type, paste one redirect URI per line, and select scopes and grant types.
4. A one-time panel reveals the Client ID and **Client Secret** - copy and store the secret immediately. It is never shown again.
5. The new client appears in the list with its type, scopes, and an **Enabled** badge.

## Detailed walkthrough

### Clients list

Clients render as cards, not table rows, above a "{N} client(s)" counter. Each card surfaces:

- **Name** - display name.
- **Enabled** / **Disabled** badge and a **Client Type** badge (`public` - mobile / desktop using PKCE, no secret - or `confidential` - server-side, uses secret).
- **Client ID** - monospace.
- **Scopes** - the granted scopes, as chips.

Redirect URIs and grant types are stored on the client and returned by the API, but the card does not render them.

Card actions:

- **Enable** / **Disable** - flips the client's active flag via PATCH. Gated on `oauth-clients:edit`. Disabled clients cannot complete OAuth flows but existing tokens keep working until expiry.
- **Delete** - hard-deletes the client registration, with no confirmation prompt. Gated on `oauth-clients:delete`.

### Create form

Clicking **Create Client** (gated on `oauth-clients:create`) opens an inline card form, not a dialog:

- **Name** - free text (placeholder: "My Application"). Required.
- **Client Type** - dropdown: `Confidential` (default) or `Public`.
- **Redirect URIs** - newline-separated textarea (placeholder shows `https://example.com/callback` and `https://localhost:3000/callback`).
- **Scopes** - chip picker offering `read`, `write`, `overlays:read`, `overlays:create`, `overlays:edit`, `overlays:delete`, `events:read`, `events:create`, `chat:read`, `chat:write`, and `admin:*`.
- **Grant Types** - chip picker offering `authorization_code` (preselected), `client_credentials`, and `refresh_token`.

### Secret reveal

After creation the UI shows a warning-styled panel:

- Title: "Client Created - Save Your Credentials".
- Body: "The client secret will only be shown once. Copy it now and store it securely."
- The Client ID and Client Secret, plus **Copy Secret** and **Dismiss** buttons.

The client card never shows the secret again. Confidential clients that lose their secret need a delete + recreate.

## Common scenarios

- **Native desktop overlay app** - Create a client with Client Type `Public` and a PKCE-compatible redirect (e.g. `http://127.0.0.1:PORT/callback` for local loopback, or a custom URL scheme).
- **Internal back-office integration** - Create a confidential client with `client_credentials` grant type and a dedicated scope set.
- **Temporarily suspend a buggy third-party app** - Disable the client; their refresh flows will fail, existing access tokens last until TTL.
- **Rotate a leaked secret** - Delete + recreate. There is no rotate-in-place flow today.

## Permissions

| Action | Permission |
|--------|-----------|
| View OAuth clients | `oauth-clients:read` |
| Create a client | `oauth-clients:create` |
| Edit (enable / disable, update fields) | `oauth-clients:edit` |
| Delete a client | `oauth-clients:delete` |

Dashboard entry requires `admin:access`. System admins implicitly hold every OAuth clients permission.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List clients | `adminOauthClients` | `GET /v1/admin/oauth-clients` |
| Get a client | `adminOauthClient` | `GET /v1/admin/oauth-clients/{id}` |
| Create client | `adminCreateOauthClient` | `POST /v1/admin/oauth-clients` |
| Update client (fields / enabled) | `adminUpdateOauthClient` | `PATCH /v1/admin/oauth-clients/{id}` |
| Delete client | `adminDeleteOauthClient` | `DELETE /v1/admin/oauth-clients/{id}` |

## Tips & gotchas

- **Secrets are shown once.** Copy from the reveal panel - there is no way to recover a lost secret, only delete + recreate.
- The Enable / Disable action is reversible. Delete is not, and it asks for no confirmation.
- Redirect URIs are matched exactly. `https://example.com/callback` and `https://example.com/callback/` are different registrations.
- Public clients should never have the `client_credentials` grant type. The form does not stop you from selecting it - apply the rule yourself.
- Do not confuse this with [System Connections](./system-connections.md): that page holds Lumio's OAuth credentials against Twitch / YouTube / etc.; this page holds credentials that third-party apps use against Lumio.

## Related

- [System Connections](./system-connections.md) - Lumio's outbound OAuth credentials
- [System Keys](./system-keys.md) - service-to-service API keys (no OAuth)
- [Audit Log](./audit-log.md) - OAuth client create / revoke events

---

## Admin / Plans

Source: https://docs.lumio.vision/admin/plans

# Plans

The Plans view is where operators define the subscription tiers Lumio offers - their pricing, the numeric limits they impose, and the feature grid that maps plan tier to feature availability. Every account is tied to exactly one plan; the plan's defaults cascade through the system unless an account has an override (see [Accounts](./accounts.md)).

## Where to find it

**Admin sidebar → Plans** (`/plans`). Detail pages live at `/plans/{id}`.

## Quick start

1. Open **Admin → Plans** to see the list.
2. Click a plan (e.g. `pro`) to open its detail page.
3. Review pricing, numeric limits, and the **Feature Grid** at the bottom.
4. Pick a category tab in the Feature Grid and flip the switch on any feature to allow or disallow it for this plan.
5. Each switch saves on click - there is no separate Save button. The change propagates to every account on the plan that does not have a per-account override.

## Detailed walkthrough

### Plans list (`/plans`)

Columns:

- **Name** - display name (e.g. "Pro").
- **Slug** - machine identifier (`free`, `pro`, …).
- **Monthly** / **Yearly** - configured prices.
- **Overlays** - max overlays allowed.
- **Integrations** - max integrations allowed.
- **Features** - count of features allowed on the plan.
- **Visibility** - Public or Hidden.
- **Actions** - View / Edit / Delete, each gated on the matching `plans:*` permission.

A **New Plan** button sits above the table, gated on `plans:create`. Sort order is a plan field but is not a list column.

### Plan detail (`/plans/[id]`)

Multiple sections:

1. **Slug / Description** - plan identity.
2. **Price (Monthly) / Price (Yearly)** - Stripe-linked prices.
3. **Plan Limits** - Max Overlays, Max Widgets, Max Storage, Max Upload Size, Max Integrations, **Max Accounts**, and Chat Retention (`0` renders as "1095 days (3 years, maximum)", because the sweep treats it as the 1095-day maximum). The plan API additionally returns `maxCommands` (the bot-command cap, `0` = unlimited) - a canonical `plans` column seeded per tier (Free 25, Pro 200) and enforced by the bot-command module. It is exposed read-only on the plan API today and adjusted via seed/migration rather than the editor form.
4. **Feature Grid** - "Toggle which features are allowed for accounts on this plan. Global kill-switches and account defaults are managed in Feature Flags." It contains:
   - A **search box** filtering on label and key, and an "{allowed} of {total} allowed" summary.
   - One **tab per feature-flag category**, each with an `allowed/total` badge.
   - Inside a tab, one row per flag: the label, the key in monospace, and a switch.

Each row also carries a state badge:

- **Globally off** (amber) when the flag's global kill-switch is off. The switch is disabled - a plan override cannot re-enable a globally disabled feature.
- **Default** when the plan has no explicit `plan_features` row and the flag's `default_for_accounts` value is being inherited.

Flipping a switch writes immediately via `PUT /api/plans/{id}/features`. The plan detail page **reads** feature-flag detail (`GET /api/feature-flags/detail`) to render the "Globally off" state and the inherited default, but it cannot change them - global kill-switches and account defaults live on the [Feature Flags](./feature-flags.md) page.

Admins without `plans:edit` see a plain **Allowed** / **Not allowed** label instead of a switch.

### Visibility

Plans with `visibility = hidden` are not shown on the public pricing page but can still be assigned via the admin [Accounts](./accounts.md) view. Typical uses: grandfathered legacy plans, enterprise-only tiers negotiated per-customer.

## Common scenarios

- **Raise the upload limit for Pro** - open `pro`, edit the plan, change Max Upload Size, save. Every Pro account without a per-account override picks up the new cap.
- **Ship a beta feature to one tier only** - enable it in that plan's Feature Grid, leave it off on the others, and make sure the flag is not globally disabled on [Feature Flags](./feature-flags.md).
- **Sunset a plan** - set visibility to Hidden; existing accounts stay, pricing page no longer offers it.
- **Apply a global kill-switch** - toggle the flag off on [Feature Flags](./feature-flags.md); every plan's switch for that feature turns amber ("Globally off") and disables.

## Permissions

| Action | Permission |
|--------|-----------|
| View plan list / detail | `plans:read` |
| Create a plan | `plans:create` |
| Edit plan fields / feature assignments | `plans:edit` |
| Delete a plan | `plans:delete` |
| Read feature-flag detail for the grid | `features:read` |

Dashboard entry requires `admin:access`. System admins implicitly hold all of the above.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List plans | `adminPlans` | `GET /v1/plans` (public) |
| Create plan | `adminCreatePlan` | `POST /v1/admin/plans` |
| Update plan | `adminUpdatePlan` | `PATCH /v1/admin/plans/{id}` |
| Delete plan | `adminDeletePlan` | `DELETE /v1/admin/plans/{id}` |
| Update plan features | `adminSetPlanFeature` | `PUT /v1/admin/plans/{id}/features` |
| Feature-flag detail list (read-only here) | `adminFeatureFlagsDetail` | `GET /v1/admin/feature-flags/detail` |

There is no `GET /v1/admin/plans` REST route. The admin list is served by the `adminPlans` GraphQL query through the app's own `/api/plans` proxy route; `GET /v1/plans` is the public, unauthenticated pricing list.

## Plan CRUD

The admin UI supports the full create / edit / delete lifecycle for plans, in addition to editing the seeded tiers. Every operation is exposed via both GraphQL and REST; see [GraphQL](../api-reference/graphql.md#plan-management) and [REST](../api-reference/rest-api.md#admin-plan-management) for full schemas.

### Permissions

| Action | Permission |
|--------|-----------|
| List / view plans | `plans:read` |
| Create a plan | `plans:create` |
| Edit a plan | `plans:edit` |
| Delete a plan | `plans:delete` |

System admins implicitly hold all four. The admin UI hides every action whose permission the caller does not hold.

### Create flow

Use **Plans → New Plan** to open the create dialog.

- **Slug** is required and **immutable**. It must match the regex `^[a-z0-9]+(?:-[a-z0-9]+)*$` (lowercase letters, digits, single dashes between segments) and be **2 to 40 characters** long. Examples: `free`, `pro`, `enterprise-legacy`. Slugs must be globally unique - duplicates return `409 Conflict` (REST) or a `"Plan slug already in use"` GraphQL error.
- **Name**, **description**, **prices** (monthly / yearly / currency), **numeric limits** (Max Overlays, Max Widgets, Max Integrations, Max Accounts, Max Storage, Max Upload Size, Chat Retention, Max Sounds, Max Sound File Size, Max Sound Storage, **Max Setting Presets**), **Public** visibility, and **sort order** all mirror the editable fields on the detail page.
- **Stripe IDs** (`stripe_product_id`, `stripe_monthly_price_id`, `stripe_yearly_price_id`) are optional. Lumio does **not** auto-create Stripe products. Create the Stripe product and prices manually in your Stripe dashboard, then paste the IDs into these fields so that billing flows can reference them.
- On success, the new plan is created with an empty feature assignment set. Use the **Feature Grid** on the detail page to enable features for the new plan.

### Edit flow

Open the plan detail page at `/plans/{id}` and edit any field except the slug.

- The **slug is immutable** after creation. If you need a different slug, create a new plan and migrate accounts to it, then delete the old one.
- Saving the form calls `adminUpdatePlan` / `PATCH /v1/admin/plans/{id}`, which rewrites all editable fields and then invalidates the feature cache for every account currently on the plan. The new limits and prices take effect on the next request from those accounts - no restart required.
- Changes to Stripe IDs here only update the reference in Lumio. **Price changes in Lumio do NOT update Stripe.** If you change a price, update the Stripe product/price in your Stripe dashboard and paste the new price ID into the corresponding field.

### Delete flow

From the plan detail page (or the list row), use **Delete Plan**.

- Deleting a plan is blocked when any accounts still reference it. The API returns `409 Conflict` with the message `"Cannot delete plan: N account(s) still reference it. Migrate them to a different plan first."` Move those accounts to another plan (see [Accounts](./accounts.md)) and retry.
- When the plan has no accounts attached, deletion cascades through the `plan_features` foreign key and removes every per-plan feature assignment automatically. No other data is affected.
- Deletion is permanent. Slugs of deleted plans can be reused by new plans.

### Stripe integration

Lumio treats Stripe IDs as **manually managed references**. The admin UI does not call the Stripe API to create or mutate products or prices.

- Create products and prices in your Stripe dashboard first.
- Paste the Stripe `product` ID into `stripe_product_id` and the `price` IDs (monthly + yearly) into the matching fields on the plan.
- Price changes in Lumio (`price_monthly`, `price_yearly`) only update the **display** price shown on marketing pages. They do not reprice any Stripe subscription. To change what subscribers pay, update the price in Stripe, create a new Stripe price if needed, and paste the new price ID into the plan.
- Removing a Stripe ID from a plan (setting it to empty) disables checkout flows that depend on it until a new ID is pasted back.

## Tips & gotchas

- Effective feature state for an account is the AND of: **global flag on** × **allowed on the plan** × not-explicit-account-override-off. If any of those are off, the feature is off for the account. A flag with no `plan_features` row for the plan falls back to the flag's `default_for_accounts` value, and the public pricing matrix treats a missing row as **disabled**.
- Stripe prices are maintained in Stripe; this page only references them. Creating a brand-new paid plan tier requires an accompanying Stripe product + price.
- **Channel data retention** is in days and covers chat, events, chatter profiles and moderation data. The maximum is **1095** (3 years); the API refuses a larger or negative value on plans and per-account overrides, and the database enforces the same 0–1095 range. `0` is not "unlimited": the sweep treats it as the maximum of 1095 days (3 years) for all channel data, and the admin and customer-facing surfaces show it that way. Customer-facing surfaces show whole years when the value is a multiple of 365.
- **Max Setting Presets** is the per-user [setting-preset](../features/setting-presets.md) quota across all kinds combined; `0` = unlimited. Defaults are Free 5, Pro 20. A member of an account resolves the best quota across all accounts they can reach, so raising a plan lifts every member on it.
- Hidden plans still appear in [Subscriptions](./subscriptions.md) and [Accounts](./accounts.md).

## Related

- [Feature Flags](./feature-flags.md) - global kill-switches
- [Accounts](./accounts.md) - per-account plan and limit overrides
- [Subscriptions](./subscriptions.md) - which accounts are on which plan
- [Coupons](./coupons.md) - discounts against these plans

---

## Admin / Privacy Erasure

Source: https://docs.lumio.vision/admin/privacy-erasure

# Privacy Erasure

The Privacy Erasure page holds support's three erasure tools. Each one erases personal data on a documented request (GDPR Art. 17): a channel's instruction, or a person's own request. Every erasure is final and writes an audit event (System scope) with the request reference and the reason.

## Where to find it

**Admin sidebar → Moderation → Privacy Erasure** (`/privacy-erasure`). The menu item, the page and every tool on it need `admin:privacy-erase`.

## Quick start

1. Open **Admin → Privacy Erasure** and pick the tab that matches the request.
2. Choose the **Channel account** (tools 1 and 3): search by account or owner name, or paste the account ID. The account's connected channels show under the search result so you can check you have the right channel.
3. Fill in the person or the record, the **Request reference** (ticket or letter number, at most 200 characters) and the **Reason** (at most 500 characters); in tool 1 also **Who initiated the erasure?**
4. Click the submit button. A confirmation dialog names the channel, the person or record, the reference, the reason and (tool 1) **Initiated by**, and lists what is **Erased** and what **Stays**.
5. Confirm. The result shows the **Case number** (the first 8 characters of the case ID) and how many entries were erased per data type. **New erasure** clears the form.
6. If removed content appeared on an indexed Lumio Stats page, request a search-engine refresh after the Lumio removal. For Google, use **Remove Outdated Content** ("Veraltete Inhalte entfernen") for the affected URL. Record the request with the case. Search results may keep the old snippet until the search engine processes it; Lumio cannot remove third-party archives.

## The three tools

### Person in one channel

Erases one person's data in **one** channel only — on that channel's instruction, or on a person's request that concerns this channel.

- **Person:** either a **Platform account** (platform + platform user ID — the ID, not the display name) or a **Lumio user** (Lumio user ID; erases the person under every platform account that user signs in with).
- **Who initiated the erasure?** (required, no preselection): **The channel** when the channel instructed it, or **The person** when the person asked for it. The choice is stored on the channel's erasure list: an entry the channel initiated can later be withdrawn on the channel's instruction; an entry the person asked for can never be withdrawn on the channel's instruction. The confirmation dialog repeats the choice.
- **Erased:** chat messages in the channel, the person's profile in the channel, moderator notes, moderation-log entries, AutoMod log entries and their allow/deny log rows, the bot-list entry, messages of the person still held for AutoMod review, and the person's name in the channel's past stream reports (places and counts stay).
- **Afterwards:** the person is on the channel's erasure list, so the channel's future stream reports leave them out. The channel owner receives a confirmation e-mail with the case number.
- **Stays:** events (follows, subs, donations), data in other channels, and Lumio Stats — use **Person at Lumio only** for those.

### Person at Lumio only

Erases one person on Lumio's own surfaces. No channel's data is touched.

- **Person:** platform (Twitch, YouTube, Kick) + platform user ID; optionally the **Login** on Twitch and Kick, which also catches leaderboard entries saved under the login name. YouTube has no login name.
- **Erased:** the person on the public Lumio Stats leaderboard (an existing objection becomes an erasure, and future Lumio Stats leave them out) and, on YouTube only, the person in Lumio's member cache of every channel.
- **Stays:** all channel data — chat, notes, logs and stream reports belong to the channels.

### Single record

Erases one entry in one channel, for example a single chat message the channel asked to remove. The person's other data stays and no erasure list is written.

| Record type | What you enter | What is erased |
|-------------|----------------|----------------|
| Chat message | Record ID + **Sent at** (your local time to the second, matched within ±1 second) | The message, and its text in the moderation log (the log row stays) |
| Moderator note | Record ID | The note |
| Moderation log entry | Record ID | The log entry |
| AutoMod log entry | Record ID | The AutoMod entry, its allow/deny log rows and a message still held for review |
| Bot list entry | Record ID | The bot-list entry |
| Person in a stream report | Stream ID (session ID) + platform + platform user ID (+ optional login) | The person's name in that report's top chatters, links, commands and keywords; places and counts stay |

A stream report can only be cleaned once it is final; until then the dialog says **The stream report is not final yet**. When the person did not appear in the report, the result says so and nothing changed.

## Errors

Errors appear inside the confirmation dialog, so you can correct the form and try again:

- **This account does not exist** — the account ID is wrong.
- **No such entry in this channel** — the record ID does not belong to this channel, or it was already erased.
- **The stream report is not final yet** — retry once the stream has ended and its report is final.
- **The request was rejected: …** — a field failed the API's validation; the API's message is shown.
- **The erasure failed** — a retry is safe.

## Permissions

| Action | Permission |
|--------|-----------|
| See the menu item and the page, use all three tools | `admin:privacy-erase` |
| Search accounts by name in the account field | `accounts:read` (without it, paste the account ID) |

Dashboard entry requires `admin:access`. `admin:privacy-erase` is assigned only to `system_admin`.

## API

The page calls the Next.js proxy routes `/api/privacy-erasure/{channel,lumio,record}`, which forward to GraphQL.

| UI action | GraphQL | REST |
|-----------|---------|------|
| Person in one channel | `eraseChatSubjectData` | `POST /v1/admin/privacy/chat/erase` |
| Person at Lumio only | `eraseChatSubjectAtLumio` | `POST /v1/admin/privacy/lumio/erase` |
| Single record | `eraseChatRecord` | `POST /v1/admin/privacy/records/erase` |

## Tips & gotchas

- **IDs come from the request.** The admin panel cannot search people or records across accounts; take the platform user ID, record ID or stream ID from the channel's instruction.
- **Check the channel in the dialog.** Tools 1 and 3 act on exactly one account; the dialog names its channel before anything is erased.
- **Not on this page:** erasing a YouTube member (`DELETE /v1/admin/privacy/youtube/member/{id}`), withdrawing a channel erasure (`admin:privacy-erase-withdraw`) and objections are API-only.
- After a Lumio Stats objection or erasure that removes content from an indexed channel or directory page, request the same search-engine refresh and record it with the case. Stream and channel-history pages carry `noindex, follow`, but a search engine may still hold an older snippet until it refreshes.
- Every erasure is listed in the [Audit Log](./audit-log.md).

---

## Admin / Providers

Source: https://docs.lumio.vision/admin/providers

# Providers

The Providers view is the top-level kill-switch dashboard for the streaming platforms Lumio integrates with. Five providers are listed: **Twitch**, **YouTube**, **Kick**, **Discord**, and **Spotify**. Each exposes a **platform kill-switch** plus sub-flags for the connection types that platform actually supports: **Login**, **Channel**, **Bot**. It is also where operators configure and connect the **Global Bot** identity.

## Where to find it

**Admin sidebar → Providers** (`/providers`).

## Quick start

1. Open **Admin → Providers**.
2. Scan the cards - each provider has its own card with the current credentials status ("Configured" / "Not Configured"), connection counts, and the four toggles.
3. To take a whole platform offline, flip the **Platform** kill-switch to off.
4. To block *only* new logins while keeping existing channel + bot connections, leave Platform on and flip the **Login** sub-toggle off.
5. Discord has nothing to set here: the invite Application ID and Secret are API `[auth]` settings and the bot token is the Discord bot's `DISCORD_BOT__BOT__TOKEN`. For the other bot platforms, click **Connect Bot** to start the OAuth flow.

## Detailed walkthrough

### Per-provider card

Each provider card surfaces:

- **Status** - Enabled / Disabled at the platform level.
- **Credentials** - Configured / Not Configured. This badge reflects `system_credentials_configured`: whether the platform's **global (system) OAuth app** is present in the API `[auth]` config (the `{platform}_channel_client_id` / `{platform}_channel_client_secret` pair, resolved by `CredentialResolver::system_pair`). These keys are set in the API configuration (file or `LUMIO__AUTH__*` environment variables), not through the admin UI. When the badge is Not Configured the card shows a "Configure Credentials" link to [System Connections](./system-connections.md) (`/system`); note that System Connections manages a **separate** operator credential store (`integration_configs`, used for native emote fetches) and does **not** set the global system OAuth app that this badge tracks.
- **Statistics** - Channel Connections, Login Connections, Bot Connections counts, each shown only for the connection types the platform supports.
- **Platform** - master kill-switch.
- **Connection Types (sub-toggles)** - Login, Channel, Bot. Each can be flipped independently while Platform is on. Only the sub-toggles the platform supports are rendered.

Capabilities come from a static platform registry, so the card shape differs per provider:

| Provider | Login | Channel | Bot | Integration |
|----------|:-----:|:-------:|:---:|:-----------:|
| Twitch | ✅ | ✅ | ✅ | - |
| YouTube | ✅ | ✅ | ✅ | - |
| Kick | ✅ | ✅ | ✅ | - |
| Discord | ✅ | - | ✅ | ✅ |
| Spotify | - | ✅ | - | - |

Disabling warning text: "Disabling will block new connections and logins. Existing connections will continue working."

### Global Bot section

Rendered for platforms that support a Lumio-owned bot identity (Twitch, YouTube, Kick, Discord) **and** only while the platform kill-switch is on. For Twitch, YouTube and Kick it shows:

- **Connected as** `<username>` when a global bot connection exists, with a **Disconnect Bot** button (native confirm: "Are you sure you want to disconnect this global bot?").
- Otherwise "Not connected", with a **Connect Bot** button that launches the OAuth authorize flow. The button is disabled until the platform's global system OAuth app is Configured. The global bot is always **system-sourced**: `adminBotAuthorizeUrl` reads the config system pair via `CredentialResolver::system_pair` and pins `credential_source = "system"` on the row. The authorize flow returns through the web host's unified callback (`{web.public_url}/api/connections/oauth/{platform}/callback`) and the OAuth `state` handle's `return_to` sends the browser back into the admin Providers UI.

### Discord

Discord's Global Bot section has no button and no input. It states where the bot is configured:

- **Bot token** - the Discord bot reads it from its own configuration, `DISCORD_BOT__BOT__TOKEN` (`[bot].token` in the Discord bot's TOML). The API does not store it.
- **Server invite app** - the Application ID and secret come from `[auth].discord_bot_client_id` and `[auth].discord_bot_client_secret` in the API configuration.

`adminBotAuthorizeUrl(platform: "discord")` and `GET /v1/admin/bot-connections/discord/authorize` reject Discord with the same message on both protocols.

### Integrations row

Providers flagged as having an integration show an extra counter row. Discord is the only listed provider with that flag today, rendering "Discord servers: N".

## Common scenarios

- **Twitch EventSub outage** - flip Platform → off on Twitch. Existing connections keep working (they use cached tokens via the Token Refresh Worker), but no new logins or reconnects are accepted.
- **Rolling a breaking bot update** - disable the Bot sub-toggle only; channel API calls and OAuth logins keep flowing while bots stay disconnected.
- **Global bot reconnect after moving to config keys** - global bot OAuth credentials come from the API `[auth]` config keys, not from `integration_configs`. Existing `integration_configs` bot tokens are not migrated automatically, so each OAuth global bot must be reconnected once after the config keys are in place:
  1. Set the platform's global system OAuth app in the API `[auth]` config (`{platform}_channel_client_id` / `{platform}_channel_client_secret`, or the `LUMIO__AUTH__*` environment variables) and restart the API.
  2. Open **Admin → Providers**; the platform's Credentials badge flips to **Configured**.
  3. Click **Connect Bot** for an OAuth bot platform and complete the flow. Discord is not connected here: its bot token is bot configuration, and servers are connected through the verified invite flow under **Connections → Discord**.
  4. Confirm the Global Bot section shows **Connected as `<username>`**.
- **Initial Discord setup** - configure `[auth].discord_bot_client_id` and `[auth].discord_bot_client_secret` in the API, and set `DISCORD_BOT__BOT__TOKEN` (plus the bot's system key, `DISCORD_BOT__API__SYSTEM_KEY`) on the Discord bot. Restart both. The invite app pair is required to connect servers; it is not stored under System Connections.
- **YouTube quota exhausted** - flip YouTube's Channel sub-toggle off until the daily quota resets.

## Permissions

| Action | Permission |
|--------|-----------|
| View provider cards / stats | `providers:read` |
| Toggle kill-switches / sub-toggles (GraphQL, used by the admin UI) | `providers:edit` |
| Get authorize URL / exchange OAuth code | `bot-connections:create` |
| Disconnect global bot | `bot-connections:delete` |
| Configure credentials (on [System Connections](./system-connections.md)) | `system-connections:edit` |

Dashboard entry requires `admin:access`. System admins implicitly hold every permission above.

The REST `PATCH /v1/admin/providers/{platform}/toggle` and `.../{subtype}/toggle` routes are guarded by `features:edit`, not `providers:edit` - the `/enabled` routes and every GraphQL mutation use `providers:edit`. The admin UI goes through GraphQL, so `providers:edit` is what the dashboard needs.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List providers with stats | `adminProviders` | `GET /v1/admin/providers` |
| Toggle platform | `adminToggleProvider` | `PATCH /v1/admin/providers/{platform}/toggle` |
| Toggle sub-flag | `adminToggleProviderSubtype` | `PATCH /v1/admin/providers/{platform}/{subtype}/toggle` |
| Set platform enabled (explicit) | `adminSetProviderEnabled` | `PATCH /v1/admin/providers/{platform}/enabled` |
| Set subtype enabled (explicit) | `adminSetProviderSubtypeEnabled` | `PATCH /v1/admin/providers/{platform}/{subtype}/enabled` |
| Get global bot status | `adminGlobalBotConnections` | `GET /v1/admin/bot-connections` |
| Discord guild count for the integrations row | `adminDiscordGuilds` | `GET /v1/admin/discord-guilds` |
| Authorize URL for global bot | `adminBotAuthorizeUrl` | `GET /v1/admin/bot-connections/{platform}/authorize` |
| Exchange OAuth code | `adminExchangeBotConnection` | `POST /v1/admin/bot-connections/{platform}/exchange` |
| Disconnect global bot | `adminDeleteGlobalBotConnection` | `DELETE /v1/admin/bot-connections/{platform}` |

## Tips & gotchas

- Toggles are hierarchical. Platform off ⇒ Login/Channel/Bot off regardless of their individual state. Turning Platform back on restores the last sub-state.
- Existing tokens keep working while a toggle is off - the switch gates **new** flows only. For immediate hard-offline, rotate tokens via [System Connections](./system-connections.md).
- To rotate the Discord bot token, generate a new one in the Discord Developer Portal, set it as `DISCORD_BOT__BOT__TOKEN` and restart the Discord bot.
- Connection counts reflect the latest DB state at page load; they're not live. Refresh for current numbers.
- Credentials must be **Configured** before any sub-toggle can be meaningfully used. If Credentials is "Not Configured", the Connect Bot button is disabled.
- **Shopify does not appear in the Providers list.** Shopify is registered as an integration-only platform (no login, channel, or bot capability), and `adminProviders` filters those out. Its kill-switch lives in [Feature Flags](./feature-flags.md) under the `integration` category as `integration:shopify`.
- **StreamElements is not a provider.** It is not in the platform registry at all; its kill-switch is the `feature:streamelements` feature flag.

## Related

- [System Connections](./system-connections.md) - operator-managed `integration_configs` credential store (native emote fetches); not the global-bot OAuth app source
- [Bot Control](./bot-control.md) - per-account pause / resume
- [Discord Guilds](./discord-guilds.md) - Discord-specific guild mappings
- [Feature Flags](./feature-flags.md) - fine-grained feature kill-switches (one layer below provider kill-switches)

---

## Admin / Stats Crawler Control

Source: https://docs.lumio.vision/admin/stats-crawler

# Stats Crawler Control

Steer the public [stats crawler](../developer-guide/public-stats-crawler.md) -
which live channels it discovers, and the curated list of channels to crawl.
This is a **platform-operator** surface: it controls the crawler globally, not a
single account's data.

## Access

Reaching the Admin app requires `admin:access`. The crawler controls are then
gated on granular, **admin-scope** (platform-operator) permissions, seeded to the
`system_admin` admin role (ZAF-725). They are enforced against the caller's admin
role (`require_admin_permission` / `AdminPermissionGuard`), so an account-scope
role grant never satisfies them:

| Control | Permission |
|---------|------------|
| View the scope mode | `crawler:scope-read` |
| Change the scope mode | `crawler:scope-edit` |
| View the watchlist | `crawler:watchlist-read` |
| Add a watchlist channel | `crawler:watchlist-create` |
| Remove a watchlist channel | `crawler:watchlist-delete` |

Every change is written to the **operator audit log** (`crawler:scope_changed`,
`crawler:watchlist_added`, `crawler:watchlist_removed`).

## Scope modes

The scope bounds which live channels the crawler publishes crawl jobs for. It is
DB-backed and **live** - a change takes effect on the crawler's next discovery
sweep, with no redeploy.

| Mode | Channels crawled |
|------|------------------|
| **Lumio** | First-party roster only (connected Lumio channels). |
| **List** | The crawl watchlist only. |
| **Lumio + List** | The union of the two. **Default.** |
| **Global** | Every live channel (unfiltered). Kill-switch / ramp target. |

The default is **Lumio + List** - a bounded, curated set that lets `/stats`
launch on today's capacity. **Global** is an explicit, opt-in widening: switch to
it only once the crawler's capacity backbone (broker + cluster) is armed and the
[arming check](../developer-guide/public-stats-crawler.md#arming-check) passes. The
system never widens to Global on its own - an unreachable database falls back to
the configured bounded default, never Global.

## Watchlist

The watchlist is the **List** component of the scope: a curated set of channel
identities (`platform` + platform channel id) to crawl regardless of whether they
are connected Lumio accounts. Adding a channel is idempotent - re-adding the same
identity updates its labels rather than creating a duplicate. Removing a channel
takes effect on the next discovery sweep.

The watchlist governs **which** channels are candidates for crawling; it is
distinct from the per-channel **opt-out** registry (`public_channel_settings`),
which removes a channel from crawling even if it is in scope. See
[Opt-out enforcement](../developer-guide/public-stats-crawler.md#opt-out-enforcement-two-sided).

## Using the admin control

The controls live in the Admin app under **Stats → Stats Crawler**
(`/stats-crawler`). The nav entry appears only if you hold at least one of the
five `crawler:*` permissions; each control on the page is additionally gated on
its own permission, so a read-only operator sees the current values without the
edit affordances.

### Setting the scope mode

The **Crawl scope** card shows the four modes as selectable cards with the
current mode badged. Pick a mode and press **Apply scope** to persist it
(`crawler:scope-edit`). Selecting **Global** surfaces an inline warning and turns
the apply button destructive - it is the explicit, opt-in widening to an
unbounded sweep, so it never happens by a single stray click. Without
`crawler:scope-edit` the cards are read-only and the apply button is hidden.

### Managing the watchlist

The **Crawl watchlist** card lists the curated entries and, for operators with
`crawler:watchlist-create`, an add form:

1. Choose the **Platform** and enter the **Platform channel ID** - the channel
   identity. The optional **Login**, **Display name**, and **Note** are
   denormalized labels shown in the list.
2. Press **Add channel**. The add is idempotent: re-adding the same
   `platform` + `platform_channel_id` updates the labels of the existing entry
   rather than creating a duplicate, and the row moves to the top of the list.
3. Remove an entry with the trash button (`crawler:watchlist-delete`).

Both scope changes and watchlist edits take effect on the crawler's next
discovery sweep and are written to the operator audit log.

---

## Admin / Subscriptions

Source: https://docs.lumio.vision/admin/subscriptions

# Subscriptions

The Subscriptions view is an operational overview of every Lumio account and its current plan - effectively a read-only "who is paying for what" list. It shares the same underlying admin accounts endpoint as the [Accounts](./accounts.md) page but is optimised for billing operators who only care about the plan mapping, not the per-account members or limits.

## Where to find it

**Admin sidebar → Subscriptions** (`/subscriptions`).

## Quick start

1. Open **Admin → Subscriptions**.
2. Search by account or owner display name.
3. Scan the plan column for `free` / `pro` badges.
4. Page through with Previous / Next at the bottom.
5. For actual plan changes, coupon application, or limit overrides, click through to the account - the Subscriptions page is read-only.

## Detailed walkthrough

### Table columns

- **Account** - account name, click-through to `/accounts/{id}` (detail page).
- **Owner** - display name of the owning user.
- **Plan** - coloured badge (`free`, `pro`).
- **Members** - member count on the account.
- **Created** - account creation date.

### Search

Debounced search on account name and owner name. Resets pagination to page 1 on each keystroke.

### Pagination

25 accounts per page, footer reads "Page X of Y (N accounts)".

## Common scenarios

- **"How many Pro accounts exist?"** - eyeball the plan column or filter by plan via search (free-text search does not filter by plan directly; use the Accounts page or the dashboard stats on [Billing](./billing.md)).
- **Look up the owner of a given account's subscription** - search by account name; Owner column has the name.
- **Churn investigation** - the table is not sortable; read the Created column while paging, or query the accounts endpoint directly.

## Permissions

| Action | Permission |
|--------|-----------|
| View subscription overview | `accounts:read` |

The page and its sidebar entry are both gated on `accounts:read`, because the page is a view over the admin accounts endpoint. Dashboard entry requires `admin:access`. System admins hold these implicitly.

`subscriptions:read` and `subscriptions:edit` exist in the admin permission registry but no endpoint or UI element enforces them today.

## API

The Subscriptions page is a thin view over the admin accounts endpoint; there is no dedicated `adminSubscriptions` query.

| UI action | GraphQL | REST |
|-----------|---------|------|
| List accounts + plan | `adminAccounts` | `GET /v1/admin/accounts` |

For the authoritative subscription data (status, renewal date, cancel-at-period-end), look inside the Stripe Dashboard against the account's `stripe_customer_id`. Lumio stores the current plan slug but not the full Stripe subscription object.

## Tips & gotchas

- This page does **not** show subscription status (active / past-due / cancelled). It shows the `plan` column on the accounts table, which is set locally by admin actions or Stripe webhooks.
- For refunds, mid-cycle proration, or subscription cancellation, use the Stripe Dashboard.
- To change a plan without Stripe (e.g. comp a paid customer), use [Accounts](./accounts.md) → Plan Management. That path writes the local plan slug but does not touch Stripe.
- Users can belong to many accounts. The Owner column is the owner of *this* account, not necessarily the paying party if billing was delegated (edge case).

## Related

- [Accounts](./accounts.md) - change plans, override limits, detach connections
- [Billing](./billing.md) - plan-count KPIs
- [Plans](./plans.md) - plan definitions and feature grid
- [Coupons](./coupons.md) - discount codes applied during checkout

---

## Admin / System Connections

Source: https://docs.lumio.vision/admin/system-connections

# System Connections

Manage system-level platform OAuth credentials (client ID / client secret pairs) used by Lumio's services.

## Overview

System connections are an operator-managed credential store keyed by platform, held in `integration_configs` under the sentinel system account. They are distinct from per-user channel connections and from the global system OAuth app used for connect/reconnect.

The single reader is `get_system_credential`, and its consumers are server-side native Twitch emote fetches via `get_twitch_emote_auth` and playlist sync. System connections are **not** the source for the global-bot OAuth client: global bot connect/reconnect reads the config `[auth]` system pair via `CredentialResolver::system_pair` (see [Providers](./providers.md)), and channel/bot token refresh follows each row's pinned `credential_source`.

For Discord, this page also does not configure the server-invite app. Its Application ID and Secret come from `[auth].discord_bot_client_id` and `[auth].discord_bot_client_secret`; the global Bot Token is entered under [Providers](./providers.md).

## Configuration

System connections are managed in the admin dashboard at **Admin > System** (`/system`), in the **System Connections** section below system API keys. The section renders one card per platform, each showing a **Configured** / **Not Configured** badge. For each platform you can:

- **Configure** (when unset) or **Update** (when set) the `client_id` and `client_secret`
- **Remove** the stored credentials

The Client ID is a plain text input and the Client Secret is a password input. The API returns the stored `client_id` and a `has_secret` boolean but never the secret itself, so re-saving a platform means re-entering the secret. The Configured / Not Configured badge is driven by `has_secret`.

Credentials are stored in the `integration_configs` table (JSONB `config` column: `client_id` plus the AES-256-GCM-encrypted secret under `client_secret_encrypted`) and encrypted at rest. The raw secret is never persisted in plaintext or returned by the API.

## Supported Platforms

The section renders a fixed list: `twitch`, `youtube`, `kick`, `discord`, `spotify`.

## Permissions

- `system-connections:read` - view configured platforms and their status
- `system-connections:edit` - create or update platform credentials
- `system-connections:delete` - remove platform credentials

The `/system` page as a whole opens for anyone holding **either** `system-keys:read` **or** `system-connections:read`. The Configure / Update / Remove controls are not additionally gated in the UI - enforcement is server-side on the permissions above, so an admin without `system-connections:edit` sees the buttons and gets a 403 from the call.

The dashboard entry itself is gated on `admin:access`. System admins (`is_system: true`) implicitly receive all admin permissions.

## API

| Action | GraphQL | REST |
|--------|---------|------|
| List system connections | `adminSystemConnections` | `GET /v1/admin/system-connections` |
| Create / update credentials | `adminUpsertSystemConnection` | `PUT /v1/admin/system-connections/{platform}` |
| Remove credentials | `adminDeleteSystemConnection` | `DELETE /v1/admin/system-connections/{platform}` |

---

## Admin / System Keys

Source: https://docs.lumio.vision/admin/system-keys

# System Keys

System Keys are long-lived API keys used for service-to-service authentication against the Lumio API. Unlike OAuth clients (which act on behalf of users) or user API keys (which act on behalf of a single account), a system key authenticates an internal Lumio service such as an external bot worker, a deployment health-check script, or a backend job. A system key is not bound to an account: it can act on **any** account, but only within the scopes it was minted with - a key reaches exactly what its scopes allow and nothing more. Mint them sparingly and with the narrowest scope set the consumer needs.

## Where to find it

**Admin sidebar → System** (`/system`) - the **System API Keys** card. System Keys and [System Connections](./system-connections.md) share this page.

## Quick start

1. Open **Admin → System**.
2. Scroll to the **System API Keys** card.
3. Click **Create Key**.
4. Enter a descriptive label (e.g. `Twitch Bot Key`) and select at least one scope from the searchable scope picker.
5. Click **Create Key** and copy the revealed key immediately - it is shown exactly once, stored hashed in the DB.
6. Use it as a bearer token in the `Authorization` header for internal service calls.

## Detailed walkthrough

### System API Keys card

Shows a key count ("N key(s)") and one card per key, not a table. Each key card shows:

- **Label** - human-friendly name given at creation, with the key's non-secret prefix in monospace next to it.
- **Permissions** - the scoped permission list, as chips.
- **Created** and **Last used** - dates on one line; "Last used" is omitted when the key has never been used.
- **Revoke** - a red button, gated on `system-keys:delete`. It deletes immediately with **no confirmation prompt**.

### Create System API Key form

Clicking **Create Key** (gated on `system-keys:create`) opens an inline card form, not a dialog:

- **Label** - free text, e.g. `Twitch Bot Key`.
- **Scopes** - a searchable, category-grouped picker (ZAF-1214). The Create button stays disabled until a label is entered **and** at least one scope is selected - and while the scope registry is still loading or failed to load.

**The picker is driven entirely by the backend registry - never a hardcoded list.** On open it fetches `GET /v1/admin/system-key-permissions` (GraphQL `adminSystemKeyPermissions`, guarded on `system-keys:read`) and renders every returned scope, grouped by category with a search box across the ~130 scopes. Category headers are localised (`en`/`de`); a category with no translation falls back to a humanised form of its registry key, so a scope is never silently dropped. Each scope is shown by its canonical key (e.g. `chat:write`) - the identifier the mint validates - rather than a separately maintained label that could drift (ZAF-428). Because the picker consumes the same registry the mint validates against, it can **never** offer a scope the create path rejects. Before ZAF-1213/1214 the dialog rendered a hardcoded 13-string list that the mint validated against the operator registry alone - every one of those chips was rejected and the whole flow was non-functional.

**The assignable registry** is `lo_auth::rbac::system_key::get_assignable_permissions()` (ZAF-1213): it unions the platform-operator registry (`all_admin_permissions()`), the account-scope service registry (`events:*`, `chat:*`, `overlays:*`, `connections:*`, …) and the user-scope registry, then removes a two-category **deny-list**: credential minting (`system-keys:create`, `apikeys:create`/`apikeys:edit`, `tokens:create`, `admin-roles:create`/`edit`/`delete`, `oauth-clients:create`) and tenant/platform destruction (`accounts:delete`, `account:delete`, `admin:privacy-erase`). On top of that it adds the **system-only** grants (`system_key::SYSTEM_ONLY_PERMISSIONS`) - today `bots:internal` (category `bots`), which exists for system keys alone and is in no role registry (ZAF-1922). Both create paths (`adminCreateSystemKey` and `POST /v1/admin/system-keys`) validate every requested permission against this one registry.

**Empty and error states are explicit, not a silently blank list.** The registry read is guarded on `system-keys:read`, which is a *different* guard from the `system-keys:create` gate on the Create button - an operator holding only `system-keys:create` can open the form but get a 403 on the registry read. In that case the picker shows an error state naming the missing `system-keys:read` requirement and a **Retry** button, and Create stays disabled. A registry that resolves but is empty shows a distinct "nothing assignable" notice.

**Wildcards (`admin:*`, `*:*`) are not mintable through this dialog** (ZAF-1213). The self-service mint path rejects them. The API does not load config-provisioned System keys. An operator-class key that needs platform-admin reach is granted the explicit `admin:access` scope (or specific admin permissions), never a wildcard. There is no `admin:access` auto-injection on the system-key mint - a machine credential is not a dashboard seat.

`audit:ingest` is the narrow grant the identity app (`apps/id`) needs to write user-scope security events (`user:login`, `user:oauth_granted`) to `POST /v1/internal/audit-ingest`. It is **system-key-only in effect**: the ingest endpoint requires a System key, so a human admin who happens to hold `audit:ingest` in an admin role can never write with it. Mint a **dedicated** key that carries only `audit:ingest` and nothing else - see [Provisioning the apps/id audit-ingest key](#provisioning-the-appsid-audit-ingest-key).

`bots:internal` is the grant for the bot fleet's internal surface (ZAF-1922): the bot channel/command/event feeds the platform bots read (`botChannels`, `botCommandsForAccount`, `emitBotEvent`, the `discordBot*` resolvers, `updateDiscordGuildInfo`, `removeDiscordGuildByBot`), the internal bot-module and automation-node feeds (`GET /v1/internal/bot-modules/{account_id}/triggers`, `GET /v1/internal/bot-modules/handlers`, `GET /v1/internal/automation-nodes/handlers`) the bot chat ingest (`POST /v1/chat/message` / `sendChatMessage`), and the cross-account extension and live surfaces (ZAF-1976): extension server functions on any install (`extensionQuery`, `extensionMutate`, `extensionExecuteHandler`; REST `POST /v1/extension-installs/{install_id}/{query,mutate,execute}/{function_name}`), draft/testing extension file trees (`extensionVersionFiles`; REST `GET /v1/extensions/{id}/versions/{version}/files`) and bundle bytes (`GET /v1/extension-bundles/...`), and the WebSocket `presence:*` and `sounds:*` channels. Each of these requires a system key **and** this grant - a system key without it is refused with `Missing permission: bots:internal`. It is **system-only**: unlike `audit:ingest` (declared in the operator registry, system-key-only in effect), it is in no role registry at all - not account, user or operator - so no role can hold it. See [Provisioning bot and worker keys](#provisioning-bot-and-worker-keys).

Submit invokes `POST /v1/admin/system-keys`; the response contains the plaintext key only once.

### API Key Created reveal dialog

Warning-styled, one-time display:

- Title: "API Key Created - Save Your Key".
- Body: "This key will only be shown once. Copy it now and store it securely."
- Buttons: **Copy Key**, **Dismiss**.

### Revocation

**Revoke** deletes the key row immediately - there is no confirmation dialog. Any subsequent request using that key returns `401`. There is no soft-disable / re-enable flow - rotation is delete + recreate.

## Common scenarios

- **Mint a key for a new bot worker** - label it after the worker (`kick-bot-prod`), select `bots:internal` plus the account scopes it uses (see [Provisioning bot and worker keys](#provisioning-bot-and-worker-keys)), store the secret in the secrets manager, configure the worker to send `Authorization: Bearer <key>`.
- **Provision the Discord bot** - create a key in the same environment with the `bots:internal` scope and set its one-time value as `DISCORD_BOT__API__SYSTEM_KEY` in the Discord bot service. `System access required` means the API did not accept a System key; `Missing permission: bots:internal` means the key is valid but lacks that grant. The API log names the first case: `lm_sys_ key not found in config or database` (the key belongs to another environment or was copied incompletely) or `System key expired`.
- **Rotate a leaked key** - create a new key, update the consumer to use it, then revoke the old one.
- **Audit inactive keys** - scan the "Last used" line on each card and revoke keys with no recent usage. The list is not sortable.

### Provisioning the apps/id audit-ingest key

The identity app (`apps/id`) writes user-scope security events (`user:login`, `user:oauth_granted`) to the Rust API via `POST /v1/internal/audit-ingest`, authenticated by a System key with the narrow `audit:ingest` grant. Without that key those events are silently dropped and `apps/id`'s `GET /api/health` reports `audit_ingest_configured=false`. To provision it:

1. Open **System → System Keys** and click **Create Key**.
2. Label it for the environment, e.g. `apps-id-audit-ingest-prod`.
3. In the scope picker, search for `audit:ingest` and select **only** that scope - nothing else. A dedicated single-grant key keeps the blast radius of a leak to audit ingest alone.
4. Create the key and copy the plaintext `lm_sys_…` value from the one-time reveal dialog.
5. Set it as `LUMIO_AUDIT_INGEST_KEY` in `apps/id`'s environment (see `apps/id/.env.example`) and redeploy `apps/id`.
6. Confirm `apps/id`'s `GET /api/health` now reports `audit_ingest_configured=true`, then verify a fresh login produces a `user:login` row in that user's [audit log](../features/audit-log.md).

Rotate it like any other system key: mint a replacement, update `LUMIO_AUDIT_INGEST_KEY`, redeploy, then revoke the old key.

Because the key carries only `audit:ingest`, it reaches no other System surface: every internal or cross-account System branch checks a named grant, never the key type alone - the bot-fleet surface, extension functions on any install, draft extension files and bundles, and the WebSocket `presence:*` / `sounds:*` channels all require `bots:internal`. What remains open to it is only what is open to *any* authenticated caller without a permission (for example the public-platform-data read `emoteInfo` / `GET /v1/emotes/info`, where a system key - having no account - gets no owner lookups).

### Provisioning bot and worker keys

The bot fleet - `twitch-bot`, `kick-bot`, `youtube-bot`, `discord-bot`, `bot-module-worker` and `automation-worker` - authenticates with system keys and reads its internal feeds under `bots:internal` (ZAF-1922). Each of these services' keys must carry:

- `bots:internal`, **plus**
- whatever account scopes the service already uses on the regular account surface (for example `chat:*`, `events:*` or moderation scopes the bot calls on behalf of an account).

A bot/worker key without `bots:internal` authenticates but is refused on every fleet feed (`403 Missing permission: bots:internal` on REST, the same `Missing permission: bots:internal` error on GraphQL). Scopes cannot be edited after creation, so an existing key that lacks the grant is fixed by minting a replacement that includes it, rolling it out to the service, and revoking the old key - an operator holding `system-keys:create` and `system-keys:delete` does this from this page. Keep one key per service and environment so each key's reach stays limited to what that service needs.

## Permissions

| Action | Permission |
|--------|-----------|
| View keys | `system-keys:read` |
| Create a key | `system-keys:create` |
| Revoke a key | `system-keys:delete` |

Dashboard entry requires `admin:access`. System admins implicitly hold every system-keys permission.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List system keys | `adminSystemKeys` | `GET /v1/admin/system-keys` |
| Create a system key | `adminCreateSystemKey` | `POST /v1/admin/system-keys` |
| Revoke a system key | `adminDeleteSystemKey` | `DELETE /v1/admin/system-keys/{id}` |
| List assignable scopes | `adminSystemKeyPermissions` | `GET /v1/admin/system-key-permissions` |

## Tips & gotchas

- **The plaintext key is shown once.** The key card displays only the non-secret prefix afterwards; there is no way to recover the full key, so lost keys must be revoked and recreated.
- Keys are stored as a SHA-256 hash in the `api_keys` table (the row is flagged `is_system = true`, with no owning user or account). The DB never sees the plaintext after creation.
- System keys are one of Lumio's authenticated token contexts. See [Authentication](../api-reference/authentication.md) for the public auth overview.
- Label is free-form, but putting the environment (`prod`, `staging`) in the name helps auditing later.
- Permissions are chosen at creation time and cannot be edited afterwards - there is no update endpoint. Changing a key's scope means creating a new key and revoking the old one.
- **Revoke has no confirmation.** One click deletes the key.

## Related

- [System Connections](./system-connections.md) - Lumio's outbound OAuth credentials (shares the same page)
- [OAuth Clients](./oauth-clients.md) - public OAuth apps for third-party users

---

## Admin / User Roles (Admin)

Source: https://docs.lumio.vision/admin/user-roles

# User Roles (Admin)

The User Roles section lets admins manage the third RBAC layer in Lumio - the set of user-scope permissions that controls what authenticated users can do across community features like the Ideas Hub. This is distinct from the account-scope roles (which control dashboard access within a streaming account) and from admin roles (which control access to the admin panel itself).

## Where to Find It

**Admin sidebar → User Roles** (`/user-roles`). The whole role editor is a dialog on that one page - there are no `/user-roles/{id}` detail routes. Per-user role assignments and permission overrides are managed from the user detail page at `/users/{id}`. Per-account permission overrides are managed from the account detail page at `/accounts/{id}`.

## Role List

The list at `/user-roles` shows all user roles.

### Columns

| Column | Description |
|--------|-------------|
| Name | Role display name, with the description underneath |
| Permissions | Count of permissions assigned to the role |
| Type | `System`, `Default`, or `Custom` badge |
| Actions | Edit (pencil) button, shown when the caller holds `user-roles:edit` |

The slug is not a list column - it appears in the edit dialog header under the role name.

Three roles are seeded as system roles (`is_system = true`) and cannot be deleted:

| Slug | Name | Permissions |
|------|------|-------------|
| `member` | Member | The default role for every user: `ideas:read`, `ideas:create`, `ideas:edit`, `ideas:delete`, `ideas:vote`, `ideas:comment_read`, `ideas:comment_create`, `ideas:comment_edit`, `ideas:comment_delete`, `ideas:comment_vote` |
| `restricted` | Restricted | Read-only: `ideas:read`, `ideas:comment_read` |
| `moderator` | Moderator | Everything `member` has, plus `ideas:moderate_status`, `ideas:moderate_edit`, `ideas:moderate_delete`, `ideas:moderate_comment` |

`member` is also flagged `is_default`, so it carries the **Default** badge.

## Role Editor

Clicking a row (or the pencil) opens the **Edit Role** dialog. There is no read-only detail view - the dialog is the only editor.

### Creating a Custom Role

Click **Create Role** (requires `user-roles:create`). The dialog fields are:

| Field | Required | Notes |
|-------|:--------:|-------|
| Name | Yes | Display name, max 100 characters |
| Slug | Yes | Auto-derived from the name; editable before saving |
| Description | No | Shown under the name in the role list |
| Permissions | No | Checkbox picker grouped by category (see [Permission Categories](#permission-categories)) |

Save to create the role. It becomes immediately available in the per-user role picker.

### Editing a Role

The dialog exposes name, description, the permission picker, a **Members** section, and a Danger Zone. **Save Changes** stays disabled until something actually changed, and it sends only the changed fields as a PATCH.

For **system roles** the dialog opens read-only: an italic note reads "System roles are read-only and cannot be modified", the name/description inputs are disabled, and Save is disabled. The pencil is still shown - the block happens inside the dialog, not on the row.

### Deleting a Custom Role

The **Danger Zone** block at the bottom of the edit dialog carries **Delete Role**, gated on `user-roles:delete` and rendered only for non-system roles. A confirmation dialog follows. The server also refuses to delete a system role.

### Members

The edit dialog contains a **Members** section: a list of the users holding this role (name, email, avatar), a debounced user search to add more, and a remove button per member. The list is served by `GET /api/user-roles/{id}/members` (backed by the `userRoleMembers` query, gated on `user-roles:read`); adding and removing members go through `PUT` / `DELETE /api/user-roles/{id}/members/{userId}` (backed by `assignUserRole` / `removeUserRole`, gated on `user-roles:edit`). The search field and the per-member remove button are gated on `user-roles:edit`. You can also assign and remove roles from the **Roles** card on the [user detail page](./users.md).

## Permission Categories

The role editor's permission picker offers a fixed set of user-scope permissions, grouped into two categories:

| Category | Permissions |
|----------|-------------|
| **Ideas** | `ideas:read`, `ideas:create`, `ideas:edit`, `ideas:delete`, `ideas:vote` |
| **Comments** | `ideas:comment_read`, `ideas:comment_create`, `ideas:comment_edit`, `ideas:comment_delete`, `ideas:comment_vote` |

Each category header has a tri-state checkbox that selects or clears the whole group.

The `ideas:moderate_*` permissions are **not** offered by the picker: idea moderation is an admin-scope capability and cannot be assigned to a custom user role. The seeded `moderator` system role carries them server-side (it is immutable and not edited through this picker).

## Per-User Role Assignments

From the user detail page at `/users/{id}`, the **Roles** card lists the user's assignments. A user can hold **several** roles, and the card mixes both RBAC layers:

- **User roles** - badged `User`, plus `System` / `Default` badges where applicable. Removing one requires `user-roles:edit`.
- **Admin roles** - badged `Admin`. Removing one requires `admin-roles:edit`.

A single grouped dropdown at the bottom of the card assigns either kind, with `User Roles` and `Admin Roles` option groups.

## Per-User Permission Overrides

From the user detail page, the **Permission Overrides** card shows all explicit overrides for that user.

Each override row shows:

- The permission string (e.g., `ideas:create`).
- **Status** - a **Granted** or **Denied** badge.
- **Reason** - the free-text reason recorded with the override, or `—`.
- **Set** - when the override was created.
- A remove button.

To add an override, use the **Add Override** form under the table: pick a permission from the dropdown (populated from `/api/assignable-permissions`, which mirrors the backend permission registry so the picker cannot drift), choose grant or deny, optionally give a reason, and save.

Overrides layer on top of the role: granting a permission gives it to the user even if their role does not include it; denying removes it even if the role does include it. Per-user overrides are applied before account-level overrides in the resolution chain.

Per-user overrides are gated on `user-roles:read` (list) and `user-roles:edit` (set / remove) - not on the per-account override permissions (`accounts:overrides-read` / `accounts:overrides-edit`).

## Per-Account Permission Overrides

From the account detail page at `/accounts/{id}`, the **Permission Overrides** card shows the user-scope overrides applied to **all users** who have that account as their active account when making requests.

The interface mirrors the per-user override UI: each row shows the permission, granted/denied state, and a remove button. Add new overrides via **Add Override**.

Account overrides are the last layer in the permission resolution chain - they can grant permissions that the user's role and individual overrides do not provide, or deny permissions that they would otherwise have.

Reading the overrides requires `accounts:overrides-read`; setting or removing them requires `accounts:overrides-edit`.

## Effective Permissions View

The user detail page renders an **Effective Permissions** card directly (no button, no modal). It shows the fully-resolved permission set for that user - role permissions merged with user overrides and account overrides - grouped by permission category. Any permission that an override contributed is highlighted in amber with an **Overridden** badge, which makes it easy to see why a user has (or lacks) access.

## Permissions

All actions in this section require `admin:access` (the dashboard-entry gate). In addition:

| Action | Permission |
|--------|-----------|
| View role list, role members, user override lists, resolved permissions | `user-roles:read` |
| Create a role (UI button gate) | `user-roles:create` |
| Delete a role (UI button gate) | `user-roles:delete` |
| Create / update / delete roles, assign & unassign roles, set & remove per-user permission overrides (server-side gate) | `user-roles:edit` |
| Read per-account permission overrides | `accounts:overrides-read` |
| Set or remove per-account permission overrides | `accounts:overrides-edit` |

`user-roles:create` and `user-roles:delete` exist in the admin permission registry and gate the corresponding buttons in the admin UI, but the API enforces `user-roles:edit` on every user-role mutation, including create and delete. Grant `user-roles:edit` alongside them.

System admins implicitly have all permissions.

## API

User-role endpoints are **not** under the `/v1/admin` prefix - they sit at the `/v1` root and are guarded by admin permissions.

| UI Action | GraphQL | REST |
|-----------|---------|------|
| List user roles | `userRoles` | `GET /v1/user-roles` |
| Create role | `createUserRole(input: CreateUserRoleInput!)` | `POST /v1/user-roles` |
| Update role | `updateUserRole(id: UUID!, input: UpdateUserRoleInput!)` | `PATCH /v1/user-roles/{id}` |
| Delete role | `deleteUserRole(id: UUID!)` | `DELETE /v1/user-roles/{id}` |
| List a user's role assignments | `userRoleAssignments(userId: UUID!)` | `GET /v1/users/{user_id}/roles` |
| Assign user role | `assignUserRole(userId, roleId)` | `POST /v1/users/{user_id}/roles` |
| Remove user role | `removeUserRole(userId, roleId)` | `DELETE /v1/users/{user_id}/roles/{role_id}` |
| List user overrides | `userPermissionOverrides(userId)` | `GET /v1/users/{user_id}/permission-overrides` |
| Set user override | `setUserPermissionOverride(userId, permission, granted, reason)` | `PUT /v1/users/{user_id}/permission-overrides` |
| Remove user override | `removeUserPermissionOverride(userId, permission)` | `DELETE /v1/users/{user_id}/permission-overrides/{permission}` |
| Resolved permissions | `resolvedUserPermissions(userId)` | `GET /v1/users/{user_id}/permissions/resolved` |
| List account overrides | `adminAccountPermissionOverrides(accountId)` | `GET /v1/admin/accounts/{id}/permission-overrides` |
| Set account override | `adminSetAccountPermissionOverride(accountId, permission, granted, reason)` | `PUT /v1/admin/accounts/{id}/permission-overrides` |
| Remove account override | `adminRemoveAccountPermissionOverride(accountId, permission)` | `DELETE /v1/admin/accounts/{id}/permission-overrides/{permission}` |

The admin app does not call these directly - it goes through its own Next.js proxy routes (`/api/user-roles/*`, `/api/users/{id}/roles`, `/api/users/{id}/permission-overrides`, `/api/users/{id}/effective-permissions`), which execute the GraphQL operations above.

## Related

- [User Roles developer guide](../developer-guide/user-roles.md) - tables, resolution algorithm, AuthContext changes, cache
- [RBAC & Permissions developer guide](../developer-guide/rbac-permissions.md) - account-scope and admin-scope RBAC layers
- [Users](./users.md) - managing users and their account memberships
- [Accounts](./accounts.md) - managing streaming accounts

---

## Admin / Users

Source: https://docs.lumio.vision/admin/users

# Users

The Users view lists every registered Lumio user across all accounts. Admins can edit user details (display name, email), manage login connections (disconnect, set reconnect flags), manage account memberships (add to / remove from accounts), override account creation and max-account limits, and delete users entirely.

## Where to find it

**Admin sidebar → Users**. The list lives at `/users`; detail pages live at `/users/{id}`.

## Quick start

1. Open **Admin → Users**.
2. Search by display name or email using the top search bar.
3. Click any row to open the user detail page.
4. Inspect login connections and account memberships in the stacked cards.
5. If a login provider needs to be detached, use the delete button on that connection row.

## Detailed walkthrough

### Users list (`/users`)

- **Search** - debounced 300 ms search on display name and email.
- **Columns** - Avatar + display name, Email, Created date, Last Login date. When a user's display name is a *localized* (non-Latin) name that differs from their platform handle - e.g. Twitch's `こさむん` whose login is `kosamun` - the handle is shown in brackets after it (`こさむん (kosamun)`) so operators can still identify the account. Ordinary case-variant names (`Cruex` / `cruex`) render the display name alone. This applies wherever an operator sees a person's name across the admin app (user search, account owners and members, role members, audit-log actors, developers and teams, ideas authors).
- **Pagination** - 25 users per page; "Page X of Y (N users)" footer.
- **Row click** - navigates to `/users/{id}`.

### User detail (`/users/[id]`)

The detail page stacks these cards:

1. **User Information** - Display name and email (both editable inline, requires `users:edit`), User ID, Created At, Last Login. A **Delete User** button (requires `users:delete`) opens a confirmation dialog before permanently deleting the user and all their data. While the user's developer profile still has a revenue balance or a payout in progress, the dialog stays open and says so: the user can be deleted once Lumio has paid it out. If Lumio cannot pay the balance out (no payout method, or identity not verified), operators with `developer-funds:release-deletion` and `users:delete` see **Release balance as a liability and delete** in that dialog; see [Releasing an unpayable developer balance](#releasing-an-unpayable-developer-balance).
2. **Login Connections** - table of every identity provider the user has linked: Provider (the `google` provider renders as "YouTube"), Username on that provider (falling back to the provider account ID; a *localized* Twitch handle whose display name differs from the login renders as `こさむん (kosamun)`, using the same rule as the person-name columns above - only Twitch connections bracket, since only Twitch has freely-editable localized display names), Connected Since, Actions. Each row carries a reconnect-flag toggle and a **Disconnect** button.
3. **Account Memberships** - table of every account the user belongs to: Account (linked to `/accounts/{account_id}`), Plan badge, Role, Owner flag, Actions. An **Add to Account** button (requires `accounts:edit`) adds the user to an account by account ID. Each non-owner membership row has a **Remove** button with a confirmation dialog.
4. **Account Creation** - 3-state override dropdown that controls whether this user may create new accounts (see [Account Creation Override](#account-creation-override) below). Rendered only for admins with `users:edit`.
5. **Account Limit Override** - optional integer override for how many accounts the user can own (see [Max Accounts Override](#max-accounts-override) below). Rendered only for admins with `users:edit`.
6. **Extension Dev Mode** - enable/disable extension development mode for this user. Rendered only for admins with `developer-limits:edit`.
6b. **Setting Presets** - lists this user's [setting presets](../features/setting-presets.md) (name, kind, default badge, last-changed; never the payload) with a **Delete** action per preset. Viewing requires `users:read`, deleting requires `users:edit`. Presets are user-bound, so a delete removes the preset for this user across every account they belong to; it emits `system:user_setting_preset_deleted`. The [account detail](./accounts.md) page mirrors this list per member.
7. **Roles** - the user's **user-role** and **admin-role** assignments in one list, each entry badged `User` or `Admin`. A user can hold several of each. Assign via the grouped dropdown at the bottom of the card; remove with the trash button on an entry. User-role rows are gated on `user-roles:edit`, admin-role rows on `admin-roles:edit`.
8. **Permission Overrides** - per-user overrides of user-scope permissions. Columns: Permission, Status (Granted / Denied), Reason, Set (timestamp), remove button. Add via the **Add Override** form. Gated on `user-roles:edit`.
9. **Effective Permissions** - the fully resolved permission set for the user, grouped by category. Permissions that come from an override are highlighted in amber with an **Overridden** badge.

The **Support Identity** card shows the user's Lumio ID and current hourly support code, lets an operator check a code supplied by the user, and lists recent checks. All three actions require admin `support:verify`, seeded to the `system_admin` and `support` admin roles and assignable to custom admin roles; revealing and checking are audited without recording the code. The check is limited to five attempts per profile per ten minutes. The card needs `LUMIO__SUPPORT__CODE_SECRET` outside development; without it the API logs a startup warning and the support code is unavailable — the card then says so as soon as it opens, in place of **Show code**, and the check is disabled (see [Installation](../getting-started/installation.md)). **Reset 2FA** requires admin `users:edit` and a written reason. The card shows counts of authenticator apps and passkeys, never their user-chosen names. A reset removes all methods, recovery codes and trusted devices and notifies the user.

### Max Accounts Override

The **Max Accounts Override** section lets admins grant a specific user the ability to own more (or fewer) Lumio accounts than their plan normally allows.

The field is stored as `max_accounts_override` on the user record and accepts an optional positive integer. When set, it replaces the plan-derived account limit for that user. When `null`, the plan default (the plan's `max_accounts` column) is used.

**Field values:**

| Value | Meaning |
|-------|---------|
| `null` | Use the plan default (no override). |
| `1` or more | User may own up to this many accounts regardless of plan. |

Updating this field goes through GraphQL: `adminUpdateUserMaxAccountsOverride(userId: UUID!, maxAccounts: Int)`. `PATCH /v1/admin/users/{id}` does **not** accept a `max_accounts_override` field - its body is limited to `account_creation_override`, `display_name`, and `email`. The admin UI reaches the mutation through its own proxy route at `/api/users/{id}/max-accounts-override`. Requires the `users:edit` admin permission.

The override is exposed in:
- `GET /v1/admin/users/{id}` response body (`max_accounts_override` field)
- `adminUser(id)` GraphQL query (`maxAccountsOverride` field on `AdminUser`)

### Account Creation Override

The **Account Creation** section lets admins grant or deny a specific user the ability to create streaming accounts, regardless of the global `system:account_creation` flag setting.

**Dropdown options:**

| Option | REST value | GraphQL enum | Meaning |
|--------|-----------|--------------|---------|
| Default (inherit global) | `"default"` | `DEFAULT` | Defer to the global `system:account_creation` flag. If the flag is ON, the user can create accounts; if OFF, they cannot. |
| Allow | `"allow"` | `ALLOW` | User may always create an account, even if the global flag is OFF. |
| Deny | `"deny"` | `DENY` | User is always blocked from creating an account, even if the global flag is ON. |

The value is persisted as a nullable boolean on the user row (`null` / `true` / `false`); both wire formats map onto it.

**Effective state** - a line below the dropdown shows the resolved outcome by combining the dropdown value with the global flag state: **Allowed**, **Blocked**, or **Allowed (global block bypassed)** when the global flag is off but this user is explicitly allowed.

Saving the override calls `PATCH /v1/admin/users/{id}` with `{ "account_creation_override": "default" \| "allow" \| "deny" }` (REST) or the `adminUpdateUserAccountCreationOverride(userId, override)` mutation (GraphQL). The admin UI reaches it through `/api/users/{id}/account-creation-override`.

## Common scenarios

- **Abuse investigation** - open a user, check their account memberships to see what data they control, then follow up in each account.
- **Compromised OAuth** - delete the affected login connection. The user must re-link that provider before using it again.
- **Duplicate account merge** - the admin UI does not merge users. Use the CLI/DB for merges; use this page to verify account memberships first.
- **"Why can't user X log in?"** - inspect Login Connections to confirm they still have at least one working provider link.


## Releasing an unpayable developer balance

A deletion is refused while the person's developer profile still has a revenue balance (`DEVELOPER_FUNDS_OUTSTANDING`). A payable balance goes through the closing payout first. When Lumio **cannot** pay it out — no payout method, or the identity is not verified — and the person asked for the deletion, the delete dialog offers **Release balance as a liability and delete**. It is shown only to operators with `developer-funds:release-deletion` and the plain delete permission (`users:delete` here, `developer-verification:edit` on the [developer pages](./developer-limits.md)).

1. Open the action from the delete dialog. The dialog states what happens: the user or profile is deleted now, the person gets an e-mail with the amount and a claim code, and Lumio keeps the record until 31 December of the third year after the release year (longer if the person files a claim before then).
2. Enter the **Request reference** (ticket or request ID of the deletion request, up to 64 characters) and the **Reason** (up to 500 characters). Both are mandatory. **Do not enter names, e-mail addresses or other contact data in either field** — the release mail tells the person that Lumio stores none.
3. Click **Book and delete**. The server decides the case. It refuses a payable balance ("use the closing payout instead") and a payout in progress; in both cases nothing is deleted and the dialog names the reason.
4. If the release mail could not be sent, the dialog shows the **claim code** once, with a copy button. Pass it to the person through their request channel, then click **I have saved the code**. Lumio does not store the code in plain text and cannot show it again.

The action emits `developer:funds_deletion_released` (System scope) in the [audit log](./audit-log.md).

A refund or chargeback of a sale made before the release finds no developer to debit any more (the extensions are deleted with the profile). The released amount still contains that sale's share, so Lumio owes the person slightly more than the sale finally earned; this is accepted, and the release is not held back for the refund window. The API logs such a refund as a warning.

### Settling a released balance

When the person comes back with the claim code, an operator with `developer-funds:settle` settles the claim in two steps on the [developer pages](./developer-limits.md). Both steps need an interactive session; API keys are refused. The claim code is sent in the request body only, never in a URL.

1. **Code presented**: on the **Developers** list, click **Claim code presented**, enter the code (separators, spaces and case are ignored) and click **Record code** (`adminStartReleasedBalanceClaim` / `POST /v1/admin/released-balances/claim`). Do this as soon as the person sends the code, even before they have a new developer profile. The dialog shows the amount, the reason for the release (no payout method / identity not verified), the release date and when the code was first presented. From then on Lumio keeps the record until the claim is settled, even past the end of the third year after the release. A repeat is harmless: it keeps the first time and says the code was already presented.
2. **Settle**: open the person's new developer profile and click **Settle a released balance** in the **Released balance** section. Enter the code and click **Record code** (repeats step 1 harmlessly and shows the amount), then the **Credit** button with the amount (`adminSettleReleasedBalance` / `POST /v1/admin/released-balances/settle`). The profile's identity must be **verified**. The dialog shows the profile's new balance. The normal payout then pays the amount out with its credit note, where the settled amount is its own line with the release date (see [Developer Credit Notes](../features/developer-credit-notes.md#lines)). A code can be settled only once.

The dialog names each refusal: an invalid code, no released balance for the code, a code that is already settled, a profile whose identity is not verified yet, and a profile that no longer exists.

The steps emit `developer:funds_released_claim_started` and `developer:funds_released_settled` (System scope). A settled record is kept for 8 years after the settlement year, and longer while part of the amount has not been paid out from the new profile yet. Once settled, the record belongs to the new profile: the person's [data export](../user-guide/privacy-and-export.md) lists it under `settled_released_balances` in `developer.json`.
## Permissions

| Action | Permission |
|--------|-----------|
| View user list / detail | `users:read` |
| Edit display name / email | `users:edit` |
| Reveal/check a user's support code and see recent checks | `support:verify` |
| Reset a user's 2FA with a recorded reason | `users:edit` |
| Delete a user's login connection | `users:edit` |
| Set reconnect flag on login connections | `users:edit` |
| Update account creation / max accounts override | `users:edit` |
| Delete a user | `users:delete` |
| Release an unpayable developer balance as a liability and delete the user | `developer-funds:release-deletion` + `users:delete` |
| Record a presented claim code / settle a released balance on a new profile | `developer-funds:settle` |
| Add / remove account memberships | `accounts:edit` |
| Assign / remove user roles, manage per-user permission overrides | `user-roles:edit` |
| Assign / remove admin roles | `admin-roles:edit` |
| Toggle Extension Dev Mode | `developer-limits:edit` |

All actions additionally require `admin:access`. System admins (`system_admin.is_system = true`) implicitly have every permission.

## API

| UI action | GraphQL | REST |
|-----------|---------|------|
| List users (paginated, searchable) | `adminUsers` | `GET /v1/admin/users` |
| Get user detail | `adminUser` | `GET /v1/admin/users/{id}` |
| Update display name / email | `adminUpdateUser` | `PATCH /v1/admin/users/{id}` |
| Delete user (refused with `409 DEVELOPER_FUNDS_OUTSTANDING` while the user's developer profile has a balance or a payout in progress) | `adminDeleteUser` | `DELETE /v1/admin/users/{id}` |
| Release an unpayable developer balance as a liability, then delete the user (admin `developer-funds:release-deletion` + `users:delete`, interactive session; see [Developer balance release](../api-reference/rest-api.md#developer-balance-release-admin)) | `adminReleaseFundsAndDeleteUser` | `POST /v1/admin/users/{id}/release-funds-delete` |
| Record that a person presented the claim code of a released balance (admin `developer-funds:settle`, interactive session) | `adminStartReleasedBalanceClaim` | `POST /v1/admin/released-balances/claim` |
| Credit a released balance to the person's new, verified developer profile (admin `developer-funds:settle`, interactive session) | `adminSettleReleasedBalance` | `POST /v1/admin/released-balances/settle` |
| Delete a login connection | `adminDeleteUserLoginConnection` | `DELETE /v1/admin/users/{id}/login-connections/{provider}` |
| Set login reconnect flag | `adminSetLoginReconnectFlag` | `PUT /v1/admin/login-connections/{id}/reconnect-flag` |
| Update account creation override | `adminUpdateUserAccountCreationOverride` | `PATCH /v1/admin/users/{id}` (body field `account_creation_override`) |
| Update max accounts override | `adminUpdateUserMaxAccountsOverride` | -- |
| List / assign / remove user roles | `userRoleAssignments` / `assignUserRole` / `removeUserRole` | `GET` / `POST` `/v1/users/{user_id}/roles`, `DELETE /v1/users/{user_id}/roles/{role_id}` |
| List admin roles for a user | `adminUserAdminRoles` | -- |
| Assign / remove admin role | `adminAssignUserRole` / `adminUnassignUserRole` | `PUT` / `DELETE` `/v1/admin/admin-roles/{id}/members/{userId}` |
| Per-user permission overrides | `userPermissionOverrides` / `setUserPermissionOverride` / `removeUserPermissionOverride` | `GET` / `PUT` `/v1/users/{user_id}/permission-overrides`, `DELETE /v1/users/{user_id}/permission-overrides/{permission}` |
| Effective permissions | `resolvedUserPermissions` | `GET /v1/users/{user_id}/permissions/resolved` |
| Toggle Extension Dev Mode | `setExtensionDevMode` | -- |
| List a user's setting presets | `adminUserSettingPresets` | `GET /v1/admin/users/{id}/setting-presets` |
| Delete a user's setting preset | `adminDeleteUserSettingPreset` | `DELETE /v1/admin/setting-presets/{id}` |

## Tips & gotchas

- There is **no ban / unban** surface in the admin app today. Blocking a user from logging in is done by removing all of their login connections or deleting the user entirely.
- There is **no sessions management** in the admin user view. Session admin is handled per-account by the account owner (see the user-facing docs for the sessions page).
- Admins can add/remove account memberships from the user detail page. Changing a member's account role still happens inside the account itself, not from the admin panel.
- The list uses the Next.js proxy route `/api/users` which calls the REST admin endpoint underneath.
- Deleting a user is permanent and cascades to all their data. Use with caution.

## Related

- [Accounts](./accounts.md) - which accounts a user belongs to
- [Audit Log](./audit-log.md) - record of login / logout / admin events
- [OAuth Clients](./oauth-clients.md) - public OAuth apps that can act on behalf of users