@binary1702/auth 0.2.4 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,139 @@
+# 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, roles → permissions
+.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`). `all` grants everything, `invoices.*` everything under that prefix. Define them in `b17_auth.yaml` under `permissions:`; `owner` has everything unless the file says otherwise.
+6. **Do not build sign-in, sign-up, forgot-password or verification pages.** They exist under `/auth/`. Link to them.
+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
+
+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:                           # role: what it may do
+  owner: all
+  admin: invoices.* reports.*
+  member: invoices.read
+
+organizations:                         # per-organization overrides, by name
+  Acme:
+    member: invoices.read reports.read
+```
+
+No arrays: a list is words separated by spaces. Changes are picked up on the next request in development; restart in production.
+
+## 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/verify?token=`, `/auth/admin` | `GET /auth/session` → the shape or 401 |
+| `GET /auth/sign-out` clears the cookie | `POST /auth/session { organization }` switches the active organization (membership checked) |
+| | `POST /auth/sign-in`, `/auth/sign-up`, `/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 an owner | a `b17_auth.yaml` `permissions.owner` line that narrows it | remove the line; owner has everything by default |
+| `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,31 @@
+# Changelog
+
+## 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,53 +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, username } 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
+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`.