@binary1702/auth 0.2.5 → 0.4.0

package/README.md

@@ -6,9 +6,9 @@ Email + password auth for Next.js. Plug and play.
 npx @binary1702/auth
 ```
 
-One command. It installs itself, writes two env vars, writes two files, creates the table, creates your first user. Then you move on.
+One command. It installs itself, writes the secrets to `.env.local`, writes two files and a settings file, creates the tables, creates your first user. Then you move on.
 
-Letting an AI agent do the install? Paste [PROMPT.md](./PROMPT.md) into it. Same steps, written for an agent, with the checks to run and what to report back. [INSTALL.md](./INSTALL.md) is the short human version.
+Letting an AI agent do the install? Paste [PROMPT.md](./PROMPT.md) into it. Same steps, written for an agent, with the checks to run and what to report back. [INSTALL.md](./INSTALL.md) is the short human version. An agent working *inside* an app that already has it reads [AGENTS.md](./AGENTS.md).
 
 ---
 
@@ -20,7 +20,7 @@ cd my-app
 npx @binary1702/auth
 ```
 
-You will be asked for one thing: your Postgres connection string (Neon). Everything else is automatic.
+You will be asked for your Postgres connection string (Neon) and, optionally, how to send email (Enter to skip). Everything else is automatic.
 
 ```
 @binary1702/auth
@@ -28,9 +28,11 @@ You will be asked for one thing: your Postgres connection string (Neon). Everyth
   ✓ @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
+  ✓ b17_auth.yaml written: app name, sign-up policy, email, permissions
+  ✓ database schema ready (4 migrations)
 
   Create the first user:
   Email: ben@example.com
@@ -49,39 +51,147 @@ Run `npm run dev`, open the site, you are redirected to the sign-in page. Sign i
 
 ## Use it in your code
 
-Every page and API route is now behind sign-in. To know who the user is:
+Every page and API route is now behind sign-in. To know who is asking:
 
 ```ts
