coulomb-social/docs/migration/bubble-auth-and-export.md

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:

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:

~/.config/coulomb-social/auth/storage-state.json   # mode 0600

Probe (should not stay on bare / if login worked):

cd ~/coulomb-social/scripts
node ./probe-auth-session.mjs
# expect something like …/vw_pages or another app path

Then:

./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):

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):

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):

~/.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