# @cerebrus/backend

Express + TypeScript API (run by Bun) that owns **WorkOS AuthKit** authentication
and all database access via **Drizzle ORM** over **Supabase Postgres**.

The browser never talks to Supabase directly — `DATABASE_URL` lives only here.

## Setup

```bash
cp .env.example .env   # fill in the values below
bun install            # from the repo root
```

### Environment

| Var | Notes |
| --- | --- |
| `PORT` | Default `3001`. |
| `FRONTEND_URL` | Browser origin, used for CORS and the post-login redirect. |
| `WORKOS_API_KEY` / `WORKOS_CLIENT_ID` | From the [WorkOS dashboard](https://dashboard.workos.com). |
| `WORKOS_COOKIE_PASSWORD` | 32+ chars. `openssl rand -base64 32`. |
| `WORKOS_REDIRECT_URI` | Must also be registered as a Redirect URI in WorkOS (default `http://localhost:3001/auth/callback`). |
| `DATABASE_URL` | Supabase Postgres connection string (use the pooler URI). |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | From a [GitHub OAuth App](https://github.com/settings/developers). |
| `GITHUB_REDIRECT_URI` | Must equal the OAuth App's Authorization callback URL (default `http://localhost:3001/api/github/callback`). |
| `APP_ENCRYPTION_KEY` | Encrypts stored GitHub tokens at rest. `openssl rand -base64 32`. |

### GitHub OAuth App

Create one at GitHub → Settings → Developer settings → **OAuth Apps** → New OAuth App.
Set **Authorization callback URL** to `GITHUB_REDIRECT_URI`. Copy the client id and a
generated client secret into `.env`. The connection requests the `repo` scope so we
can list **private** repositories — note this grants broad repo access (an OAuth App
has no read-only private scope; use a GitHub App if you need least privilege).

Auth and DB are independent: the server boots with neither set and reports status
at `GET /health`. Each integration activates as soon as its vars are present.

## Run

```bash
bun run dev     # watch mode (also runs via `bun run dev` at the repo root, alongside the frontend)
bun run start   # one-off
```

## Database (Drizzle + Supabase)

```bash
bun run db:generate   # SQL migration from src/db/schema.ts -> src/db/migrations (offline)
bun run db:migrate    # apply migrations to DATABASE_URL
bun run db:push       # push schema directly (dev convenience)
```

## Routes

- `GET /health` — liveness + `{ authConfigured, dbConfigured }`.
- `GET /auth/login` — redirect to WorkOS AuthKit.
- `GET /auth/callback` — exchange code, set sealed-session cookie, upsert user.
- `GET /auth/me` — `{ user | null, configured }`.
- `GET /auth/logout` — clear cookie, redirect through WorkOS logout.
- `GET /api/me` — **protected**; WorkOS user + their Supabase row.
- `GET /api/github/status` — **protected**; `{ configured, connected, login }`.
- `GET /api/github/connect` — **protected**; start GitHub OAuth.
- `GET /api/github/callback` — store the encrypted token, redirect to the app.
- `GET /api/github/repos` — **protected**; the user's repos (public + private), each flagged `connected`.
- `POST /api/github/repos/connect` · `POST /api/github/repos/disconnect` — **protected**; toggle a project.
- `GET /api/github/projects` — **protected**; the user's connected repositories.