Add safe Bubble session export path for CSOC-WP-0001-T02

Document XDG/OpenBao credential custody (no secrets in chat) and add Playwright inventory export using storage-state for automated read access.
2026-08-13 10:18:41 +02:00 · 2026-08-13 10:18:41 +02:00 · a160ad400b
commit a160ad400b
parent 638166cff4
5 changed files with 390 additions and 1 deletions
--- a/docs/migration/bubble-auth-and-export.md
+++ b/docs/migration/bubble-auth-and-export.md
@ -0,0 +1,127 @@
+# Bubble auth for automated export (CSOC-WP-0001-T02)
+
+## Do not put credentials in chat or git
+
+| Artefact | Where it belongs |
+|----------|------------------|
+| Email / password | Local `0600` files and/or OpenBao — **never** chat, PRs, workplans |
+| Playwright `storage-state.json` | `~/.config/coulomb-social/auth/` mode `0600` (gitignored) |
+| Export dumps | Local under auth dir or `docs/migration/samples/_local/` (gitignored) |
+
+Agents will **not** accept a password pasted into the conversation. That would
+land secrets in session logs.
+
+## What a member session can do
+
+With **your coulomb.social member** login, automation can:
+
+- Open authenticated Bubble routes (`/vw_pages`, `/vw_spaces`, …)
+- Capture HTML/text/screenshots for mapping
+- Intercept browser network calls (sometimes useful for JSON payloads)
+
+A **member** session usually **cannot**:
+
+- Full Bubble **editor** data-type field export
+- Admin “export all data” unless your account is an app admin with that power
+
+If you need full schema dumps, use Bubble editor as the same human, or grant
+editor access to a dedicated automation identity (still via OpenBao, not chat).
+
+## Path A — Interactive session (recommended if MFA/CAPTCHA)
+
+On the workstation:
+
+```bash
+cd ~/coulomb-social
+./scripts/capture-auth-state.sh
+```
+
+1. Browser opens `https://coulomb.social`.
+2. Log in as **you**.
+3. Open a real app surface (e.g. Research / Pages — not only the landing root).
+4. Press **Enter** in the terminal.
+
+Session file:
+
+```text
+~/.config/coulomb-social/auth/storage-state.json   # mode 0600
+```
+
+Probe (should **not** stay on bare `/` if login worked):
+
+```bash
+cd ~/coulomb-social/scripts
+node ./probe-auth-session.mjs
+# expect something like …/vw_pages or another app path
+```
+
+Then:
+
+```bash
+./scripts/export-bubble-session.sh
+```
+
+## Path B — Password files (only if no interactive MFA)
+
+You write secrets **yourself** on disk (agent never sees the values in chat):
+
+```bash
+AUTH="$HOME/.config/coulomb-social/auth"
+mkdir -p "$AUTH"
+chmod 700 "$AUTH"
+
+# Replace with your real values — run in your terminal only
+printf '%s' 'your@email.example' > "$AUTH/email"
+printf '%s' 'your-password-here'  > "$AUTH/password"
+chmod 600 "$AUTH/email" "$AUTH/password"
+
+cd ~/coulomb-social
+./scripts/capture-auth-state.sh --from-password-files
+# If Bubble shows MFA/CAPTCHA, fall back to Path A.
+```
+
+Optional OpenBao (when CCR/policy applied — see `docs/design-extract-auth.md`):
+
+```text
+tenants/binky/coulomb-social/bubble-member  →  EMAIL, PASSWORD
+```
+
+## Path C — Keep session warm for agents
+
+Once `storage-state.json` exists and probe looks authenticated:
+
+1. Tell the agent: *“Session is captured under the default XDG auth path; run export.”*
+2. Do **not** paste the file contents.
+3. Re-run `capture-auth-state.sh` when the session expires (probe lands on `/` only).
+
+Agents with local filesystem access can then run export without further human
+login **until cookies die**.
+
+## Export outputs
+
+Default dump directory (not for commit of raw HTML):
+
+```text
+~/.config/coulomb-social/auth/exports/YYYYMMDD-HHMMSS/
+  probe-url.txt
+  routes/
+  network/
+  SUMMARY.md
+```
+
+Redacted notes for the repo go under `docs/migration/` after review.
+
+## Security checklist
+
+- [ ] Secrets only in `~/.config/coulomb-social/auth/` (700/600)
+- [ ] No password in chat, Slack, or git
+- [ ] No `storage-state.json` committed (`.gitignore`)
+- [ ] Prefer a **dedicated** Bubble user with least privilege if this becomes long-lived automation
+- [ ] Rotate password if it was ever pasted into an unsafe channel
+
+## Related
+
+- `docs/design-extract-auth.md` — designlang / OpenBao detail  
+- `scripts/capture-auth-state.sh`  
+- `scripts/export-bubble-session.sh`  
+- CSOC-WP-0001-T02