@binary1702/auth 0.3.0 → 0.4.0

package/AGENTS.md

@@ -9,7 +9,9 @@ cookie            auth_session: a signed token saying WHO (user id). Nothing els
 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
+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}
 ```
 
@@ -66,8 +68,8 @@ export async function POST(req: Request) {
 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.
+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`.**
 
@@ -77,6 +79,7 @@ export async function POST(req: Request) {
 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}
@@ -88,25 +91,37 @@ email:
     clientEmail: ${AUTH_GMAIL_CLIENT_EMAIL}
     privateKey: ${AUTH_GMAIL_PRIVATE_KEY}
 
-permissions:                           # role: what it may do
-  owner: all
+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
-
-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.
 
+## 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/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` |
+| `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.
 
@@ -131,7 +146,8 @@ npx @binary1702/auth list-orgs
 | 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 |
+| 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 |

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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.

package/PROMPT.md

@@ -207,7 +207,7 @@ export async function GET() {
 }
 ```
 
-Permissions are names the app chooses (`invoices.create`), mapped from roles in `b17_auth.yaml` under `permissions:`. `owner` has everything by default. Memberships come from the CLI (`add-org`, `add-member`). Do not invent a permission system in the app; use `requirePermission()`.
+Permissions are names the app chooses (`invoices.create`), declared with a label in `b17_auth.yaml` under `permissions:`. Which role holds which is set on `/auth/admin › Roles` and saved in the database (`roles:` in the yaml only seeds it once); `owner` always has everything. Memberships come from the CLI (`add-org`, `add-member`) or the admin page. Do not invent a permission system in the app; use `requirePermission()` on the server and `useAuth().can()` in the UI.
 
 **Server components (pages, layouts):**
 
