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:

```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  

## Targeted fresh first-use-case capture

For the nominated ReichelAg transfer, use explicit target mode after renewing
the session. This excludes August seed data, selects the space in the Pages
filter then applies Search, rejects expired signature cookies, and refuses
a one-page or body-incomplete target. A captured tree still needs reconciliation
against the latest expected protocol and private membership map before import.

```bash
COULOMB_SOCIAL_TARGET_SPACE_LABEL=ReichelAG node scripts/export-bubble-corpus.mjs
```

Set COULOMB_SOCIAL_CORPUS_DIR to a private directory if needed. Do not put raw
exports in the checkout. Default target route is /vw_pages; override via
COULOMB_SOCIAL_CAPTURE_ROUTE only after confirming the actual authenticated
protocol surface. A successful public-route load is not authentication proof.


## Retained Visual capture and review bundle

The October31 all-space bundle now has a separate private Visual preparation at
`~/.config/coulomb-social/auth/exports/visual-bundle-20261031`. The original
`review-bundle-20261031` remains unchanged.242Visual references were captured from
108URLs on the one recorded Bubble CDN, producing90distinct images.236draft
article pages and67space indexes link local hashed assets. All90images decode in
an offline browser; this is not a source/product appearance verdict or an import.

The reusable collector is `scripts/capture-bubble-visuals.py ORIGINAL --output NEW`.
It requires a complete hash-bound original bundle, a new private directory outside
repositories, and the exact known CDN over HTTPS. It refuses redirects, alternate
origins, credentials in URLs, active/unknown image formats, source drift, oversized
responses and existing output. No stored browser credentials are read or sent.
A missing final reconciliation.json means partial output, which must be retained
for review rather than used as an import bundle. Original body/date bytes are not
rewritten; only the compiler's empty Visual metadata is replaced.

Verification for the completed bundle (read-only):

```bash
python3 scripts/verify-bubble-visual-preservation.py \
  ~/.config/coulomb-social/auth/exports/review-bundle-20261031 \
  ~/.config/coulomb-social/auth/exports/visual-bundle-20261031
node scripts/verify-bubble-visuals.mjs \
  ~/.config/coulomb-social/auth/exports/visual-bundle-20261031
```

Only aggregate results belong in Git/chat. Images, titles, source URLs and original
records remain private. The new bundle retains all71spaces and the existing
graph/grant/fidelity gates.18body links and one attachment flag are still
unreconciled. Captured Visual bytes do not authorize copying memberships or
productive import. Public proof: docs/release/bubble-visual-preparation-2026-10-31.json.