103 lines
2.6 KiB
Markdown
103 lines
2.6 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.
|
|
|
|
## 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`
|