@@ -256,7 +256,7 @@ Sign-out: a link to `/auth/sign-out`, or `fetch("/auth/sign-out", { method: "POS
 
 After the install, `node_modules/@binary1702/auth/AGENTS.md` is the reference for working in the app day to day.
 
-**Custom sign-in form (only if I ask for one):** a page under `/auth/` with a form that POSTs `email`, `password` and optionally `next` to `/auth/sign-in`. It must be served from the same site; cross-site POSTs get `403`.
+**Custom sign-in / sign-up page (only if I ask for one):** name it in `b17_auth.yaml` under `pages:` (`signIn: /sign-in`, `signUp: /sign-up`), then build an ordinary page at that path with `signIn()` / `signUp()` / `fetchPolicy()` from `@binary1702/auth/react`. Never under `/auth/`. The package then sends every signed-out visitor there and redirects `GET /auth/sign-in` to it. Details: README "Your own sign-in page" and `AGENTS.md`.
 
 ## Step 6: Settings
 
@@ -271,7 +271,8 @@ Only if I ask for them. All go in `b17_auth.yaml` (the CLI wrote it with comment
 | `requireVerified: true` | no session until the emailed link is clicked (needs email configured) |
 | `protected: /app/* /api/*` | only these need sign-in; everything else is open (default without it: everything needs sign-in, `public:` lists exceptions) |
 | `email:` | Gmail API or Resend; see the README's "Email" section. Keys stay in `.env.local`. |
-| `permissions:` / `organizations:` | role → permissions, and per-organization overrides |
+| `permissions:` | what the app gates, `id: label`: the rows of the Roles grid on `/auth/admin` |
+| `roles:` | role → permissions, the starting point written into the database once; the admin page decides after |
 
 Without `signup`, sign-up is closed, except while the user table is empty: then `/auth/sign-in` sends visitors to create the first account.
 

package/README.md

@@ -74,13 +74,14 @@ Two kinds of URL under `/auth/`. **Pages** are HTML you open in a browser; they
 
 | 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/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)**
 
@@ -88,8 +89,9 @@ Two kinds of URL under `/auth/`. **Pages** are HTML you open in a browser; they
 |---|---|---|
 | `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 }` |
+| `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 |
@@ -172,21 +174,24 @@ npx @binary1702/auth remove-member ben@binary1702.com Binary1702
 npx @binary1702/auth list-orgs
 ```
 
-**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:
+**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:
 
 ```yaml
 admins: ben@binary1702.com ops@binary1702.com
 ```
 
-An admin cannot remove or sign out the account they are using.
+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** 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.
+**Permissions** have three parts, each in one place:
 
 ```
-AUTH_PERMISSIONS={"owner":["*"],"admin":["invoices.*"],"member":["invoices.view"]}
+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
 ```
 
-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.
+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()`.
 
 ---
 
@@ -274,14 +279,15 @@ email:
     clientEmail: ${AUTH_GMAIL_CLIENT_EMAIL}
     privateKey: ${AUTH_GMAIL_PRIVATE_KEY}
 
-permissions:                                       # role: what it may do. all = everything, x.* = a prefix
-  owner: all
+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
-
-organizations:                                     # overrides by organization name
-  Acme:
-    member: invoices.read
 ```
 
 | Key | Default | |
@@ -294,8 +300,11 @@ organizations:                                     # overrides by organization n
 | `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`, `organizations` | none | see [The session contract](#the-session-contract) |
+| `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.
 
@@ -315,7 +324,7 @@ The format is a small subset of YAML: `key: value`, sections by indentation, `#`
 | `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_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 |
@@ -385,7 +394,7 @@ Request
   ├─ /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
+                                   → + active org + role → permissions from the roles table (set on /auth/admin)
                                    → { user, organization, authorization }
 ```
 
@@ -421,6 +430,10 @@ Request
 | `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`
 
@@ -440,6 +453,7 @@ For building your own handlers or using the primitives outside Next.
 | `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 |
@@ -471,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`.
 
 ---
 

package/dist/cli.js

@@ -309,6 +309,10 @@ signup: closed                                       # open | closed | invite  (
 # protected: /app/* /api/*                           # only these need sign-in; everything else is open. * = anything below
 #                                                    # (or the reverse: public: / /pricing  = everything needs sign-in except these)
 # admins: you@example.com                            # who may open /auth/admin (users, organizations, roles)
+# home: /app                                         # the signed-in home: after sign-in, and where a signed-in visitor to / goes
+# pages:                                             # your own sign-in / sign-up pages instead of the built-in ones;
+#   signIn: /sign-in                                 # they call signIn() / signUp() from @binary1702/auth/react
+#   signUp: /sign-up
 
 database: \${DATABASE_URL}
 secret: \${AUTH_SECRET}
@@ -331,14 +335,14 @@ ${gmail
   # resend:
   #   apiKey: \${AUTH_RESEND_API_KEY}`}
 
-permissions:                                          # role: what it may do. all = everything, x.* = a prefix
-  owner: all
+# permissions:                                       # what the app gates: id: label. The rows on /auth/admin › Roles
+#   invoices.read: See invoices
+#   invoices.create: Create invoices
+
+roles:                                                # role: what it may do to start with. all = everything, x.* = a prefix
+  owner: all                                          # (/auth/admin › Roles saves changes in the database)
   admin: all
   member:
-
-# organizations:                                      # overrides by organization name
-#   Acme:
-#     member: invoices.read
 `;
 }
 async function stepConfig() {
@@ -365,6 +369,17 @@ async function stepConfig() {
     writeFileSync(abs, configTemplate(readEnv()));
     done(`${CONFIG_FILE} written: app name, sign-up policy, email, permissions`);
 }
+/** The roles from b17_auth.yaml, written into the database once. A role the admin page already saved is left alone. */
+async function stepRoles() {
+    const { seedRoles } = await db();
+    const { options, resetOptions } = await import("./core/options.js");
+    resetOptions(); // the file may have been written a step ago
+    const written = await seedRoles(options().roles);
+    if (written.length)
+        done(`roles written to the database: ${written.join(", ")}  ${c.dim("(the starting point; /auth/admin › Roles decides from here)")}`);
+    else
+        skip("roles already in the database");
+}
 async function stepSchema() {
     const { ensureSchema, MIGRATIONS } = await db();
     await ensureSchema().catch((e) => fail(`Could not reach the database: ${e.message}`));
@@ -513,6 +528,7 @@ async function main() {
     stepFiles(appDir, src);
     await stepConfig();
     await stepSchema();
+    await stepRoles();
     await stepFirstUser();
     finish();
 }

package/dist/core/admin-html.d.ts

@@ -1,7 +1,7 @@
-import type { AdminOrg, AdminUser } from "./db.ts";
+import type { AdminOrg, AdminUser, StoredRole } from "./db.ts";
 import type { Options } from "./options.ts";
 export type AdminView = {
-    tab: "orgs" | "users" | "settings";
+    tab: "orgs" | "users" | "roles" | "settings";
 } | {
     tab: "org";
     orgId: string;
@@ -12,14 +12,20 @@ export type AdminPageData = {
     users: AdminUser[];
     orgs: AdminOrg[];
     roles: string[];
+    /** what the admin page saved for roles, all scopes */
+    stored: StoredRole[];
     options: Options;
     transport: string;
     tokens: {
         total: number;
         live: number;
     };
+    /** an organization's owner, not a system admin: only their organization is shown */
+    limited?: boolean;
     notice?: string;
     error?: string;
+    /** a one-time link (invite or verify) just issued, shown so the admin can hand it over */
+    link?: string;
     /** per-render, for the one script the page carries; must match the CSP header */
     nonce: string;
 };