Implement Channel Points Twungeon MVP

docs/twitch-setup.md

@@ -0,0 +1,109 @@
+# Twitch setup
+
+This guide connects the Twungeon proof of concept to a Twitch development
+channel. Never commit real values: copy `.env.example` to an ignored `.env` or
+provide the variables through your process manager.
+
+## Prerequisites
+
+- Node.js 22 or newer and npm.
+- A Twitch developer application and a development channel.
+- A Twitch Extension with identity sharing enabled. Twungeon requires the
+  numeric `user_id`; anonymous or opaque-only viewers fail closed.
+- A broadcaster user access token that can read chat and check followers.
+- The Extension shared secret, copied exactly as the base64 value supplied by
+  the Extension Manager.
+
+The installed Twurple packages are locked in `package-lock.json`. Re-check
+their release documentation and Twitch's current scope requirements before
+rotating tokens or upgrading packages.
+
+## Required environment
+
+Set `TWITCH_ENABLED=true`, then provide:
+
+| Variable | Purpose |
+| --- | --- |
+| `TWITCH_CLIENT_ID` | Developer application/Extension client ID |
+| `TWITCH_CLIENT_SECRET` | Server-only application secret |
+| `TWITCH_BROADCASTER_ID` | Numeric channel owner ID |
+| `TWITCH_CHANNEL_LOGIN` | Channel login joined by Twurple chat |
+| `TWITCH_BOT_ACCESS_TOKEN` | Broadcaster user access token |
+| `TWITCH_EXTENSION_SECRET` | Base64 Extension shared secret |
+| `CHANNEL_POINTS_RESURRECTION_REWARD_ID` | Stable ID of the resurrection custom reward |
+| `PUBLIC_BASE_URL` | Public HTTPS backend origin |
+
+The user token currently needs `chat:read`, `moderator:read:followers`, and
+`channel:read:redemptions`. The follower and Channel Points subscriptions use
+the broadcaster token, so its subject must match `TWITCH_BROADCASTER_ID`.
+Twungeon subscribes only to the configured custom reward and uses Twitch's
+stable redemption ID as the deduplication key. The broadcaster owns the reward
+cost in Twitch; the backend does not duplicate it.
+
+## Extension configuration
+
+1. Host the built static files and backend at an HTTPS origin allowed by the
+   Extension configuration. Twitch embeds the UI in an iframe and supplies the
+   Extension Helper JWT through `onAuthorized`.
+2. Point the viewer/mobile video component to the application root.
+3. Enable identity sharing. A JWT without `user_id`, with the wrong
+   `channel_id`, an expired signature, or an `external` role is rejected.
+4. Keep the Extension secret only in the backend environment. It must never be
+   included in the UI bundle or URL.
+5. Start with `npm run build && npm start`. Confirm `/health` returns `ready:
+   true` and `twitchMode: "configured"` after chat connects.
+
+The Extension JWT is exchanged for a random 15-minute Twungeon session. A
+refresh obtains a new Twitch JWT, re-verifies it, and restores the existing
+character; it does not create a player.
+
+## Channel Points reward
+
+1. In the broadcaster dashboard, create one custom reward for resurrection.
+2. Choose its title and cost in Twitch. Disable viewer text input unless the
+   channel has a separate moderation reason to keep it.
+3. Enable **Skip Reward Requests Queue** because Twungeon consumes the
+   redemption immediately and uses read-only EventSub access rather than
+   managing fulfillment status.
+4. Retrieve the reward's stable ID through the Twitch API or Twitch CLI using
+   the broadcaster token, and set it as
+   `CHANNEL_POINTS_RESURRECTION_REWARD_ID`.
+5. Do not reuse that reward for another action. Redemptions of every other
+   reward are ignored by the domain.
+
+Bits, Cheers, and Bits-in-Extensions products are outside the MVP and have no
+gameplay handler.
+
+## Event flow
+
+1. A follower types `!spawn` in chat.
+2. Twurple supplies the stable chatter ID; the API checks that ID against the
+   broadcaster's followers.
+3. The Extension sends its current Twitch JWT to
+   `POST /api/extension/session`.
+4. The backend verifies signature, expiry, channel, role, and numeric user ID.
+5. Controls enable only when the verified ID equals the chat-spawn owner ID.
+6. A redemption of the configured Channel Points reward by the dead player
+   invokes resurrection exactly once.
+
+## Troubleshooting and rotation
+
+- **Chat disconnected:** check token validity, `chat:read`, channel login, and
+  outbound WebSocket access. Existing game state continues; new Twitch inputs
+  fail closed until reconnect.
+- **Follower rejected:** ensure the token belongs to the broadcaster and has
+  `moderator:read:followers`; confirm the numeric broadcaster ID.
+- **Extension returns `UNAUTHENTICATED`:** check the base64 secret, JWT expiry,
+  allowed channel, and identity-sharing capability. Never log the JWT.
+- **`IDENTITY_NOT_BOUND`:** compare the chat and verified Extension numeric IDs;
+  display names are deliberately ignored for ownership.
+- **Reward does not resurrect:** confirm the configured reward ID, the
+  `channel:read:redemptions` scope, the dead character owner ID, and that the
+  redemption was not already processed.
+- **Public iframe fails:** confirm TLS, allowed origins, Extension asset paths,
+  and that WebSocket traffic reaches `/ws`.
+
+To rotate credentials, stop new Twitch intake, replace the server environment,
+restart, verify `/health`, test one follower check and Extension login, then
+revoke the old token/secret. A full process restart creates a new in-memory run,
+as required by the MVP persistence boundary.