[Foundry P1] Pair a Foundry world: pairing codes, per-GM tokens, the Quest Board module served by each server (D333–D336)

rbrooks commented

2026-06-23 00:42:31 +00:00

Owner

Rewritten 2026-11-07 for the module design (D333–D338, #143 closed, #4 passed 7/7). The old scope (a server URL, an encrypted API key and a system selector) is gone: there is no URL field and no API key, so no SSRF exemption is needed.

The contract: docs/design/foundry-connection.md (branch feat/5-foundry-connect).

Scope

Pairing: a GM gets an 8-character code from Settings → Foundry (10 minutes, used once, Redis DB 0). Pairing happens over the module's socket. Only a Foundry Gamemaster can pair. One world per campaign. Any GM can pair; the owner can unpair the world (D336); a GM can remove a pairing they made.
Tokens: one per Foundry GM, stored as sha256 hashes, never logged, revocable.
The module (quest-board): served by each Quest Board server as /api/foundry/module.json and a zip that carries that server's wss:// address (D334), so a GM never types a URL. GM-only settings menu (#4 finding 1).
Tables: foundry_worlds and foundry_tokens, one migration.
nginx: upgrade headers for /api/foundry/ws.
Settings → Foundry (CAMP-16): the code, the paired world (name, system, core version), the paired GMs, Unpair. Drawn on a prototype page first; IS-268–271 are replaced.

Done when

A GM installs the module from their server's manifest URL, pairs The Amberwake Accord on foundry-dev with a code, and Settings → Foundry shows the world. The owner can unpair it, which drops the socket. A player can't pair. The token never appears in logs or responses after the one paired message.

**Rewritten 2026-11-07 for the module design** (D333–D338, #143 closed, #4 passed 7/7). The old scope (a server URL, an encrypted API key and a system selector) is gone: there is no URL field and no API key, so no SSRF exemption is needed. **The contract:** `docs/design/foundry-connection.md` (branch `feat/5-foundry-connect`). ## Scope - **Pairing:** a GM gets an 8-character code from Settings → Foundry (10 minutes, used once, Redis DB 0). Pairing happens over the module's socket. Only a Foundry Gamemaster can pair. One world per campaign. Any GM can pair; the owner can unpair the world (D336); a GM can remove a pairing they made. - **Tokens:** one per Foundry GM, stored as sha256 hashes, never logged, revocable. - **The module (`quest-board`):** served by each Quest Board server as `/api/foundry/module.json` and a zip that carries that server's `wss://` address (D334), so a GM never types a URL. GM-only settings menu (#4 finding 1). - **Tables:** `foundry_worlds` and `foundry_tokens`, one migration. - **nginx:** upgrade headers for `/api/foundry/ws`. - **Settings → Foundry (CAMP-16):** the code, the paired world (name, system, core version), the paired GMs, Unpair. Drawn on a prototype page first; IS-268–271 are replaced. ## Done when A GM installs the module from their server's manifest URL, pairs The Amberwake Accord on foundry-dev with a code, and Settings → Foundry shows the world. The owner can unpair it, which drops the socket. A player can't pair. The token never appears in logs or responses after the one `paired` message.

rbrooks added this to the v5.0.0 - Foundry: Connect & Push milestone

2026-06-23 00:42:31 +00:00

rbrooks added the

backend

enhancement

frontend

labels

2026-06-23 00:42:31 +00:00

rbrooks referenced this issue

2026-06-24 04:21:51 +00:00

[Foundry] Bidirectional integration — architecture & design reference #24

claude-bot referenced this issue

2026-07-15 22:02:32 +00:00

[Foundry] Decide & document connection topology: self-hosted relay vs direct URL, and the SSRF/URL-policy exemption #143

claude-bot referenced this issue

2026-07-15 22:03:27 +00:00

[Game Systems] Foundry alignment: one system identity + structured npc_to_actor #151

claude-bot referenced this issue

2026-07-27 23:15:00 +00:00

[Foundry] Test (D337): a minimal Quest Board module pairs and round-trips in The Amberwake Accord #4

claude-bot referenced this issue

2026-09-15 18:21:00 +00:00

[UX] Redesign coverage: where every shipped and planned feature lives in Design A #656

claude-bot referenced this issue

2026-09-23 21:05:10 +00:00

Build lane 11: stat blocks and character sheets (WIKI-19) #737

claude-bot referenced this issue

2026-09-23 21:05:12 +00:00

Build lane 3: the campaign core and Settings (CAMP-1 to CAMP-17, SH-7) #729

claude-bot referenced this issue

2026-09-30 06:42:19 +00:00

Character sheets phase 2: Foundry both ways, Pathbuilder in, conversion, Update to version n #958

claude-bot referenced this issue

2026-11-06 02:03:04 +00:00

[Design] Scenes become first-class and reusable across sessions, and pairable with a Foundry map #689

claude-bot referenced this issue

2026-11-06 02:06:11 +00:00

[Foundry] Decide & document connection topology: self-hosted relay vs direct URL, and the SSRF/URL-policy exemption #143

claude-bot referenced this issue

2026-11-06 02:10:15 +00:00

[Foundry] Decide & document connection topology: self-hosted relay vs direct URL, and the SSRF/URL-policy exemption #143

claude-bot referenced this issue

2026-11-07 00:41:54 +00:00

[Foundry] Test (D337): a minimal Quest Board module pairs and round-trips in The Amberwake Accord #4

rbrooks referenced this issue from a commit

2026-11-07 15:54:23 +00:00

docs: the Foundry connection's build contract (#5, #6)

claude-bot referenced this issue

2026-11-07 15:54:27 +00:00

[Foundry] Decide & document connection topology: self-hosted relay vs direct URL, and the SSRF/URL-policy exemption #143

claude-bot changed title from ~~[Foundry P1] Per-campaign Foundry connection settings (URL, encrypted API key, system selector)~~ to [Foundry P1] Pair a Foundry world: pairing codes, per-GM tokens, the Quest Board module served by each server (D333–D336)

2026-11-07 15:54:44 +00:00

rbrooks referenced this issue from a commit

2026-11-07 16:00:27 +00:00

Foundry module: GM-only connection form, indicator and link state machine (#5, #6)

rbrooks referenced this issue from a commit

2026-11-07 16:01:03 +00:00

design: Settings → Foundry redrawn for pairing a world (#5, #6)

rbrooks referenced this issue from a commit

2026-11-07 16:11:32 +00:00

wip: Foundry connection backend (#5, #6)

rbrooks referenced this issue from a commit

2026-11-07 16:11:32 +00:00

Foundry: token authority, scoped replacement, transport frame cap (#5, #6)

rbrooks referenced this issue from a commit

2026-11-07 16:16:01 +00:00

fix(webapp): a Foundry link needs a Gamemaster and the user it was paired for (#5)

rbrooks referenced this issue from a commit

2026-11-08 17:20:15 +00:00

Foundry: the approved wording for a non-Gamemaster (ac-018), and D342 (#5, #6)

rbrooks referenced this issue from a commit

2026-11-08 18:58:59 +00:00

feat(webapp): Settings -> Foundry section (#5, #6)

claude-bot referenced this issue

2026-11-08 20:41:51 +00:00

WIP: Foundry slice 1, pair a world and see its connection (#5, #6) #1368

claude-bot referenced this issue

2026-11-08 20:48:43 +00:00

[Foundry P2] pf2e npc_to_actor + "Send to Foundry" on NPC generation #9

rbrooks referenced this issue from a commit

2026-11-08 21:34:47 +00:00

fix(webapp): the Unpair confirm says what it does, and Remove sits at the row's end (#5)

rbrooks referenced this issue from a commit

2026-11-08 22:18:55 +00:00

test: the guards for the Foundry section and its tokens (#5)

rbrooks referenced this issue from a commit

2026-11-08 22:50:15 +00:00

fix(webapp): the Foundry socket gets its sessions from main.py (#5)

claude-bot referenced this issue

2026-11-09 18:18:18 +00:00

[Foundry P2] pf2e npc_to_actor + "Send to Foundry" on NPC generation #9

claude-bot commented

2026-11-09 23:30:32 +00:00

Collaborator

Live test on foundry-dev passed (2026-11-09, owner at the browser). Foundry 14.369, pf2e 8.7.0, The Amberwake Accord. The backend under test was the feat/9-foundry-push code: a throwaway on the qb-foundry-test endpoint, through int-proxy over wss://, with the D337 stand-in stopped for the test and restarted afterwards.

Check	Result
Pair as Ryan with a code; the GM-only "now paired" whisper; the marker	✅
A second GM (Test-GM) pairs from another Quest Board GM's code (Sam)	✅
One holder: Test-GM on "Waiting (held by Ryan)", handoff in 2–3 s when Ryan's window closed	✅
Player2: no settings entry, no marker, no connection (only two sockets ever opened)	✅
Send Brenna Hask: level 3 pf2e NPC with AC 18, HP 40, the attributes, Perception +9, speed 25	✅
Audience: public notes hold the summary and table text; private notes hold only the `:::gm` line	✅
Sent while the world was closed: queued (1 waiting), delivered the second a GM reopened, same actor, "updated" whisper	✅

Fixed during the test (on #1369):

HP on update: pf2e clamped the new value to the old max (40/45). Now full stays full and damage is kept; checked live at 50/50, then 30/55.
Speed in the notes: "Speed: 25 feet" was repeated in them.
Doubled message: "not paired" showed twice before a GM had paired.
Waiting form: a waiting GM's form said "not paired yet".
Marker: cut off ("Quest ..."); it's now its own row above Latency/FPS, reading "Quest Board: Connected", checked live.

Found, still to do: a manifest install from foundry-dev fails ("Fetch Failed"), because the foundry-dev container's Docker DNS can't resolve *.lan.ryanbrooks.dev (by IP it reaches int-proxy fine). For the test, the module was copied into Data/modules/quest-board with the owner's OK. The real fix is DNS for that container in iac-repo.

**Live test on foundry-dev passed (2026-11-09, owner at the browser).** Foundry 14.369, pf2e 8.7.0, The Amberwake Accord. The backend under test was the `feat/9-foundry-push` code: a throwaway on the `qb-foundry-test` endpoint, through int-proxy over `wss://`, with the D337 stand-in stopped for the test and restarted afterwards. | Check | Result | |---|---| | Pair as Ryan with a code; the GM-only "now paired" whisper; the marker | ✅ | | A second GM (Test-GM) pairs from another Quest Board GM's code (Sam) | ✅ | | One holder: Test-GM on "Waiting (held by Ryan)", handoff in 2–3 s when Ryan's window closed | ✅ | | Player2: no settings entry, no marker, no connection (only two sockets ever opened) | ✅ | | Send Brenna Hask: level 3 pf2e NPC with AC 18, HP 40, the attributes, Perception +9, speed 25 | ✅ | | Audience: public notes hold the summary and table text; private notes hold only the `:::gm` line | ✅ | | Sent while the world was closed: queued (1 waiting), delivered the second a GM reopened, same actor, "updated" whisper | ✅ | **Fixed during the test (on #1369):** 1. **HP on update:** pf2e clamped the new value to the old max (40/45). Now full stays full and damage is kept; checked live at 50/50, then 30/55. 2. **Speed in the notes:** "Speed: 25 feet" was repeated in them. 3. **Doubled message:** "not paired" showed twice before a GM had paired. 4. **Waiting form:** a waiting GM's form said "not paired yet". 5. **Marker:** cut off ("Quest ..."); it's now its own row above Latency/FPS, reading "Quest Board: Connected", checked live. **Found, still to do:** a manifest install from foundry-dev fails ("Fetch Failed"), because the `foundry-dev` container's Docker DNS can't resolve `*.lan.ryanbrooks.dev` (by IP it reaches int-proxy fine). For the test, the module was copied into `Data/modules/quest-board` with the owner's OK. The real fix is DNS for that container in iac-repo.

Rows
Columns

[Foundry P1] Pair a Foundry world: pairing codes, per-GM tokens, the Quest Board module served by each server (D333–D336) #5

Scope

Done when