@binary1702/auth 0.2.4 → 0.3.0

package/README.md

@@ -1,14 +1,14 @@
 # @binary1702/auth
 
-Username + password auth for Next.js. Plug and play.
+Email + password auth for Next.js. Plug and play.
 
 ```bash
 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,15 +28,17 @@ 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:
-  Username: ben
+  Email: ben@example.com
   Password:
   Password again:
-  ✓ user "ben" created
+  ✓ user "ben@example.com" created
 
 Done. Start the dev server and open /auth/sign-in.
 ```
@@ -49,39 +51,142 @@ 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, username }
+  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". |
+| `/auth/sign-up` | The registration form. Closed unless `signup: open` (or `invite`) in `b17_auth.yaml`. See [Users](#users). |
+| `/auth/sign-out` | Not a page: clears the cookie and redirects to sign-in. 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. |
+
+**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 |
+| `POST /auth/sign-in` | `{ email, password }` | `200 { user }` + cookie, `401`, or `403 { verify: true }` |
+| `POST /auth/sign-up` | `{ email, password, invite? }` | `200 { user }` + 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):
+
+```tsx
+// app/layout.tsx (server): pass the session down, no extra request
+import { getSession } from "@binary1702/auth/next"
+import { AuthProvider } from "@binary1702/auth/react"
 
-const user = await getUser()   // { id, username } or null, never throws
+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, set a password, sign someone out everywhere, mark an email verified, remove a user; create an organization, add a member with a role, change a role, remove a member or an organization. Beside each membership it shows the permissions that role resolves to, so the two layers are visible side by side: the membership row says *who is what, where*; `b17_auth.yaml` says *what a role means*. The page never edits the yaml. 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.
+
+**Permissions** are the app's vocabulary, so they come from one env var: a JSON map from role to permissions. `"*"` means everything, `"invoices.*"` everything under that prefix.
+
+```
+AUTH_PERMISSIONS={"owner":["*"],"admin":["invoices.*"],"member":["invoices.view"]}
+```
+
+A role missing from the map has no permissions. An invalid value throws at the first session check, so a typo cannot silently lock everyone out.
 
 ---
 
@@ -92,23 +197,28 @@ Two ways in. Pick one or use both.
 **From the terminal** (always works):
 
 ```bash
-npx @binary1702/auth add-user           # prompts for username and password
-npx @binary1702/auth add-user gladys    # username given
-npx @binary1702/auth set-password ben
+npx @binary1702/auth add-user                                   # prompts for email and password
+npx @binary1702/auth add-user gladys@example.com                # email given
+npx @binary1702/auth set-password ben@example.com               # also signs them out everywhere
+npx @binary1702/auth remove-user ben@example.com                # delete; their sessions end too
+npx @binary1702/auth sign-out-everywhere ben@example.com        # end every session, keep the account
 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. |
+| `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: username 2 to 32 characters (letters, numbers, `. _ -`), 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.)
 
-Programmatic: `POST /auth/sign-up` as JSON `{ username, password, invite? }` returns `200 { user }` and the cookie, or `400 / 403 / 404 / 409` with `{ error }`.
+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 }`.
 
 ---
 
@@ -130,51 +240,162 @@ 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:                                       # role: what it may do. all = everything, x.* = a prefix
+  owner: all
+  admin: all
+  member: invoices.* reports.read
+
+organizations:                                     # overrides by organization name
+  Acme:
+    member: invoices.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` |
+| `email` | console in dev | see [Email](#email) |
+| `permissions`, `organizations` | none | see [The session contract](#the-session-contract) |
+
+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_PERMISSIONS` | JSON map of role → permissions for the [session contract](#the-session-contract) | 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
+```
 
-Both live in `.env.local`. Copy both to your host (Vercel, etc.) when you deploy.
+**Gmail API with a Google Workspace mailbox** (for example `verify@binary1702.com`):
+
+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`.
 
 ---
 
 ## 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, username, password_hash, created_at)   identity   one table, owned by the package
-scrypt                                                  proof      node:crypto, no dependency
-signed JWT in an httpOnly cookie, 7 days                session    stateless, zero DB reads per request
-proxy.ts                                                guard      verifies the cookie signature only
-/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)
-  ├─ /auth/sign-in    POST username+password → verify hash → set cookie → redirect
-  └─ your route       requireUser() → reads cookie → { id, username }
+  ├─ 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
+  ├─ /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 yaml
+                                   → { 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. `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.
 
-**Trade-off you should know.** The session is a signed token, not a database row. That is why the proxy costs nothing per request. The cost is that one session cannot be revoked before it expires. Change `AUTH_SECRET` to revoke all of them.
+**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.
 
 ---
 
@@ -185,10 +406,21 @@ Request
 | Export | |
 |---|---|
 | `GET`, `POST` | Route handlers. Mount at `app/auth/[...path]/route.ts`. |
-| `requireUser()` | `Promise<{ id, username }>`. Throws `AuthError` (status 401) if signed out. |
-| `getUser()` | `Promise<{ id, username } \| null>`. Never throws. |
-| `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`. |
 
 ### `@binary1702/auth/next/proxy`
 
@@ -205,7 +437,11 @@ 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 |
+| `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 |
 
@@ -216,14 +452,15 @@ 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", {
   method: "POST",
   headers: { "content-type": "application/json" },
-  body: JSON.stringify({ username, password }),
+  body: JSON.stringify({ email, password }),
 })   // 200 { user } or 401 { error }
 
 // sign out
@@ -236,7 +473,7 @@ Or just link to `/auth/sign-out`.
 
 ## Custom sign-in page
 
-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 `username` 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.
+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.
 
 ---