integratedhub/CLAUDE.md

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:

deno task check

Auth callback regression:

deno task test:auth-callback-db

E2E suite:

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