141 lines
6.9 KiB
Markdown
141 lines
6.9 KiB
Markdown
# 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 confidential Twitch developer application whose OAuth callback is the
|
|
public Twungeon `/oauth/callback` URL.
|
|
- 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
|
|
|
|
Provide the following values first. Keep `TWITCH_ENABLED=false` until OAuth,
|
|
Extension, and Channel Points setup are complete; then switch it to `true` for
|
|
live operation.
|
|
|
|
| Variable | Purpose |
|
|
| --- | --- |
|
|
| `TWITCH_CLIENT_ID` | Confidential OAuth application 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_EXTENSION_SECRET` | Base64 Extension shared secret |
|
|
| `TWITCH_OAUTH_REDIRECT_URI` | Exact HTTPS OAuth callback registered with Twitch |
|
|
| `TWITCH_TOKEN_FILE` | Restricted file used for access and refresh tokens |
|
|
| `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.
|
|
|
|
## Broadcaster OAuth authorization
|
|
|
|
1. Register a **Confidential** Twitch application with an exact HTTPS redirect
|
|
such as `https://twungeon.example/oauth/callback`.
|
|
2. Configure `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET`,
|
|
`TWITCH_CHANNEL_LOGIN`, `TWITCH_OAUTH_REDIRECT_URI`, and
|
|
`TWITCH_TOKEN_FILE` while leaving `TWITCH_ENABLED=false`.
|
|
3. Restart Twungeon and confirm `/oauth/status` reports `configured: true` and
|
|
`authorized: false`.
|
|
4. Open `/oauth/login` in a browser and authorize using the configured
|
|
broadcaster account. Twungeon requests only `chat:read`,
|
|
`moderator:read:followers`, and `channel:read:redemptions`.
|
|
5. Confirm the callback reports success and `/oauth/status` reports
|
|
`authorized: true`. The callback validates the client ID, broadcaster login,
|
|
and required scopes before storing the token.
|
|
6. Record the numeric broadcaster ID shown by the callback as
|
|
`TWITCH_BROADCASTER_ID`.
|
|
|
|
The access and refresh tokens are stored atomically at `TWITCH_TOKEN_FILE` with
|
|
owner-only permissions. Twurple refreshes the access token when necessary and
|
|
Twungeon replaces the stored token without printing either token. The token
|
|
directory must be writable only by the Twungeon service account. Never place the
|
|
token file inside the repository or a web-served directory.
|
|
|
|
## Extension configuration
|
|
|
|
1. Create a Twitch Extension separately from the confidential OAuth
|
|
application. In the Extension Manager, use a testing base URI ending in
|
|
`/`, select a video component, and set its viewer path to `extension`.
|
|
2. Enable **Request Identity Link**. The viewer must click **Share Twitch
|
|
identity** in the component; the Extension Helper then invokes
|
|
`requestIdShare()` from that user gesture and supplies a new JWT through
|
|
`onAuthorized`.
|
|
3. 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.
|