68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
# @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.
|