@binary1702/auth 0.2.5 → 0.4.0

package/AGENTS.md

@@ -0,0 +1,155 @@
+# For agents working in an app that uses @binary1702/auth
+
+You are editing an application that already has `@binary1702/auth` installed (there is an `app/auth/[...path]/route.ts`, a `proxy.ts` and a `b17_auth.yaml`). This file tells you what the package gives you and the rules for using it. Installing it is a different document: `PROMPT.md`.
+
+## The model in one screen
+
+```
+cookie            auth_session: a signed token saying WHO (user id). Nothing else. Never read it yourself.
+proxy.ts          runs on every request: open path or valid cookie → continue, else → /auth/sign-in (401 for /api/*)
+getSession()      the real check, one query: user still exists, session not revoked, email verified if required
+                  → { user, organization, authorization } or null
+b17_auth.yaml     the app's choices: name, sign-up policy, which paths need sign-in, email, the permissions the app
+                  gates (permissions:) and the starting roles (roles:, written into the database once)
+roles table       what each role may do, as set on /auth/admin (Roles, or inside an organization). The database decides.
+.env.local        secrets only (DATABASE_URL, AUTH_SECRET, the email key); the yaml references them as ${NAME}
+```
+
+Three concepts, one JSON shape, everywhere:
+
+```json
+{
+  "user":          { "id": "4f1c…", "email": "ben@example.com" },
+  "organization":  { "id": "9a2e…", "name": "Acme" },
+  "authorization": { "role": "admin", "permissions": ["invoices.*", "reports.read"] }
+}
+```
+
+`organization` is `null` when the user is in none; then `role` is `null` and `permissions` is `[]`.
+
+## Reading the session
+
+| Where | Use | Returns |
+|---|---|---|
+| route handler, server component, server action | `await getSession()` | the shape above, or `null` |
+| same, when the caller must be signed in | `await requireSession()` | the shape, or throws `AuthError` (401) |
+| same, when a permission is required | `await requirePermission("invoices.create")` | the shape, or throws `AuthError` (401 signed out, 403 lacking it) |
+| only the user | `await getUser()` / `await requireUser()` | `{ id, email }` |
+| client component | `useAuth()` from `@binary1702/auth/react` | `{ user, organization, authorization, loading, refresh }` |
+| browser code without React | `GET /auth/session` | the shape, or `401` |
+
+All imports except the hook come from `@binary1702/auth/next`.
+
+**Route handler**
+
+```ts
+import { requirePermission, unauthorized } from "@binary1702/auth/next"
+
+export async function POST(req: Request) {
+  try {
+    const { user, organization } = await requirePermission("invoices.create")
+    // ... scope every query to organization.id and/or user.id ...
+    return Response.json({ ok: true })
+  } catch (e) {
+    return unauthorized(e)   // 401 or 403 JSON for AuthError, rethrows anything else
+  }
+}
+```
+
+**Page or layout** (server component): use `getSession()` and `redirect("/auth/sign-out")` when it is null. Do not use `requireSession()` in a page: it throws, which shows the error page instead of the sign-in page.
+
+**Server action**: call `requireSession()` or `requirePermission()` at the top of every action. Actions can be invoked directly; the page having checked means nothing.
+
+**Client component**: `useAuth()` needs an `<AuthProvider>` above it. The root layout normally has `<AuthProvider session={await getSession()}>`, so no request is made from the browser. Use it to show or hide UI only.
+
+## Rules
+
+1. **The server decides.** A greyed-out button is a hint. Every route handler and server action that reads or changes data calls `requireSession()` or `requirePermission()` itself.
+2. **Scope data by `organization.id`** (and `user.id` where it is personal). The package authenticates and tells you the role; what rows that role may touch is the app's query.
+3. **Never read or parse the `auth_session` cookie.** Never query the package's tables (`users`, `orgs`, `members`, `tokens`, `auth_migrations`) from app code. Users and memberships are managed with the CLI (below). Your own tables should use other names.
+4. **Never put a secret in `b17_auth.yaml`.** Secrets go in `.env.local`; the yaml references them as `${NAME}`. The CLI refuses a literal secret in the file.
+5. **Permission names are the app's vocabulary.** Pick `area.verb` names (`invoices.create`) and declare each with a label in `b17_auth.yaml` under `permissions:`; those are the rows on `/auth/admin › Roles`. Who holds which is decided there and saved in the database, never in code or in the yaml (`roles:` only seeds the database once). `owner` and the emails under `admins:` always hold everything. In the UI use `useAuth().can("invoices.create")` to show or hide; on the server `requirePermission()` is the check.
+6. **Do not build forgot-password or verification pages.** They exist under `/auth/`. Link to them. Sign-in and sign-up exist there too; build your own only when the app wants its own design, and then through `pages:` in `b17_auth.yaml` plus `signIn()` / `signUp()` / `fetchPolicy()` from `@binary1702/auth/react` (see "Your own sign-in page" below). Never a page that reads the cookie or checks a password itself.
+7. **Do not edit `proxy.ts`'s matcher.** Which paths need sign-in is `protected:` in `b17_auth.yaml` (`/x/*` covers `/x` and everything below); everything not listed is open. Without the key, everything is guarded, and `public:` lists exceptions instead. Never both.
+8. **Do not edit anything in `node_modules/@binary1702/auth`.**
+
+## b17_auth.yaml
+
+```yaml
+name: Acme Portal                      # page titles, email subjects
+signup: closed                         # open | closed | invite (needs inviteCode: ${AUTH_INVITE_CODE})
+protected: /app/* /api/*               # only these need sign-in; everything else is open
+home: /app                             # the signed-in home: sign-in lands here, a signed-in visitor to / is sent here
+
+database: ${DATABASE_URL}
+secret: ${AUTH_SECRET}
+
+email:
+  from: NoReply (Acme) <no-reply@acme.com>
+  gmail:                               # or resend: { apiKey: ${AUTH_RESEND_API_KEY} }
+    user: ops@acme.com
+    clientEmail: ${AUTH_GMAIL_CLIENT_EMAIL}
+    privateKey: ${AUTH_GMAIL_PRIVATE_KEY}
+
+permissions:                           # what the app gates: id: label (the rows on /auth/admin › Roles)
+  invoices.read: See invoices
+  invoices.create: Create invoices
+  reports.read: See reports
+
+roles:                                 # the starting point, written into the database once; /auth/admin decides after
+  owner: all                           # owner always holds everything
+  admin: invoices.* reports.*
+  member: invoices.read
+```
+
+No arrays: a list is words separated by spaces. Changes are picked up on the next request in development; restart in production.
+
+## Your own sign-in page
+
+```yaml
+pages:
+  signIn: /sign-in                     # the app's own page (either, or both)
+  signUp: /sign-up
+```
+
+With that, every redirect the package makes (the proxy, sign-out, a verified email, "create the first account") lands on the app's page, `GET /auth/sign-in` redirects there with the same query, and the page is always open. The protocol stays with the package: the page calls `signIn({ email, password, next })` / `signUp({ email, password, invite?, next })` from `@binary1702/auth/react` (JSON POSTs to `/auth/sign-in` and `/auth/sign-up`) and navigates to `r.next` on `ok`, or shows `r.error`. `fetchPolicy()` (`GET /auth/policy`) says whether sign-up is allowed, whether an invite code is needed, and whether this is the first account (`signup.reason === "first"`: the sign-in page should send the visitor to sign-up). The query the page may receive: `next`, `error` (`1` = wrong email or password, otherwise the message), `verify=1`, `verified=1`.
+
+## URLs the package serves
+
+| Pages (HTML, for a person) | API (JSON, for code) |
+|---|---|
+| `GET /auth/sign-in`, `/auth/sign-up`, `/auth/forgot`, `/auth/reset?token=`, `/auth/invite?token=`, `/auth/verify?token=`, `/auth/admin` | `GET /auth/session` → the shape or 401 |
+| `GET /auth/sign-out` clears the cookie, lands on `?next=` (same origin) or sign-in | `POST /auth/session { organization }` switches the active organization (membership checked) |
+| | `GET /auth/policy` → `{ signup, pages, name }` for an app's own sign-in / sign-up page |
+| | `POST /auth/sign-in`, `/auth/sign-up` (answer `{ user, next }` + cookie), `/auth/sign-out`, `/auth/forgot`, `/auth/reset`, `/auth/verify/resend` |
+
+Every POST refuses cross-site requests with 403.
+
+## Managing users and organizations (a page or the terminal, not code)
+
+`/auth/admin` does all of the below from the browser, for emails listed under `admins:` in `b17_auth.yaml`. It assigns roles; it never edits the yaml, where roles get their meaning.
+
+```bash
+npx @binary1702/auth add-user [email]
+npx @binary1702/auth set-password [email]             # also ends their sessions
+npx @binary1702/auth remove-user [email]
+npx @binary1702/auth sign-out-everywhere [email]
+npx @binary1702/auth list-users
+npx @binary1702/auth add-org <name>
+npx @binary1702/auth add-member <email> <org> [role]  # role defaults to "member"
+npx @binary1702/auth remove-member <email> <org>
+npx @binary1702/auth list-orgs
+```
+
+## When something is wrong
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `getSession()` is null but the user just signed in | password changed, `sign-out-everywhere`, or `requireVerified` is on and the email is not verified | sign out and in; or verify the email |
+| 403 from `requirePermission` for a role that should have it | the role's row in the database (Roles on /auth/admin, or the organization's own rule) does not tick that permission; a permission added to the yaml later starts off | tick it on /auth/admin; owner and admins always have everything |
+| `permissions: now lists what the app gates…` at startup | the yaml still has the pre-0.4.0 role map under `permissions:` | rename that section to `roles:`; declare the catalogue under `permissions:` |
+| `AUTH_SECRET is missing` / `DATABASE_URL is missing` | server started before `.env.local`, or the yaml references a name that is not set | check `.env.local`, restart |
+| `b17_auth.yaml line N: …` at startup | a syntax mistake in the file | the message says which line |
+| a page redirects to sign-in that should not | it matches `protected:` (or is not in `public:`); or Next 15 edge middleware cannot read the file | adjust the list; on Next 15 set `runtime: "nodejs"` in the middleware config |
+| emails print to the terminal instead of sending | no `email.gmail` / `email.resend` in the yaml | configure one; see README "Email" |
+| `429 Too many attempts` while testing sign-in | the rate limit: 10 wrong tries per email or 20 per IP in 15 minutes | wait for `Retry-After`, or test with another address |

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## Unreleased (0.4.0)
+
+### Added
+- `pages:` in `b17_auth.yaml` (`signIn: /sign-in`, `signUp: /sign-up`; env `AUTH_SIGN_IN_PAGE` / `AUTH_SIGN_UP_PAGE`): the app serves its own sign-in / sign-up page in its own design. Every redirect the package makes lands there, `GET /auth/sign-in` and `/auth/sign-up` redirect there with the same query, and the page is always open to the proxy. The POST protocol does not move.
+- `@binary1702/auth/react`: `signIn()`, `signUp()`, `signOut()`, `fetchPolicy()`, the protocol as functions for such a page, with one result shape (`AuthResult`).
+- `GET /auth/policy`: `{ signup: { allowed, inviteRequired, reason }, pages, name }`, what a sign-in / sign-up page needs before it renders.
+- `POST /auth/sign-in` and `/auth/sign-up` JSON answers carry `next`, the server-checked same-origin destination.
+- `home:` in `b17_auth.yaml` (env `AUTH_HOME`): the signed-in home. Sign-in lands there when nothing says otherwise, the admin page's "app" link points there, and the proxy sends a signed-in visitor who opens `/` there, so `/` can stay the public site. `GET /auth/policy` returns it as `home`.
+- `/auth/sign-out?next=<path>`: where to land after signing out (same origin), e.g. `?next=/` for the public front.
+- **Permissions are decided in the database, on /auth/admin.** A `roles` table (migration 8) holds what each role may do: for every organization (scope `""`) or for one organization (its id); the most specific rule wins, and nothing saved means nothing allowed. The session query joins it, so a change is live on the next request. `/auth/admin › Roles` is a grid: one row per permission the app declares, one checkbox per role, Save per role; each organization's page has the same grid for its own rule ("follows Roles" until saved). The `owner` role is fixed at everything and cannot be edited. An organization's owner may open their organization on /auth/admin and manage its roles and members; everything else stays with `admins:`.
+- `b17_auth.yaml`: `permissions:` now declares what the app gates (`id: label`, the grid's rows); `roles:` is the starting point, written into the database once (at install, or on first use) and restorable per role with "defaults". `organizations:` is gone (set an organization's own rule on its page). A file still holding the old role map under `permissions:` fails at startup with the fix spelled out. Env: `AUTH_ROLES` (JSON) replaces `AUTH_PERMISSIONS`, which still works.
+- `@binary1702/auth/react`: `useAuth().can(permission)` for showing and hiding UI.
+- Two ways to add a user on `/auth/admin`: **Register** (email + password: ready and verified) and **Invite** (email only: the account gets a random password and one link, `/auth/invite?token=…`, good once for seven days; the person chooses a password, which verifies the address, and is signed in). "invite" on an unverified user sends the link again. `invite` is a token kind; `POST /auth/invite` is the reset flow for it.
+- The admin page is honest about email: a banner on every tab when no transport is configured, and "email" / "invite" say the link was printed to the dev terminal rather than claiming a send. Either way the one-time link just issued is shown on the page with a copy button, so an admin can hand it over directly (only this site's own /auth/ links are ever shown; the query is not trusted).
+
+### Changed
+- `permissionsFor(role, stored)` and `buildSession(row, { admins })`: the yaml no longer takes part in the decision. An email under `admins:` holds every permission.
+
+## 0.3.0 (2026-10-22)
+
+Nothing to change by hand when upgrading from 0.2.x: migrations run on first start, the old cookie name is still read, tokens from before the cutoff are accepted, and password hashes upgrade themselves at sign-in. Run `npx @binary1702/auth` once to get `b17_auth.yaml` written.
+
+### Added
+- `b17_auth.yaml`: one settings file (name, sign-up policy, protected paths, admins, email, roles → permissions, per-organization overrides) with `${NAME}` references into `.env.local`. A dependency-free YAML subset. Secrets must be references; the CLI refuses a literal.
+- The session contract: `GET /auth/session` and `getSession()` return `{ user, organization, authorization }`; `requireSession()`, `requirePermission()`; `POST /auth/session` switches the active organization after a membership check.
+- Organizations and roles: `orgs`, `members (org_id, user_id, role)`; CLI `add-org`, `add-member`, `remove-member`, `list-orgs`.
+- `@binary1702/auth/react`: `AuthProvider` and `useAuth()`.
+- Email verification: verify links on sign-up, `/auth/verify`, `POST /auth/verify/resend`, `requireVerified`.
+- Password reset: `/auth/forgot`, `/auth/reset`.
+- Email over `fetch`: the Gmail API (service account with domain-wide delegation, or OAuth refresh token) or Resend; console in development.
+- One-time tokens (`tokens`): only the SHA-256 is stored; a link works once.
+- Rate limiting (`rate_limits`): sign-in 20 per IP and 10 per email per 15 min, sign-up 10 per IP an hour, reset and verification emails 3 per address an hour; `429` with `Retry-After`.
+- `/auth/admin`: users, organizations and roles from the browser, for emails under `admins:`.
+- `AGENTS.md` for agents working inside an app that has the package; `PROMPT.md` updated for the installer.
+
+### Changed
+- Tables are `users`, `orgs`, `members`, `tokens`, `rate_limits` and `auth_migrations`; a migration renames the old `auth_*` tables. A fresh install refuses a database whose `users` table is not the package's.
+- `GET /auth/session` answers `401` when signed out (was `200 { user: null }`).
+- scrypt N is 2^17 (was 2^14); rows re-hash at the next sign-in.
+- The session token carries `iss` and `aud`; tokens issued after 2026-10-22 without them are refused.
+- The production cookie is `__Host-auth_session`.
+- Every auth page is served with `Cache-Control: no-store`, `X-Frame-Options: DENY`, `Referrer-Policy: same-origin` and a no-script `Content-Security-Policy`.
+- Passwords are capped at 256 characters; the invite code is compared in constant time; emails are unique case-insensitively; a sign-up race ends in `409`.
+- Schema changes go through `auth_migrations`.
+
+## 0.2.5
+- Open redirect, unguarded paths and cross-site POSTs fixed; sessions revoked on user deletion or password change.

package/INSTALL.md

@@ -6,55 +6,66 @@ Inside a Next.js project (App Router):
 npx @binary1702/auth
 ```
 
-That is the whole install. It asks for your Postgres connection string once, then does everything else:
+That is the whole install. It asks for your Postgres connection string once, offers to set up email (Enter to skip), then does everything else:
 
 ```
 ✓ @binary1702/auth installed
 ✓ DATABASE_URL → .env.local
 ✓ AUTH_SECRET generated → .env.local
+· email not configured: dev prints emails to the console
 ✓ app/auth/[...path]/route.ts
 ✓ proxy.ts
-✓ auth_users table ready
-✓ user "ben" created
+✓ b17_auth.yaml written: app name, sign-up policy, email, permissions
+✓ database schema ready (4 migrations)
+✓ user "ben@example.com" created
 ```
 
 Safe to run again. It only does what is left.
 
 ## Use it
 
-Every page and API route is now behind sign-in. Get the user anywhere on the server:
+Every page and API route is now behind sign-in. Get the session anywhere on the server:
 
 ```ts
-import { requireUser } from "@binary1702/auth/next"
+import { getSession, requireSession, requirePermission } from "@binary1702/auth/next"
 
-const user = await requireUser()   // { id, email } or throws 401
+const session = await getSession()                         // { user, organization, authorization } or null
+const session = await requireSession()                     // same, or throws 401
+const session = await requirePermission("invoices.create") // same, or throws 401 / 403
 ```
 
+In React: `<AuthProvider session={await getSession()}>` in the root layout, then `useAuth()` in any client component.
+
+## The two files you edit
+
+**`b17_auth.yaml`** in the project root: app name, who may sign up, which paths need sign-in, email, roles → permissions. No secrets.
+
+**`.env.local`**: `DATABASE_URL`, `AUTH_SECRET`, and the email key. The yaml references them as `${NAME}`.
+
 ## URLs you get
 
 | URL | |
 |---|---|
 | `/auth/sign-in` | sign-in page |
+| `/auth/sign-up` | registration, when `signup:` allows it |
+| `/auth/forgot` | password reset by email |
 | `/auth/sign-out` | clears the session |
-| `/auth/session` | `{ user }` as JSON, for client code |
+| `/auth/session` | `{ user, organization, authorization }` as JSON, or 401 |
+| `/auth/admin` | users, organizations, roles, for emails under `admins:` in `b17_auth.yaml` |
 
 ## More users
 
-From the terminal:
-
 ```bash
 npx @binary1702/auth add-user
 npx @binary1702/auth set-password          # also ends their sessions
 npx @binary1702/auth remove-user
 npx @binary1702/auth sign-out-everywhere
 npx @binary1702/auth list-users
+npx @binary1702/auth add-org <name>
+npx @binary1702/auth add-member <email> <org> [role]
+npx @binary1702/auth list-orgs
 ```
 
-Or let people register themselves at `/auth/sign-up`. Add to `.env.local`:
-
-```
-AUTH_SIGNUP=open             # anyone can create an account
-AUTH_INVITE_CODE=secret      # optional: the form then asks for this code
-```
+Or let people register themselves: `signup: open` (or `invite`) in `b17_auth.yaml`. Without it, sign-up is closed, except on a fresh install with zero users, where `/auth/sign-in` takes you to create the first account.
 
-Without `AUTH_SIGNUP`, sign-up is closed. The one exception is a fresh install with zero users, where `/auth/sign-in` takes you to create the first account.
+Working in the app with an AI agent? Point it at `AGENTS.md`. Installing with one? `PROMPT.md`.