# CyberHybridHub Runbook

This is a focused runbook for working safely in the current CyberHybridHub
codebase.

## 1. Architecture Snapshot

- Framework: Fresh 2 with Vite (`main.ts`)
- Server runtime: Deno
- Persistence: PostgreSQL + Drizzle (`db/schema.ts`, `db/db.ts`)
- Supplemental cache layer: `modules/KvCacheStore.ts`
- Authentication:
  - `/auth/login` starts OAuth flow
  - `/auth/callback` exchanges code, upserts user, stores tokens, sets cookies
  - `/auth/validate` refreshes token/session
- Authorization: `services/authMiddleware.ts` + `services/authRouteConfig.ts`

## 2. Critical Invariants

- Database search path must keep `public` first:
  `SET search_path TO public, memory, checkpoints`.
- OAuth callback must guarantee parent `users` row exists before writing to
  `user_tokens`.
- Concurrent session support depends on composite key `(user_id, state_id)` in
  `user_tokens`.
- Cookie sealing/unsealing must stay compatible with `state_keys` records.

If these drift, auth failures and FK errors are likely.

## 3. High-Risk Files

- `routes/auth/callback.ts`
- `routes/auth/validate.ts`
- `services/stateMiddleware.ts`
- `services/authMiddleware.ts`
- `db/db.ts`
- `db/sqlUserRepository.ts`
- `modules/KvCacheStore.ts`

## 4. Local Setup Checklist

1. Copy `.env.example` to `.env`.
2. Set `POSTGRES_OPTIONS`.
3. Set OAuth env vars (`AUTHORITY`, `CLIENT_ID`, `CLIENT_SECRET`,
   `REDIRECT_URI`, `TOKEN_URL`, `REDIRECT_HOME`).
4. Start app: `deno task dev`.

## 5. Verification Commands

Baseline quality:

```bash
deno task check
```

Auth callback regression:

```bash
deno task test:auth-callback-db
```

E2E suite:

```bash
deno task e2e
```

## 6. Troubleshooting

### FK error on token insert

Symptom:

- foreign key violation for `user_tokens_user_id_users_id_fk`

Checks:

1. Confirm callback still upserts/ensures user before token write.
2. Confirm writes target expected schema/tables.
3. Confirm `POSTGRES_OPTIONS` points to the intended database.
4. Restart server to avoid stale process code paths.

### Session appears invalid after login

Checks:

1. Verify `xx_state_id` and `session` cookies are both present.
2. Confirm `state_keys` row exists for the same state ID.
3. Ensure cookie hash/state key validation logic remains unchanged.

### Payments in local mode

- If `SANDBOX_MODE=true` or `DISABLE_EXTERNAL_APIS=true`, payment intent flow
  stays local and does not call Stripe.

### Islands disappear after load (production / Ubuntu server)

Symptom:

- Island components (e.g. WelcomeBar, GuestHome) render briefly then vanish when
  the app is run from a production build on another machine (e.g. Ubuntu).

Cause:

- Multiple copies of Preact end up in the bundle/cache. Hydration then fails and
  Preact can tear down the island DOM. Common when the server has a different or
  stale Deno cache than the machine that built the app.

Checks and fix:

1. On the **deployment server** (Ubuntu), force a clean dependency install
   before building:

   ```bash
   deno install -r --allow-scripts
   deno task build
   deno task start
   ```

2. Ensure the process **working directory is the project root** so that
   `_fresh/server.js` and `_fresh/static/` are found (e.g. in systemd set
   `WorkingDirectory=` to the app directory).

3. For reproducible builds across machines, consider re-enabling the lockfile in
   `deno.json` (`"lock": true`) and committing `deno.lock`, then using the same
   lock on the server.

4. Do not use `esm.sh` for Preact (this project already uses `npm:preact`);
   duplicate Preact from mixed sources is a common cause.

## 7. Change Discipline

- Keep docs and code aligned when behavior changes.
- Avoid adding temporary root-level feature summary markdown files.
- After auth/session/database changes, always run:
  - `deno task check`
  - `deno task test:auth-callback-db`