138 lines
3.8 KiB
Markdown
138 lines
3.8 KiB
Markdown
# 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`
|