coulomb-social/docs/design-extract-auth.md

# Design extract — authenticated access to coulomb.social

designlang can crawl authenticated pages via Playwright cookies / storage state:

```text
npx designlang … --cookie-file <path>
```

Supported cookie file formats: JSON, Playwright `storageState`, Netscape `cookies.txt`.

## Threat model

| Artefact | Sensitivity | Where it lives |
|----------|-------------|----------------|
| Bubble member password | **High** — full account | OpenBao only (never Git/chat) |
| Browser `storageState` | **High** — session impersonation | Local XDG path, mode `0600`, gitignored |
| designlang output (tokens, screenshots) | Product UI — ok in repo after review | `docs/design-extract/` |

Do **not** paste passwords, cookies, or storage-state JSON into chat, workplans, or commits.

## Preferred flow (interactive session)

Bubble login may involve MFA, email codes, or CAPTCHA. Prefer a **human-attended** headed browser once, then reuse session state for extracts.

### 1. Capture session as your user

```bash
cd ~/coulomb-social
./scripts/capture-auth-state.sh
```

1. A Chromium window opens on `https://coulomb.social`.
2. Log in as **your** member account and navigate until you see the authenticated UI you care about.
3. Return to the terminal and press **Enter**.
4. Session is written to:

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

### 2. Run the extract

```bash
./scripts/run-design-extract.sh
# or with extra flags:
./scripts/run-design-extract.sh --depth 5 --full
```

Default output: `docs/design-extract/` (safe to commit after review; no secrets).

### 3. Refresh when the session expires

Re-run `./scripts/capture-auth-state.sh`. There is no long-lived cookie vault unless you complete the OpenBao lane below.

## OpenBao custody (password for re-login / automation)

Use when you need **unattended** re-auth (CI, agent loops) without a headed browser.

| Field | Value |
|-------|--------|
| Mount | `tenants` |
| Path | `tenants/binky/coulomb-social/bubble-member` |
| Fields | `EMAIL`, `PASSWORD` |
| Risk | `high` (member account) |
| Tenant | `binky` (Binky Hedgehog = client #1) |
| Workload | `coulomb-social` |
| Bundle | `bubble-member` |

This follows `ops-warden/wiki/playbooks/tenant-secret-onboarding.md`. **Status today:** path and fields are **declared** for this repo; the CCR, policy, OIDC role, and catalog entry are **not yet applied**. Until then, use interactive capture only.

### Founder provision (after CCR is applied)

```bash
# values only in mode-0600 files — never argv or chat
printf '%s' 'you@example.com' > /tmp/cs-email
printf '%s' '…' > /tmp/cs-pass
chmod 600 /tmp/cs-email /tmp/cs-pass

bao login -method=oidc -path=netkingdom   # admin / net-kingdom-admins as required
bao kv put tenants/binky/coulomb-social/bubble-member \
  EMAIL=@/tmp/cs-email \
  PASSWORD=@/tmp/cs-pass

shred -u /tmp/cs-email /tmp/cs-pass
```

### Worker fetch (never print)

```bash
bao login -method=oidc -path=netkingdom role=<lane>-workload-kv-read
bao kv get -field=EMAIL tenants/binky/coulomb-social/bubble-member > ~/.config/coulomb-social/auth/email
bao kv get -field=PASSWORD tenants/binky/coulomb-social/bubble-member > ~/.config/coulomb-social/auth/password
chmod 600 ~/.config/coulomb-social/auth/email ~/.config/coulomb-social/auth/password
```

Automated login-from-password is optional (`./scripts/capture-auth-state.sh --from-password-files`) and only works if bubble accepts simple email/password without interactive MFA.

## Routing (agents)

```bash
warden route find "coulomb.social bubble member login"
```

Until a catalog id exists, treat this as:

| Need | Owner |
|------|--------|
| Member password | OpenBao `tenants/binky/…` (founder provision) |
| Interactive session | You — `scripts/capture-auth-state.sh` |
| SSH / tunnels | ops-warden / ops-bridge (unrelated) |

**Anti-patterns:** message ops-warden for the password; commit `storage-state.json`; put `EMAIL`/`PASSWORD` in `.env` in the repo.

## designlang auth flags (reference)

**Important:** use the **main** `designlang <url>` command, not `designlang pack`.
The `pack` subcommand ignores `--cookie-file` and crawls anonymously.

```bash
# Prefer the wrapper (probes session, applies cookies, correct out dir):
./scripts/run-design-extract.sh

# Or manually:
npx designlang https://coulomb.social \
  --cookie-file ~/.config/coulomb-social/auth/storage-state.json \
  -o docs/design-extract \
  -n coulomb-social \
  --wait 5000 \
  --depth 2 \
  --interactions
```

Bubble reuses the same `coulomb_*` cookie **names** for guests and members.
A real member session is verified by landing on an app route (e.g. `/vw_pages`)
after load, not by cookie count.

Chrome extension path (optional): log in in desktop Chrome, use designlang’s extension for a one-click handoff if you prefer not to use Playwright capture.