-import { requireUser } from "@binary1702/auth/next"
+import { getSession } from "@binary1702/auth/next"
 
 export async function GET() {
-  const user = await requireUser()   // { id, email }
+  const session = await getSession()   // { user, organization, authorization } or null
   // ...
 }
 ```
 
-That is the only line you ever write by hand.
+That is the only line you ever write by hand. `requireSession()` throws 401 instead of returning null, `requirePermission("invoices.create")` throws 403 when the role lacks it, and `getUser()` / `requireUser()` give just `{ id, email }`. All work in route handlers, server components, and server actions; `useAuth()` from `@binary1702/auth/react` gives the same object to client components. See [The session contract](#the-session-contract).
+
+---
+
+## What you get
+
+Two kinds of URL under `/auth/`. **Pages** are HTML you open in a browser; they carry forms, and the forms POST back to the same path. **API** calls are JSON for code.
+
+**Pages (open in a browser)**
+
+| URL | What you see |
+|---|---|
+| `/auth/sign-in` | The sign-in form. `?verify=1` shows "check your email" with a resend button; `?verified=1` shows "email verified". With `pages.signIn` in `b17_auth.yaml`, redirects to [your own page](#your-own-sign-in-page). |
+| `/auth/sign-up` | The registration form. Closed unless `signup: open` (or `invite`) in `b17_auth.yaml`. See [Users](#users). Same `pages.signUp` override. |
+| `/auth/sign-out` | Not a page: clears the cookie and redirects to sign-in, or to `?next=<same-origin path>` (`/auth/sign-out?next=/` lands on the public front). Link to it. |
+| `/auth/verify?token=…` | The link in the verification email. Marks the email verified and redirects. |
+| `/auth/forgot` | "Send me a reset link". Always answers the same, whether or not the address exists. |
+| `/auth/admin` | Users, organizations, roles: what the CLI does, as a page. Only for emails under `admins:` in `b17_auth.yaml`. |
+| `/auth/reset?token=…` | The link in the reset email. New password, then you are signed in; every older session of yours is ended. |
+| `/auth/invite?token=…` | The link an added user gets (admin page, "Add user" with no password): choose a password, which verifies the address, and you are signed in. Works once, seven days. |
+
+**API (JSON, for code)**
+
+| Call | Does | Answers |
+|---|---|---|
+| `GET /auth/session` | the [session contract](#the-session-contract) | `200 { user, organization, authorization }` or `401` |
+| `POST /auth/session` | switch the active organization `{ organization: "<id>" }` | the new contract, or `403` if not a member |
+| `GET /auth/policy` | what a sign-in / sign-up page needs before it renders | `200 { signup: { allowed, inviteRequired, reason }, pages, name }` |
+| `POST /auth/sign-in` | `{ email, password, next? }` | `200 { user, next }` + cookie, `401`, or `403 { verify: true }` |
+| `POST /auth/sign-up` | `{ email, password, invite?, next? }` | `200 { user, next }` + cookie, or `400 / 403 / 404 / 409 { error }` |
+| `POST /auth/sign-out` | clears the cookie | `200 { ok: true }` |
+| `POST /auth/verify/resend` | `{ email }`: emails a fresh verification link | `200 { ok: true }`, always |
+| `POST /auth/forgot` | `{ email }`: emails a reset link (1 h) if the address exists | `200 { ok: true }`, always |
+| `POST /auth/reset` | `{ token, password }` | `200 { user }` + cookie, or `400 { error }` |
+
+The same POST paths accept form posts too (that is what the pages do); a form post gets a redirect instead of JSON. Every POST refuses cross-site requests with `403`.
+
+Guessing is rate limited per fixed window, in the database so it holds across instances: sign-in 20 per IP and 10 per email every 15 minutes, sign-up 10 per IP an hour, reset and verification emails 3 per address an hour. Over the limit answers `429` with a `Retry-After` header (and the message on the form). The IP is the first `x-forwarded-for` entry, else `x-real-ip`, else "unknown", so behind a proxy that sets neither, every visitor shares one bucket.
+
+Everything else on the site requires a session. Unauthenticated page requests redirect to `/auth/sign-in?next=<where they were going>`. Unauthenticated `/api/*` requests get a `401` JSON response.
+
+---
+
+## The session contract
+
+One endpoint, one shape, three keys. The same object comes from `GET /auth/session` in the browser, `getSession()` on the server, and `useAuth()` in React.
+
+```json
+{
+  "user":          { "id": "4f1c…", "email": "ben@binary1702.com" },
+  "organization":  { "id": "9a2e…", "name": "Binary1702" },
+  "authorization": { "role": "admin", "permissions": ["invoices.view", "invoices.create"] }
+}
+```
+
+```
+user            who: from the cookie, checked against the database on every call
+organization    where: the user's active organization, or null if they are in none
+authorization   what: the role of their membership, and the permissions that role maps to
+```
+
+Signed out, revoked, or unverified while `AUTH_REQUIRE_VERIFIED` is on: the endpoint answers `401`, the helpers return `null`. The JSON is sent with `Cache-Control: no-store` and never contains the token.
+
+**Server** (route handlers, server components, server actions):
 
 ```ts
-import { getUser } from "@binary1702/auth/next"
+import { getSession, requireSession, requirePermission, unauthorized } from "@binary1702/auth/next"
+
+const session = await getSession()                        // contract or null
+const session = await requireSession()                    // contract or throws AuthError(401)
+const session = await requirePermission("invoices.create") // contract or throws AuthError(401 | 403)
+
+export async function POST() {
+  try {
+    const { user, organization } = await requirePermission("invoices.create")
+    // ...
+  } catch (e) {
+    return unauthorized(e)   // 401 or 403 JSON for AuthError, rethrows anything else
+  }
+}
+```
+
+`getUser()` / `requireUser()` still exist and return just the `user` part. All of them run the same check, so there is one place where "is this session good" is decided.
+
+**React** (rendering only; the server still checks every protected operation):
 
-const user = await getUser()   // { id, email } or null
+```tsx
+// app/layout.tsx (server): pass the session down, no extra request
+import { getSession } from "@binary1702/auth/next"
+import { AuthProvider } from "@binary1702/auth/react"
+
+export default async function Layout({ children }) {
+  return <AuthProvider session={await getSession()}>{children}</AuthProvider>
+}
+
+// any client component
+import { useAuth } from "@binary1702/auth/react"
+
+const { user, organization, authorization } = useAuth()
 ```
 
-Works in route handlers, server components, and server actions.
+Without a `session` prop, `<AuthProvider>` fetches `GET /auth/session` once on mount; `useAuth()` also gives `loading` and `refresh()`.
 
----
+**Organizations and roles** live in two tables the package owns, `orgs` and `members (org_id, user_id, role)`. A user can be in several; the session carries the *active* one: the one they last switched to, else the earliest membership. Switching is `POST /auth/session { organization }`, and the server checks the membership, so a client can never pick an organization it is not in.
 
-## What you get
+```bash
+npx @binary1702/auth add-org "Binary1702"
+npx @binary1702/auth add-member ben@binary1702.com Binary1702 admin    # role defaults to "member"
+npx @binary1702/auth remove-member ben@binary1702.com Binary1702
+npx @binary1702/auth list-orgs
+```
 
-| URL | What it does |
-|---|---|
-| `/auth/sign-in` | The sign-in page. Served by the package, no React, no styling work. |
-| `/auth/sign-up` | Self registration. Closed unless `AUTH_SIGNUP=open`. See [Users](#users). |
-| `/auth/sign-out` | Clears the session and sends you back to sign-in. Link to it. |
-| `/auth/session` | `{ user }` or `{ user: null }` as JSON, for client code. |
+**The admin page**, `/auth/admin`, does the same as those commands from the browser: add a user two ways, **Register** (email + password, ready and verified) or **Invite** (email only: a seven-day link to choose a password, which verifies the address and signs them in), set a password, sign someone out everywhere, mark an email verified or send the Invite link again, remove a user; create an organization, add a member with a role, change a role, remove a member or an organization. And it decides *what a role means*: the **Roles** tab is a grid, one row per permission the app declares, one checkbox per role, a Save button per role. Each organization's page carries the same grid for its own rule. Who may open it:
 
-Everything else on the site requires a session. Unauthenticated page requests redirect to `/auth/sign-in?next=<where they were going>`. Unauthenticated `/api/*` requests get a `401` JSON response.
+```yaml
+admins: ben@binary1702.com ops@binary1702.com
+```
+
+An admin cannot remove or sign out the account they are using. An organization's **owner** may open their own organization on the page (`/auth/admin?org=<id>`) and manage its roles and members, nothing else.
+
+**Permissions** have three parts, each in one place:
+
+```
+b17_auth.yaml  permissions:   what exists    id: label, the rows of the grid. The app's vocabulary.
+               roles:         the start      role → permissions, written into the database once
+roles table    /auth/admin    what's allowed  per role, for every organization or for one; most specific wins
+session JSON   authorization  the result     { role, permissions }, read by the app
+```
+
+Nothing saved for a role means it may do nothing. The `owner` role always holds everything and cannot be edited; so does any email under `admins:`. A saved role grants exactly its ticked boxes: a permission the app declares later starts off until someone ticks it. `"*"` means everything and `"invoices.*"` everything under that prefix, in the yaml's starting lists and in `hasPermission()`.
 
 ---
 
@@ -100,16 +210,18 @@ npx @binary1702/auth sign-out-everywhere ben@example.com        # end every sess
 npx @binary1702/auth list-users
 ```
 
-**Self sign-up at `/auth/sign-up`**, controlled by one env var:
+**Self sign-up at `/auth/sign-up`**, controlled by one key in `b17_auth.yaml`:
 
-| `.env.local` | Who can sign up |
+| `b17_auth.yaml` | Who can sign up |
 |---|---|
-| nothing set | Nobody. Except on a fresh install with zero users: `/auth/sign-in` sends you to create the first account. |
-| `AUTH_SIGNUP=open` | Anyone. The sign-in page gets a "Create one" link. |
-| `AUTH_SIGNUP=open` + `AUTH_INVITE_CODE=secret` | Anyone who knows the code. The form gets an invite field. |
-| `AUTH_EMAIL_DOMAIN=example.com` | Combine with any of the above: only `@example.com` emails can sign up. |
+| `signup: closed` (the default) | Nobody. Except on a fresh install with zero users: `/auth/sign-in` sends you to create the first account. |
+| `signup: open` | Anyone. The sign-in page gets a "Create one" link. |
+| `signup: invite` + `inviteCode: ${AUTH_INVITE_CODE}` | Anyone who knows the code (kept in `.env.local`). The form gets an invite field. |
+| `emailDomain: example.com` | Combine with either: only `@example.com` emails can sign up. |
 
-Rules on the form: a valid email address, password at least 8. Accounts are created and signed in immediately. Nothing to approve.
+(`AUTH_SIGNUP=open`, `AUTH_INVITE_CODE` and `AUTH_EMAIL_DOMAIN` as env vars still work and override the file.)
+
+Rules on the form: a valid email address, password 8 to 256 characters. Accounts are created and signed in immediately, and a verification link is emailed; with `requireVerified: true` the session waits for that link. Nothing to approve.
 
 Programmatic: `POST /auth/sign-up` as JSON `{ email, password, invite? }` returns `200 { user }` and the cookie, or `400 / 403 / 404 / 409` with `{ error }`.
 
@@ -133,24 +245,119 @@ import { proxy } from "@binary1702/auth/next/proxy"
 export default proxy
 
 export const config = {
-  matcher: ["/((?!auth|_next/static|_next/image|favicon.ico|.*\\..*).*)"],
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
 }
 ```
 
-The matcher is inline because Next reads it statically at build time and ignores a re-exported one.
+The matcher is inline because Next reads it statically at build time and ignores a re-exported one. It only skips Next's build output; the proxy itself lets through `/auth/*` and static files by extension (`.png`, `.css`, `.svg`, …), never anything under `/api/`.
+
+**Upgrading from 0.2.5 or earlier:** replace the matcher in your `proxy.ts` with the one above. The old one skipped any path starting with `auth` (`/authors`) and any path with a dot (`/api/export.csv`), so those were not guarded. Re-running `npx @binary1702/auth` detects the old matcher and tells you.
+
+Sign-in, sign-up and sign-out POSTs from another website are refused with `403` (checked via the browser's `Sec-Fetch-Site` / `Origin` headers), so no other site can sign your visitors in or out.
 
 If you already had a `proxy.ts`, the CLI leaves it alone and prints the snippet for you to merge.
 
 ---
 
+## b17_auth.yaml
+
+One file in the project root for everything the app decides. The CLI writes it on install; you edit it. Secrets never go in it: they stay in `.env.local` and appear here as `${NAME}` references.
+
+```yaml
+name: Binary1702                                   # page titles, email subjects
+signup: open                                       # open | closed | invite
+protected: /app/* /api/*                           # only these need sign-in; everything else is open. * = anything below
+
+database: ${DATABASE_URL}
+secret: ${AUTH_SECRET}
+
+email:
+  from: NoReply (Binary1702) <no-reply@binary1702.com>
+  replyTo: support@binary1702.com                  # optional
+  gmail:                                           # or resend: { apiKey: ${AUTH_RESEND_API_KEY} }
+    user: ben@binary1702.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. all = everything, x.* = a prefix
+  owner: all                                       # (then /auth/admin › Roles decides; owner always has everything)
+  admin: all
+  member: invoices.* reports.read
+```
+
+| Key | Default | |
+|---|---|---|
+| `name` | the request's host | shown in `<title>` and email subjects |
+| `signup` | `closed` | `invite` also needs `inviteCode: ${AUTH_INVITE_CODE}` |
+| `emailDomain` | any | only these addresses may sign up |
+| `requireVerified` | `false` | no session until the verification link is clicked |
+| `sessionDays` | `7` | cookie lifetime |
+| `protected` | none: everything guarded | only these paths need sign-in; the rest is open. `/x/*` covers `/x` and everything below |
+| `public` | none | the reverse: everything needs sign-in except these. Use one or the other. |
+| `admins` | none | emails that may open `/auth/admin` |
+| `pages` | the built-in pages | `signIn: /sign-in` and/or `signUp: /sign-up`: your own pages, see [Your own sign-in page](#your-own-sign-in-page) |
+| `home` | `/` | the signed-in home, e.g. `/app`: where sign-in lands when nothing says otherwise, the admin page's "app" link, and where a signed-in visitor opening `/` is sent (so `/` can be the public site) |
+| `email` | console in dev | see [Email](#email) |
+| `permissions` | none | what the app gates, `id: label`; see [The session contract](#the-session-contract) |
+| `roles` | `owner: all` | role → permissions, the starting point written into the database once; after that `/auth/admin › Roles` decides |
+
+The format is a small subset of YAML: `key: value`, sections by indentation, `#` comments. No arrays: a list is words separated by spaces. Mistakes are reported with the line number at startup.
+
+**How it resolves.** Built-in defaults, then the file, then env vars on top. `${NAME}` is replaced from the environment when the file is read; a missing variable is an error that names the key. The keys `database`, `secret`, `inviteCode`, `privateKey`, `clientSecret`, `refreshToken` and `apiKey` must be references: the CLI refuses a literal there unless the file is git-ignored. Without a file, the env vars below work exactly as they always did, so an existing install changes nothing.
+
+**`protected` and the proxy.** The matcher in `proxy.ts` is plumbing that says "run the guard on everything"; it never changes. The guard reads `protected:` (or `public:`) from this file and decides per request. With neither key, everything needs sign-in, as before. Next 16 runs the proxy in Node, so this just works. On Next 15, add `runtime: "nodejs"` to the `config` export in `middleware.ts` (and `experimental.nodeMiddleware: true` in `next.config`), since the edge runtime cannot read files.
+
+---
+
 ## Env vars
 
 | Var | What | Who sets it |
 |---|---|---|
 | `DATABASE_URL` | Postgres connection string | You, once, when the CLI asks |
 | `AUTH_SECRET` | Signs the session cookie | The CLI generates it |
+| `AUTH_GMAIL_USER` + `AUTH_GMAIL_CLIENT_EMAIL` + `AUTH_GMAIL_PRIVATE_KEY` | Send email through the Gmail API as that mailbox. See [Email](#email). | You, when the CLI asks. Skippable. |
+| `AUTH_RESEND_API_KEY` + `AUTH_EMAIL_FROM` | Or send through [Resend](https://resend.com) | Same prompt |
+| `AUTH_EMAIL_FROM` | With Gmail: optional display name, `Binary1702 <verify@binary1702.com>` | You, optional |
+| `AUTH_REQUIRE_VERIFIED` | `true`: no session until the email is verified. Default off. | You, optional |
+| `AUTH_ROLES` (or the older `AUTH_PERMISSIONS`) | JSON map of role → permissions, the starting point written into the database once (same as `roles:`) | You, optional |
+| `AUTH_SIGNUP`, `AUTH_INVITE_CODE`, `AUTH_EMAIL_DOMAIN` | Who may sign up. See [Users](#users). | You, optional |
+| `AUTH_PROTECTED` / `AUTH_PUBLIC` | Which paths need sign-in, space-separated. Same as the yaml keys. | You, optional |
+| `AUTH_ADMINS` | Emails that may open `/auth/admin` | You, optional |
+| `AUTH_EMAIL_REPLY_TO` | Reply-To on outgoing email | You, optional |
+| `AUTH_GMAIL_CLIENT_ID` + `AUTH_GMAIL_CLIENT_SECRET` + `AUTH_GMAIL_REFRESH_TOKEN` | Gmail through a personal account instead of a service account | You, optional |
+| `AUTH_CONFIG` | Path to the settings file when it is not `b17_auth.yaml` in the working directory | You, rarely |
+
+All live in `.env.local`. Copy them to your host (Vercel, etc.) when you deploy. With a `b17_auth.yaml`, only the secrets need to be env vars; the rest is in the file, and an env var set anyway overrides the file's value for that key.
+
+---
+
+## Email
+
+Verification links and password resets go out as email. One function sends them, over `fetch`, with no mail library. Which way it goes is decided by what is set:
+
+```
+AUTH_GMAIL_USER + AUTH_GMAIL_CLIENT_EMAIL + AUTH_GMAIL_PRIVATE_KEY   → Gmail API, as that mailbox
+AUTH_RESEND_API_KEY + AUTH_EMAIL_FROM            → Resend
+neither, in development                          → printed to the dev server's console (the links work)
+neither, in production                           → the first send throws; sign-in and sign-up keep working
+```
+
+**Gmail API with a Google Workspace mailbox** (for example `verify@binary1702.com`):
 
-Both live in `.env.local`. Copy both to your host (Vercel, etc.) when you deploy.
+1. In Google Cloud: create a project, enable the **Gmail API**, create a **service account**, and download its JSON key.
+2. In Google Admin → Security → API controls → **Domain-wide delegation**: add the service account's client id with the scope `https://www.googleapis.com/auth/gmail.send`.
+3. Run `npx @binary1702/auth`, answer `gmail`, give the mailbox and the path to the JSON key. The CLI writes `AUTH_GMAIL_USER`, `AUTH_GMAIL_CLIENT_EMAIL` and `AUTH_GMAIL_PRIVATE_KEY` (the PEM on one line, newlines as `\n`) to `.env.local`.
+
+No password or app password is involved: the package signs a short-lived assertion with the service account's key, trades it for a one-hour token at Google's token endpoint, caches the token in memory, and POSTs each message to the Gmail send endpoint. Sent mail shows up in that mailbox's Sent folder.
+
+**Gmail API with a personal Gmail account**: set `AUTH_GMAIL_USER`, `AUTH_GMAIL_CLIENT_ID`, `AUTH_GMAIL_CLIENT_SECRET` and `AUTH_GMAIL_REFRESH_TOKEN` (an OAuth client with the `gmail.send` scope, consented once). Same send path.
+
+**Resend**: an API key and a From address on a domain you have verified in Resend.
 
 Rotating `AUTH_SECRET` signs everyone out. That is the revoke-all button.
 For one user: `sign-out-everywhere`, `set-password` or `remove-user`.
@@ -159,31 +366,45 @@ For one user: `sign-out-everywhere`, `set-password` or `remove-user`.
 
 ## How it works
 
-Five primitives around one cookie. Nothing else.
+A few primitives around one cookie. Each is one file under `src/core/`, pure where it can be, with the Next handlers only wiring them.
 
 ```
-auth_users (id, email, password_hash, created_at,
-            session_epoch)                              identity   one table, owned by the package
-scrypt                                                  proof      node:crypto, no dependency
-signed JWT in an httpOnly cookie, 7 days, carries the
-  user's session_epoch                                  session    revoked when the epoch moves on
-proxy.ts                                                guard      verifies the cookie signature only
-getUser() / requireUser()                               gate       signature + one lookup by id
-/auth/sign-in  /auth/sign-out  /auth/session            lifecycle  one route file
+users (id, email, password_hash, session_epoch,
+            email_verified_at, active_org_id)            identity      owned by the package
+orgs, members (org_id, user_id, role)          where + role  a user may be in several; one is active
+tokens (user_id, kind, token_hash, expires_at,
+             used_at)                                    links         verify / reset; only the hash is stored
+rate_limits (bucket, count, reset_at)                    brakes        sign-in 20/IP and 10/email per 15 min, sign-up
+                                                                       10/IP/h, reset and resend emails 3/h → 429
+auth_migrations                                          schema        numbered steps, applied once on first start
+scrypt                                                   proof         node:crypto, no dependency
+signed JWT in an httpOnly cookie, carries the user's
+  session_epoch                                          session       says WHO; revoked when the epoch moves on
+proxy.ts                                                 guard         signature only, plus protected: / public: paths
+getSession() and friends                                 gate          signature + one query → the contract
+b17_auth.yaml                                            settings      name, sign-up, public, email, permissions
+sendEmail()                                              email         Gmail API or Resend, over fetch
+/auth/*                                                  lifecycle     one route file
 ```
 
 ```
 Request
-  ├─ proxy.ts         cookie valid? → continue   else → redirect (page) or 401 (api)
+  ├─ proxy.ts         open path, or cookie valid? → continue   else → redirect (page) or 401 (api)
   ├─ /auth/sign-in    POST email+password → verify hash → set cookie → redirect
-  └─ your route       requireUser() → reads cookie → user still exists, epoch matches? → { id, email }
+  ├─ /auth/sign-up    create user → email a verify link → set cookie (or wait for the link)
+  ├─ /auth/forgot     email a reset link → /auth/reset sets the password, bumps the epoch, signs in
+  └─ your route       getSession() → cookie → user exists, epoch matches, verified if required?
+                                   → + active org + role → permissions from the roles table (set on /auth/admin)
+                                   → { user, organization, authorization }
 ```
 
-**Authentication only.** The package tells you `user.id`. What that user may see or edit is your app's job. Keeping that boundary is what keeps this package small enough to never break.
+**Authentication, plus who-is-where.** The package tells you the user, their active organization and the role's permissions. What rows that role may touch is your app's query. Keeping that boundary is what keeps this package small enough to never break.
 
-**Two gates.** The proxy checks only the token's signature, so it costs nothing per request. `getUser()` / `requireUser()` also look the user up by id and compare the token's `session_epoch` with the database's. Deleting a user, changing their password or `sign-out-everywhere` moves the epoch on (or removes the row), and every older token stops working there. A revoked token still passes the proxy and can load a page, but it gets no user and no data: treat `null` / 401 as "go to `/auth/sign-out`", which clears the cookie and lands on sign-in.
+**Two gates.** The proxy checks only the token's signature, so it costs nothing per request. `getSession()` also looks the user up and compares the token's `session_epoch` with the database's. Deleting a user, changing their password (including by reset link) or `sign-out-everywhere` moves the epoch on (or removes the row), and every older token stops working there. A revoked token still passes the proxy and can load a page, but it gets no session and no data: treat `null` / 401 as "go to `/auth/sign-out`", which clears the cookie and lands on sign-in.
 
-Tokens signed before 0.2.5 carry no epoch and count as 0, so upgrading signs nobody out. The `session_epoch` column is added automatically on first start.
+**Hardening.** Every auth page is served with `Cache-Control: no-store`, `X-Frame-Options: DENY`, a `Content-Security-Policy` that allows no scripts (the admin page gets a per-request nonce for its one) and forms posting only to this origin. In production the cookie is `__Host-auth_session`: the browser refuses it unless Secure, path `/`, no domain, so a subdomain or a plain-http page cannot plant one. Passwords are scrypt with N=2^17 (about a third of a second per hash); rows hashed under older parameters are re-hashed on the next successful sign-in. The token carries `iss` and `aud`, so a token minted by another app that shares the secret is refused. The invite code is compared in constant time. Two sign-ups racing on one email: the database decides, the loser gets 409. Emails are unique case-insensitively.
+
+**Upgrading from 0.2.x:** nothing to do by hand. The cookie name changes in production but the old one is still read and cleared, tokens from before the 0.3.0 cutoff are accepted without the new claims, and old password hashes upgrade themselves at sign-in. Migrations run on first start, the new columns default to "not verified" and "no organization", tokens signed before keep working, and without a `b17_auth.yaml` the env vars behave as before. Run `npx @binary1702/auth` once to get the settings file written.
 
 ---
 
@@ -194,10 +415,25 @@ Tokens signed before 0.2.5 carry no epoch and count as 0, so upgrading signs nob
 | Export | |
 |---|---|
 | `GET`, `POST` | Route handlers. Mount at `app/auth/[...path]/route.ts`. |
-| `requireUser()` | `Promise<{ id, email }>`. Throws `AuthError` (status 401) if signed out, deleted or revoked. |
-| `getUser()` | `Promise<{ id, email } \| null>`. Null if signed out, deleted or revoked. One database lookup; throws only if the database is unreachable. |
-| `unauthorized(err)` | Turns an `AuthError` into a 401 JSON response. Rethrows anything else. |
-| `AuthError` | The error class. Has `.status = 401`. |
+| `getSession()` | `Promise<Session \| null>`. The [contract](#the-session-contract). Null if signed out, deleted, revoked or (when required) unverified. One database query. |
+| `requireSession()` | Same, or throws `AuthError` (401). |
+| `requirePermission(p)` | Same, or throws `AuthError` (401 signed out, 403 role lacks `p`). |
+| `getUser()` / `requireUser()` | Just the `user` part: `{ id, email }`. |
+| `unauthorized(err)` | Turns an `AuthError` into a 401/403 JSON response. Rethrows anything else. |
+| `AuthError` | The error class. Has `.status` (401 or 403). |
+| `Session`, `Organization`, `Authorization`, `User` | The types. |
+
+### `@binary1702/auth/react`
+
+| Export | |
+|---|---|
+| `AuthProvider` | `<AuthProvider session={…}>` with the server's `getSession()` result, or without a prop to fetch once on mount. |
+| `useAuth()` | `{ user, organization, authorization, loading, refresh }`. Nulls and an empty permission list when signed out. |
+| `fetchSession()` | `GET /auth/session` from the browser: `Session \| null`. |
+| `signIn({ email, password, next? })` | `POST /auth/sign-in` as JSON. `{ ok: true, user, next }` or `{ ok: false, status, error, verify, retryAfter? }`. For [your own sign-in page](#your-own-sign-in-page). |
+| `signUp({ email, password, invite?, next? })` | `POST /auth/sign-up`. Same result shape; `verify: true` with `ok` means "check your email". |
+| `signOut()` | `POST /auth/sign-out`. |
+| `fetchPolicy()` | `GET /auth/policy`: `{ signup: { allowed, inviteRequired, reason }, pages, name }`. |
 
 ### `@binary1702/auth/next/proxy`
 
@@ -214,7 +450,12 @@ For building your own handlers or using the primitives outside Next.
 |---|---|
 | `hashPassword(pw)`, `verifyPassword(pw, hash)` | scrypt |
 | `signSession(user, secret)`, `verifySession(token, secret)` | JWT HS256 |
-| `ensureSchema()`, `findUser()`, `createUser()`, `countUsers()`, `listUsers()`, `setPassword()` | Database |
+| `ensureSchema()`, `findUser()`, `createUser()`, `countUsers()`, `listUsers()`, `setPassword()`, `sessionRow()` | Users. Every function takes an optional `Db` as its last argument, so handler logic can run against a fake. |
+| `createOrg()`, `findOrg()`, `listOrgs()`, `addMember()`, `removeMember()`, `setActiveOrg()` | Organizations |
+| `buildSession()`, `hasPermission()`, `permissionsFor()` | The session contract, pure |
+| `storedRoles()`, `setRolePermissions()`, `resetRole()`, `seedRoles()`, `memberRole()` | The roles table: what each role may do, per scope |
+| `issueToken()`, `consumeToken()` | One-time tokens (`verify`, `reset`): only the SHA-256 is stored |
+| `sendEmail()` | Resend over `fetch`, console in development |
 | `signInPage({ error?, next?, title? })` | The HTML form as a string |
 | `COOKIE_NAME`, `SESSION_DAYS`, `SIGN_IN_PATH`, `SIGN_OUT_PATH` | Constants |
 
@@ -225,8 +466,9 @@ For building your own handlers or using the primitives outside Next.
 No client library. Plain HTTP.
 
 ```ts
-// who am I
-const { user } = await fetch("/auth/session").then((r) => r.json())
+// who am I, where am I, what may I do (401 when signed out)
+const res = await fetch("/auth/session")
+const { user, organization, authorization } = res.ok ? await res.json() : {}
 
 // sign in from a custom form
 await fetch("/auth/sign-in", {
@@ -243,9 +485,52 @@ Or just link to `/auth/sign-out`.
 
 ---
 
-## Custom sign-in page
+## Your own sign-in page
+
+The built-in pages are plain HTML with light and dark mode. To draw them in your app's design, name your pages in `b17_auth.yaml`:
+
+```yaml
+pages:
+  signIn: /sign-in
+  signUp: /sign-up        # either, or both
+```
+
+That moves the *page*, not the protocol. The package keeps deciding what is valid, who may sign up, where to go next and when to refuse; your page only renders.
+
+```
+pages.signIn set →  the proxy, sign-out, a verified email, "no account yet" all land on /sign-in
+                    GET /auth/sign-in?next=…  redirects to /sign-in?next=…  (old links keep working)
+                    /sign-in is always open, in both protected: and public: modes
+                    POST /auth/sign-in        unchanged: that is what your page calls
+```
+
+Your page is an ordinary route in the app (`app/sign-in/page.tsx`), built with the functions from `@binary1702/auth/react`:
+
+```tsx
+"use client"
+import { fetchPolicy, signIn, signUp } from "@binary1702/auth/react"
+
+const r = await signIn({ email, password, next })   // POST /auth/sign-in as JSON
+if (r.ok) location.assign(r.next)                   // next: checked by the server, same origin only
+else setError(r.error)                              // 401 wrong password, 429 too many tries, 403 verify your email
+
+const { signup, pages } = await fetchPolicy()       // GET /auth/policy
+// signup.allowed       may anyone sign up right now?            (sign-up page: show "closed" otherwise)
+// signup.inviteRequired ask for the invite code
+// signup.reason        "first": no users yet, this is the first account (sign-in page: send to pages.signUp)
+```
+
+What arrives on your page in the query, because the package redirected there:
+
+| Query | Means | Where from |
+|---|---|---|
+| `?next=/app/x` | where to go after sign-in; pass it to `signIn()` as is | the proxy |
+| `?error=1` | wrong email or password | a form POST to `/auth/sign-in` that failed (JSON callers get `401` instead) |
+| `?error=<text>` | the message | a form POST to `/auth/sign-up` that failed |
+| `?verify=1` | account created, email not verified yet | sign-up with `requireVerified` |
+| `?verified=1` | the verification link worked; sign in now | `/auth/verify` |
 
-The built-in page is plain HTML with light and dark mode. If you want your own, make any page with a form that POSTs `email` and `password` to `/auth/sign-in`, and put it anywhere under `/auth/` so the proxy lets it through. Optional hidden field `next` for where to go after.
+A form that POSTs `email`, `password` (and `next`, `invite`) to `/auth/sign-in` or `/auth/sign-up` works too; it gets redirects instead of JSON. Either way the request must come from your own site: cross-site POSTs get `403`. Forgot-password and reset stay the package's pages under `/auth/`; link to `/auth/forgot`.
 
 ---