From 416a0b20652ef1cf2550f10e246dd7615531dcd1 Mon Sep 17 00:00:00 2001 From: diubi Date: Sun, 8 Nov 2026 00:18:30 +0100 Subject: [PATCH 1/2] docs: add a contributing guide with the local stack setup CONTRIBUTING.md sets up Auth on its own with the dev personas, and connects it to a local backend and admin dashboard: resource identifiers, the backend's key pair, and the two applications to register. The local port is 3003, as `vp run dev` serves it, so the README and the env examples now say so too. Co-Authored-By: Claude Opus 5.5 --- .env.example | 2 +- .env.local.example | 2 +- CONTRIBUTING.md | 152 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 8 +-- 4 files changed, 158 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.env.example b/.env.example index eacf9cc..0a0f854 100644 --- a/.env.example +++ b/.env.example @@ -23,7 +23,7 @@ AUTH_CLIENT_IP_HEADER=cf-connecting-ip # Backend's IdP-signed access-change receiver; leave unset until it is deployed. # OAUTH_BACKEND_EVENTS_URL=http://backend-service.backend.svc:3000/internal/events -# For local development, override BETTER_AUTH_URL with http://localhost:3000 in .env.local. +# For local development, override BETTER_AUTH_URL with http://localhost:3003 in .env.local. # Enable a provider by setting all its credentials. Leave unused providers commented. # The PN app also reads Soci membership: grant Microsoft Graph application # GroupMember.Read.All and admin consent on this app registration. diff --git a/.env.local.example b/.env.local.example index 5d6ffb3..9f6be72 100644 --- a/.env.local.example +++ b/.env.local.example @@ -6,7 +6,7 @@ DB_USER=postgres DB_PASS=postgres DB_NAME=polinetwork_auth -BETTER_AUTH_URL=http://localhost:3000 +BETTER_AUTH_URL=http://localhost:3003 # Public on purpose: startup refuses this value anywhere but localhost. BETTER_AUTH_SECRET=local-development-only-secret-never-deploy-this diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..a8f1bc0 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,152 @@ +# Contributing to PoliNetwork Auth + +This guide gets a development environment ready for this repository, and then connects it to the +[backend](https://github.com/PoliNetworkOrg/backend) and the [admin dashboard](https://github.com/PoliNetworkOrg/admin) +so the three run together on your machine. The [README](README.md) explains how Auth works; read its +[Run locally](README.md#run-locally) section for the details behind the steps below. + +## Prerequisites + +- **Git**. +- **Docker** with Compose, for the local PostgreSQL database. +- **[Vite+](https://viteplus.dev/guide/)** (`vp`), which runs Node, pnpm and every project command here: + + ```sh + curl -fsSL https://vite.plus | bash + ``` + + Open a new shell afterwards. The pnpm version comes from `devEngines` in `package.json` and is downloaded when needed. + Production images use Node 22. + +## Set up Auth on its own + +```sh +git clone git@github.com:PoliNetworkOrg/auth.git +cd auth +vp install +cp .env.local.example .env.local +vp run dev:setup +vp run dev +``` + +- `vp run dev:setup` starts PostgreSQL with `compose.yaml` (on `localhost:55432`), applies the migrations and seeds four + test personas plus 60 fake people. It refuses to run against anything but a local database. +- `vp run dev` serves Auth on **http://localhost:3003**. Pick a persona under **Dev sign-in** on the login page: + **Ada Admin** is Master Admin and holds every permission. + +No provider credentials (Google, Microsoft, Telegram) are needed: the personas cover sign-in. To try a real provider, +copy its variables from `.env.example` into `.env.local`. + +## Everyday commands + +| Command | What it does | +| -------------------- | ----------------------------------------------------------------------------- | +| `vp run dev` | Development server on http://localhost:3003 | +| `vp run dev:db` | Starts the local database again, e.g. after a reboot | +| `vp run dev:seed` | Restores the personas and the fake people, updating them in place | +| `vp run db:generate` | Generates a Drizzle migration after a change to `src/db/schema.ts` | +| `vp run db:migrate` | Applies the migrations to the database in `.env.local` | +| `vp check` | Formatting, lint and type checks | +| `vp test` | Tests (integration suites are opt-in: see [Validation](README.md#validation)) | +| `vp run build` | Production build | + +Change the database only through migrations (`db:generate`, then `db:migrate`). `db:push` changes the schema without +recording a migration, so a later `db:migrate` fails on changes that already exist. + +## Connect the local stack + +The backend accepts only access tokens issued by Auth, and the admin dashboard signs people in through Auth. To work +on them with real data, run all three and register two applications in your local Auth. Do this once; the +[backend](https://github.com/PoliNetworkOrg/backend/blob/main/CONTRIBUTING.md) and +[admin](https://github.com/PoliNetworkOrg/admin/blob/main/CONTRIBUTING.md) guides link here. + +| Service | URL | Its own services (Docker) | +| ------- | --------------------- | ------------------------------------------------------- | +| Auth | http://localhost:3003 | PostgreSQL on 55432 | +| Backend | http://localhost:3000 | PostgreSQL on 55433, Redis on 56379 | +| Admin | http://localhost:3001 | Redis on 56380, for sessions only (never the backend's) | + +### 1. Turn on the backend resources in Auth + +Add to Auth's `.env.local`, then restart `vp run dev`: + +```sh +OAUTH_BACKEND_RESOURCE_URI=https://backend.internal.polinetwork.org +OAUTH_INTERNAL_RESOURCE_URI=https://localhost:3003/api/internal +``` + +These are identifiers (token audiences), not addresses: nothing is ever requested at them. Auth requires both, as +distinct HTTPS URLs, and the backend and the dashboard must use the same values. + +### 2. Generate the backend's key pair + +The backend proves who it is to Auth with a private key. Generate an Ed25519 pair: + +```sh +node -e 'const c=require("node:crypto");const{privateKey}=c.generateKeyPairSync("ed25519");const jwk={...privateKey.export({format:"jwk"}),kid:c.randomUUID(),alg:"EdDSA"};const{d,...pub}=jwk;console.log("OAUTH_BACKEND_PRIVATE_JWK=\x27"+JSON.stringify(jwk)+"\x27\n\nPublic JWKS to paste in Auth:\n"+JSON.stringify({keys:[pub]}))' +``` + +The first line goes into the backend's `.env`. Paste only the **public** JWKS into Auth: the private key never leaves +the backend. + +### 3. Register the backend + +Sign in as Ada Admin and open **Applications** → new application (`/applications/new`): + +1. **Basics**: any name, e.g. `Backend (local)`. +2. **Usage**: **Calls APIs as itself** only. +3. **Authentication**: **Private key**, and paste the public JWKS from step 2. +4. **Access**, under _PoliNetwork APIs it may call as itself_: `idp:access:read` (the access snapshot, required) and + `idp:people:roles` (only needed to change People roles). +5. Create it and copy its **client ID**. + +Put the client ID in Auth's `.env.local` and restart Auth: + +```sh +OAUTH_BACKEND_CLIENT_ID= +``` + +Then finish the backend's `.env` as described in the +[backend guide](https://github.com/PoliNetworkOrg/backend/blob/main/CONTRIBUTING.md#connect-it-to-auth), and start it. + +Optionally, let Auth notify the backend at once when access changes, instead of waiting for its 30-second poll: + +```sh +OAUTH_BACKEND_EVENTS_URL=http://localhost:3000/internal/events +``` + +### 4. Register the admin dashboard + +New application again: + +1. **Basics**: any name, e.g. `Admin Dashboard (local)`. +2. **Usage**: **Signs people in** only. +3. **Authentication**: **Client secret**. +4. **Access**: + - Redirect URI type: **Also localhost and app schemes**, because the dashboard runs on `http://localhost`. + - **Redirect URIs**: `http://localhost:3001/auth/callback` + - _What it may ask people for_: `openid`, `profile`, `email`, `offline_access` + - _PoliNetwork APIs it may call for them_: `backend:admin` + - **Post-logout redirect URIs**: `http://localhost:3001/login` +5. Create it, and copy the **client ID** and the **client secret**: the secret is shown only once. + +They go into the dashboard's `.env`, as described in the +[admin guide](https://github.com/PoliNetworkOrg/admin/blob/main/CONTRIBUTING.md#connect-it-to-auth). + +### 5. Check it works + +With all three running, open http://localhost:3001, sign in as Ada Admin and open a page with backend data, such as +the Telegram groups. If it fails, the backend log names the cause: a missing scope, an unknown client, or a snapshot +that could not be pulled. + +A persona can only see what its permissions allow, and a permission that does not exist in Auth is held by nobody, +not even Master Admin. If a dashboard page stays hidden for Ada Admin, check that its permission exists at +`/access/permissions`. + +## Pull requests + +- Run `vp check`, `vp test` and `vp run build` before pushing. +- Use [Conventional Commits](https://www.conventionalcommits.org) for commit messages and PR titles: + `type(scope): summary`, e.g. `feat(auth): …` or `fix(account): …`, with `!` after the scope for breaking changes. A + squash merge turns the PR title into the commit on `main`. +- A schema change ships with its generated migration in `drizzle/`. diff --git a/README.md b/README.md index 697bb9a..8f30b40 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,15 @@ A standalone TanStack Start and Better Auth identity provider. As of RFC v3 Phas ## Run locally -Use Node and pnpm through Vite+. +Use Node and pnpm through Vite+. [CONTRIBUTING.md](CONTRIBUTING.md) walks through the setup step by step, including how to run Auth together with the backend and the admin dashboard. The quickest way in needs only Docker and no provider credentials: 1. Run `vp install` and copy `.env.local.example` to `.env.local`. 2. Run `vp run dev:setup`. It starts PostgreSQL with `compose.yaml` (on `localhost:55432`), applies the migrations, and seeds four test personas plus 60 fake people. Run `vp run dev:seed` again whenever you want them back; it updates them in place. -3. Run `vp run dev`, open `http://localhost:3000`, and pick a persona under **Dev sign-in** on the login page. +3. Run `vp run dev`, open `http://localhost:3003`, and pick a persona under **Dev sign-in** on the login page. -The personas are Ada Admin (Master Admin, through `IDP_ADMIN_USER_IDS=dev-admin`), Sam Staff (a role with only `idp:users:read` and `idp:roles:read`), Stella Student (a verified Polimi student with Telegram linked) and Nico Newcomer (Google only, nothing else). Socio and Direttivo cannot be personas: they are always checked live against Entra, never trusted from the database. Scripts and agents can skip the page: opening `/api/dev/login?as=staff&redirect=/users` signs in and redirects, `/api/dev/login` alone lists the personas, and with curl `curl -c jar 'localhost:3000/api/dev/login?as=admin'` stores the session cookie. An OpenID Connect sign-in started from an application resumes after picking a persona. +The personas are Ada Admin (Master Admin, through `IDP_ADMIN_USER_IDS=dev-admin`), Sam Staff (a role with only `idp:users:read` and `idp:roles:read`), Stella Student (a verified Polimi student with Telegram linked) and Nico Newcomer (Google only, nothing else). Socio and Direttivo cannot be personas: they are always checked live against Entra, never trusted from the database. Scripts and agents can skip the page: opening `/api/dev/login?as=staff&redirect=/users` signs in and redirects, `/api/dev/login` alone lists the personas, and with curl `curl -c jar 'localhost:3003/api/dev/login?as=admin'` stores the session cookie. An OpenID Connect sign-in started from an application resumes after picking a persona. The dev sign-in exists only in `vp dev`. Production builds do not contain it, and `vp run build` fails if they ever do. It also stays off unless `.env.local` sets `DEV_LOGIN=1`, which startup refuses unless `BETTER_AUTH_URL` is localhost. Startup likewise refuses the public example secret from `.env.local.example` anywhere but localhost. @@ -22,7 +22,7 @@ To use your own database or real providers instead: 1. Run `vp install`. 2. Copy `.env.example` to `.env.local`, set a random secret, point `DB_*` at a **new, separate PostgreSQL database**, and configure an explicit admin group or `IDP_ADMIN_USER_IDS` bootstrap allowlist. -3. Set `BETTER_AUTH_URL=http://localhost:3000` for local development. +3. Set `BETTER_AUTH_URL=http://localhost:3003` for local development. 4. Run `vp run db:migrate` to apply the checked-in migration to that database. 5. Run `vp run dev` and open the origin set in `BETTER_AUTH_URL`. From e94cf59ef80fc4123a82ff634edda83af6942369 Mon Sep 17 00:00:00 2001 From: diubi Date: Mon, 16 Nov 2026 00:15:08 +0100 Subject: [PATCH 2/2] docs: point to the backend's stand-in for Auth Co-Authored-By: Claude Opus 5.5 --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8f1bc0..3430f76 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,6 +60,10 @@ on them with real data, run all three and register two applications in your loca [backend](https://github.com/PoliNetworkOrg/backend/blob/main/CONTRIBUTING.md) and [admin](https://github.com/PoliNetworkOrg/admin/blob/main/CONTRIBUTING.md) guides link here. +If you only work on the backend or the dashboard, the backend also has a stand-in for Auth with fixed accounts that +needs none of this: +[Or use the stand-in for Auth](https://github.com/PoliNetworkOrg/backend/blob/main/CONTRIBUTING.md#or-use-the-stand-in-for-auth). + | Service | URL | Its own services (Docker) | | ------- | --------------------- | ------------------------------------------------------- | | Auth | http://localhost:3003 | PostgreSQL on 55432 |