@binary1702/auth 0.3.0 → 0.4.0

package/dist/core/admin-html.js

@@ -2,19 +2,27 @@
 // The admin page. Plain HTML like the other auth pages.
 //
 //   ?tab=orgs (default)   organizations: name, members, roles in use → click one
-//   ?org=<id>             one organization: its roles → permissions, its members
+//   ?org=<id>             one organization: its members, and its own rule per
+//                         role (a grid of checkboxes; unset = follows Roles)
 //   ?tab=users            every user: verification, memberships, actions
+//   ?tab=roles            what each role may do in every organization without
+//                         its own rule: one checkbox per permission the app
+//                         declares (permissions: in b17_auth.yaml)
 //   ?tab=settings         the resolved settings, read-only
 //
+// An organization's owner sees only their organization (`limited`), and
+// only its roles grid and members.
+//
 // Every change is a small form that POSTs back and returns to the same
 // view. Nothing here decides anything; the handler and core/admin.ts
 // do. Every value goes through escape().
 // ─────────────────────────────────────────────────────────────
 import { escape } from "./html.js";
-import { ADMIN_PATH } from "./admin.js";
+import { ADMIN_PATH, checkedFor } from "./admin.js";
 import { SIGN_OUT_PATH } from "./config.js";
+import { landing } from "./pages.js";
 import { PASSWORD_MAX, PASSWORD_MIN } from "./signup.js";
-import { permissionsFor } from "./org.js";
+import { OWNER, permissionsFor } from "./org.js";
 const STYLE = `
   :root { color-scheme: light dark; --fg: #111; --bg: #fff; --line: #e3e3e3; --muted: #6b6b6b; --err: #c0392b; --ok: #1e8449; --panel: #f6f6f7; --accent: #2f7fd6; }
   @media (prefers-color-scheme: dark) { :root { --fg: #ececec; --bg: #121212; --line: #2c2c2c; --muted: #9a9a9a; --err: #ff6b6b; --ok: #58d68d; --panel: #1c1c1e; --accent: #6fb1ff; } }
@@ -43,17 +51,24 @@ const STYLE = `
   tr.row:hover td { background: color-mix(in srgb, var(--panel) 60%, var(--bg)); }
   code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
   .muted { color: var(--muted); }
+  .small { font-size: 12px; }
   .ok { color: var(--ok); }
   .warn { color: var(--err); }
   .right { text-align: right; white-space: nowrap; }
+  .center { text-align: center; }
   form.inline { display: inline-flex; gap: 4px; align-items: center; margin: 0 4px 0 0; }
   form.grid { display: grid; gap: 10px; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); align-items: end; }
   label { display: grid; gap: 3px; font-size: 12px; color: var(--muted); }
   input, select { font: inherit; font-size: 13px; padding: 6px 8px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); min-width: 0; }
+  input[type=checkbox] { width: 18px; height: 18px; padding: 0; accent-color: var(--fg); cursor: pointer; }
+  input[type=checkbox]:disabled { cursor: not-allowed; opacity: .6; }
   button { font: inherit; font-size: 12.5px; padding: 5px 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--fg); cursor: pointer; white-space: nowrap; }
   button.primary { background: var(--fg); color: var(--bg); border-color: var(--fg); }
   button.danger { color: var(--err); border-color: var(--err); }
   button.quiet { border-color: transparent; color: var(--muted); }
+  button.small { font-size: 11.5px; padding: 3px 8px; }
+  table.roles th.center, table.roles td.center { padding-left: 6px; padding-right: 6px; }
+  table.roles tfoot td { border-top: 2px solid var(--line); vertical-align: top; }
   .chip { display: inline-block; font-family: ui-monospace, Menlo, monospace; font-size: 11px; padding: 1px 7px; border: 1px solid var(--line); border-radius: 999px; margin: 1px 4px 1px 0; color: var(--muted); }
   .chip.all { color: var(--fg); border-color: var(--fg); }
   .pill { display: inline-block; font-size: 12px; padding: 1px 8px; border-radius: 999px; border: 1px solid var(--line); background: var(--panel); }
@@ -67,6 +82,8 @@ const STYLE = `
   button.quiet.danger { color: var(--err); }
   pre { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 10px; font-size: 12px; overflow: auto; margin: 8px 0 0; }
   .empty { color: var(--muted); font-size: 13px; padding: 6px 0; }
+  .link { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; margin: -6px 0 14px; padding: 8px 12px; border: 1px dashed var(--line); border-radius: 8px; }
+  .link code { word-break: break-all; }
 `;
 const hidden = (fields) => Object.entries(fields)
     .map(([k, v]) => `<input type="hidden" name="${escape(k)}" value="${escape(v)}">`)
@@ -78,10 +95,75 @@ const chips = (perms) => perms.length ? perms.map((p) => (p === "*" ? `<span cla
 export function adminPage(d) {
     const usersPath = `${ADMIN_PATH}/users`;
     const orgsPath = `${ADMIN_PATH}/orgs`;
+    const rolesPath = `${ADMIN_PATH}/roles`;
     const o = d.options;
     const tab = d.view.tab === "org" ? "orgs" : d.view.tab;
     const link = (t) => `${ADMIN_PATH}${t === "orgs" ? "" : `?tab=${t}`}`;
     const orgLink = (id) => `${ADMIN_PATH}?org=${escape(id)}`;
+    const catalogue = Object.entries(o.permissions);
+    const catalogueIds = catalogue.map(([id]) => id);
+    /** what was saved for a role: in this organization and for all of them */
+    const storedFor = (role, orgId) => ({
+        org: orgId ? (d.stored.find((s) => s.scope === orgId && s.name === role)?.permissions ?? null) : null,
+        all: d.stored.find((s) => s.scope === "" && s.name === role)?.permissions ?? null,
+    });
+    const effective = (role, orgId) => permissionsFor(role, storedFor(role, orgId));
+    /**
+     * The grid: rows are the catalogue, columns the roles, one form per role
+     * (outside the table; each checkbox names it through the `form`
+     * attribute). scope "" is the rule for every organization; an id is one
+     * organization's own rule. The owner column is fixed: everything.
+     */
+    const grid = (scope, inUse) => {
+        const formId = (r) => `role-${r.replace(/[^a-z0-9_-]/gi, "_")}`;
+        const own = (r) => (scope ? storedFor(r, scope).org : storedFor(r).all);
+        const forms = d.roles
+            .filter((r) => r !== OWNER)
+            .map((r) => `<form id="${formId(r)}" method="post" action="${rolesPath}">${hidden({ action: "set-permissions", role: r, scope, ...(scope ? { org: scope } : { tab: "roles" }) })}</form>`)
+            .join("");
+        const head = d.roles
+            .map((r) => {
+            const used = inUse.filter((x) => x === r).length;
+            const note = r === OWNER ? "everything, always" : scope ? (own(r) ? "own rule" : "follows Roles") : own(r) ? "saved" : "default";
+            return `<th class="center"><span class="pill">${escape(r)}</span><br><span class="muted small">${used} member${used === 1 ? "" : "s"} · ${note}</span></th>`;
+        })
+            .join("");
+        const rows = catalogue
+            .map(([id, label]) => {
+            const cells = d.roles
+                .map((r) => {
+                const on = checkedFor(effective(r, scope || undefined), [id]).length > 0;
+                const fixed = r === OWNER;
+                return `<td class="center"><input type="checkbox"${fixed ? "" : ` form="${formId(r)}"`} name="p:${escape(id)}" value="on"${on ? " checked" : ""}${fixed ? " disabled" : ""} aria-label="${escape(r)} may ${escape(label)}"></td>`;
+            })
+                .join("");
+            return `<tr class="row"><td><b>${escape(label)}</b><br><code class="muted">${escape(id)}</code></td>${cells}</tr>`;
+        })
+            .join("\n");
+        const foot = d.roles
+            .map((r) => {
+            if (r === OWNER)
+                return `<td class="center muted small">fixed</td>`;
+            const save = `<button type="submit" form="${formId(r)}" class="primary small">Save</button>`;
+            const back = scope
+                ? own(r)
+                    ? `<form class="inline" method="post" action="${rolesPath}">${hidden({ action: "follow", role: r, scope, org: scope })}<button type="submit" class="quiet small" title="drop this organization's own rule; follow Roles again">follow Roles</button></form>`
+                    : ""
+                : o.roles[r]
+                    ? `<form class="inline" method="post" action="${rolesPath}">${hidden({ action: "defaults", role: r, scope: "", tab: "roles" })}<button type="submit" class="quiet small" title="back to the starting point in b17_auth.yaml">defaults</button></form>`
+                    : "";
+            return `<td class="center">${save}${back ? `<br>${back}` : ""}</td>`;
+        })
+            .join("");
+        return `${forms}<table class="roles"><thead><tr><th>permission</th>${head}</tr></thead><tbody>${rows}</tbody><tfoot><tr><td class="muted small">A saved role grants exactly its ticked boxes; a permission the app adds later starts off until ticked.</td>${foot}</tr></tfoot></table>`;
+    };
+    const noCatalogue = `<p class="empty">Nothing to toggle yet: the app has not declared what it gates. In b17_auth.yaml, list each permission with a label:</p>
+<pre>permissions:
+  invoices.read: See invoices
+  invoices.create: Create invoices
+roles:
+  owner: all
+  member: invoices.read</pre>`;
     let body = "";
     // ── organizations ───────────────────────────────────────────
     if (d.view.tab === "orgs") {
@@ -113,35 +195,23 @@ ${d.orgs.length ? `<table><thead><tr><th>organization</th><th>members</th><th>ro
         const orgId = d.view.orgId;
         const org = d.orgs.find((x) => x.id === orgId);
         if (!org) {
-            body = `<p class="error">No such organization.</p><p><a href="${ADMIN_PATH}">← Organizations</a></p>`;
+            body = `<p class="error">No such organization.</p>${d.limited ? "" : `<p><a href="${ADMIN_PATH}">← Organizations</a></p>`}`;
         }
         else {
             const inUse = org.members.map((m) => m.role);
-            const roleRows = d.roles
-                .filter((r) => inUse.includes(r) || o.permissions[r] || o.organizations[org.name]?.[r])
-                .map((r) => {
-                const override = o.organizations[org.name]?.[r] !== undefined;
-                return `<tr class="row">
-  <td><span class="pill">${escape(r)}</span></td>
-  <td>${chips(permissionsFor(r, org.name, o))}</td>
-  <td class="muted">${override ? `organizations.${escape(org.name)}.${escape(r)}` : o.permissions[r] ? `permissions.${escape(r)}` : "not in b17_auth.yaml"}</td>
-  <td class="right">${inUse.filter((x) => x === r).length} member${inUse.filter((x) => x === r).length === 1 ? "" : "s"}</td>
-</tr>`;
-            })
-                .join("\n");
             const memberRows = org.members
                 .map((m) => `<tr class="row">
   <td><b>${escape(m.email)}</b>${m.email === d.self ? ' <span class="muted">(you)</span>' : ""}</td>
   <td><form class="inline" method="post" action="${orgsPath}">${hidden({ action: "set-role", org: org.id, email: m.email })}${roleSelect("role", d.roles, m.role)}<button type="submit" class="quiet">set</button></form></td>
-  <td>${chips(permissionsFor(m.role, org.name, o))}</td>
+  <td>${chips(effective(m.role, org.id))}</td>
   <td class="right"><form class="inline" method="post" action="${orgsPath}">${hidden({ action: "remove-member", org: org.id, email: m.email })}<button type="submit" class="danger">remove</button></form></td>
 </tr>`)
                 .join("\n");
             body = `
-<div class="crumb"><a href="${ADMIN_PATH}">Organizations</a> › <b>${escape(org.name)}</b> <code class="muted">${escape(org.id)}</code></div>
+<div class="crumb">${d.limited ? "" : `<a href="${ADMIN_PATH}">Organizations</a> › `}<b>${escape(org.name)}</b> <code class="muted">${escape(org.id)}</code></div>
 <div class="card">
-<h2>Roles in ${escape(org.name)} <span class="muted">· what each may do, from b17_auth.yaml</span></h2>
-${roleRows ? `<table><thead><tr><th>role</th><th>permissions</th><th>defined in</th><th class="right">used by</th></tr></thead><tbody>${roleRows}</tbody></table>` : '<p class="empty">No roles yet.</p>'}
+<h2>Roles in ${escape(org.name)} <span class="muted">· this organization's own rule per role; a column that follows Roles uses the rule for every organization</span></h2>
+${catalogue.length ? grid(org.id, inUse) : noCatalogue}
 </div>
 <div class="card">
 <h2>Members <span class="muted">(${org.members.length})</span></h2>
@@ -154,7 +224,7 @@ ${memberRows ? `<table><thead><tr><th>user</th><th>role</th><th>permissions here
   <button type="submit" class="primary">Add</button>
 </form>
 </div>
-<form class="inline" method="post" action="${orgsPath}" ${confirmRemove(org.name)}>${hidden({ action: "remove-org", org: org.id })}<button type="submit" class="danger">Remove ${escape(org.name)}</button></form>`;
+${d.limited ? "" : `<form class="inline" method="post" action="${orgsPath}" ${confirmRemove(org.name)}>${hidden({ action: "remove-org", org: org.id })}<button type="submit" class="danger">Remove ${escape(org.name)}</button></form>`}`;
         }
     }
     // ── users ───────────────────────────────────────────────────
@@ -169,7 +239,8 @@ ${memberRows ? `<table><thead><tr><th>user</th><th>role</th><th>permissions here
                 ? '<span class="ok">verified</span>'
                 : `<span class="warn">unverified</span>
     <form class="inline" method="post" action="${usersPath}">${hidden({ action: "send-verify", email: u.email, tab: "users" })}<button type="submit" class="quiet" title="send a verification email">email</button></form>
-    <form class="inline" method="post" action="${usersPath}">${hidden({ action: "verify", email: u.email, tab: "users" })}<button type="submit" class="quiet" title="mark verified without the email">mark</button></form>`;
+    <form class="inline" method="post" action="${usersPath}">${hidden({ action: "verify", email: u.email, tab: "users" })}<button type="submit" class="quiet" title="mark verified without the email">mark</button></form>
+    <form class="inline" method="post" action="${usersPath}">${hidden({ action: "invite", email: u.email, tab: "users" })}<button type="submit" class="quiet" title="email a link to choose a password (also verifies the address)">invite</button></form>`;
             return `<tr class="row">
   <td title="${escape(u.id)}"><b>${escape(u.email)}</b>${self ? ' <span class="muted">you</span>' : ""}${o.admins.includes(u.email) ? ' <span class="pill">admin</span>' : ""}</td>
   <td class="nowrap">${status}</td>
@@ -188,24 +259,34 @@ ${memberRows ? `<table><thead><tr><th>user</th><th>role</th><th>permissions here
 <div class="card">
 <h2>Users <span class="muted">(${d.users.length})</span></h2>
 <table><thead><tr><th>user</th><th>email</th><th>organizations</th><th></th></tr></thead><tbody>${rows}</tbody></table>
-<p class="empty">Permissions are per organization: open one under Organizations.</p>
+<p class="empty">What a role may do is under Roles, or inside an organization for its own rule.</p>
 </div>
 <div class="card panel">
 <form class="grid" method="post" action="${usersPath}">${hidden({ action: "add", tab: "users" })}
   <label>New user <input type="email" name="email" required autocomplete="off" placeholder="email"></label>
-  <label>Password <input type="password" name="password" minlength="${PASSWORD_MIN}" maxlength="${PASSWORD_MAX}" required autocomplete="new-password"></label>
-  <button type="submit" class="primary">Add user</button>
+  <label>Password <input type="password" name="password" minlength="${PASSWORD_MIN}" maxlength="${PASSWORD_MAX}" autocomplete="new-password" placeholder="for Register only"></label>
+  <button type="submit" name="mode" value="register" class="primary" title="email + password: the account is ready and verified">Register</button>
+  <button type="submit" name="mode" value="invite" title="email only: a seven-day link to choose a password, which verifies the address and signs them in">Invite</button>
 </form>
+<p class="muted small"><b>Register</b>: email + password, ready and verified now. <b>Invite</b>: email only; the person gets one link, good for seven days, to choose a password, which verifies the address and signs them in.</p>
 </div>`;
+    }
+    // ── roles ───────────────────────────────────────────────────
+    if (d.view.tab === "roles") {
+        const inUse = d.orgs.flatMap((org) => org.members.map((m) => m.role));
+        body = `
+<div class="card">
+<h2>Roles <span class="muted">· what each role may do in every organization without its own rule. Tick, then Save that column.</span></h2>
+${catalogue.length ? grid("", inUse) : noCatalogue}
+</div>
+<p class="empty">An organization can have its own rule per role: open it under Organizations. Owners and admins (${escape(o.admins.join(", ") || "none")}) hold everything regardless.</p>`;
     }
     // ── settings ────────────────────────────────────────────────
     if (d.view.tab === "settings") {
-        const permissionRows = Object.entries(o.permissions)
+        const catalogueRows = catalogue.map(([id, label]) => `  ${id}: ${label}`).join("\n");
+        const defaultRows = Object.entries(o.roles)
             .map(([role, perms]) => `  ${role}: ${perms.join(" ") || "(nothing)"}`)
             .join("\n");
-        const orgOverrides = Object.entries(o.organizations)
-            .map(([org, roles]) => `  ${org}:\n` + Object.entries(roles).map(([r, p]) => `    ${r}: ${p.join(" ") || "(nothing)"}`).join("\n"))
-            .join("\n");
         body = `
 <div class="card">
 <h2>Settings <span class="muted">· read-only, from b17_auth.yaml and .env.local</span></h2>
@@ -215,12 +296,16 @@ ${memberRows ? `<table><thead><tr><th>user</th><th>role</th><th>permissions here
 <tr><td>requireVerified</td><td>${o.requireVerified}</td></tr>
 <tr><td>sessionDays</td><td>${o.sessionDays}</td></tr>
 <tr><td>${o.protected.length ? "protected" : "public"}</td><td>${escape((o.protected.length ? o.protected : o.public).join(" ") || "(everything needs sign-in)")}</td></tr>
+<tr><td>home</td><td>${escape(landing(null, o.home))}</td></tr>
 <tr><td>admins</td><td>${escape(o.admins.join(" "))}</td></tr>
 <tr><td>email</td><td>${escape(d.transport)}${o.email.from ? ` · from ${escape(o.email.from)}` : ""}${o.email.replyTo ? ` · reply-to ${escape(o.email.replyTo)}` : ""}</td></tr>
 <tr><td>tokens</td><td>${d.tokens.total} issued · ${d.tokens.live} still usable</td></tr>
 </tbody></table>
-<pre>permissions:
-${escape(permissionRows) || "  (none)"}${orgOverrides ? `\norganizations:\n${escape(orgOverrides)}` : ""}</pre>
+<pre>permissions:                 # what the app gates
+${escape(catalogueRows) || "  (none declared)"}
+roles:                       # the starting point, written to the database once
+${escape(defaultRows) || "  (none)"}</pre>
+<p class="muted small">What a role may do today is under <a href="${link("roles")}">Roles</a>; the database decides, this file only seeds it.</p>
 </div>`;
     }
     return `<!doctype html>
@@ -233,19 +318,32 @@ ${escape(permissionRows) || "  (none)"}${orgOverrides ? `\norganizations:\n${esc
 </head>
 <body>
 <main>
-<div class="top"><h1>${escape(o.name || "Auth")} admin</h1><a href="/">app</a><a href="${SIGN_OUT_PATH}">sign out</a><span class="who">${escape(d.self)}</span></div>
-<nav class="tabs">
+<div class="top"><h1>${escape(o.name || "Auth")} admin</h1><a href="${escape(landing(null, o.home))}">app</a><a href="${SIGN_OUT_PATH}">sign out</a><span class="who">${escape(d.self)}</span></div>
+${d.limited
+        ? ""
+        : `<nav class="tabs">
   <a href="${link("orgs")}" class="${tab === "orgs" ? "on" : ""}">Organizations</a>
   <a href="${link("users")}" class="${tab === "users" ? "on" : ""}">Users</a>
+  <a href="${link("roles")}" class="${tab === "roles" ? "on" : ""}">Roles</a>
   <a href="${link("settings")}" class="${tab === "settings" ? "on" : ""}">Settings</a>
-</nav>
-${d.notice ? `<p class="notice">${escape(d.notice)}</p>` : ""}${d.error ? `<p class="error">${escape(d.error)}</p>` : ""}
+</nav>`}
+${d.transport === "console"
+        ? `<p class="error">Email is not set up: verification and password-reset links are printed to the dev server's terminal, not sent. Add <code>email:</code> (gmail or resend) to b17_auth.yaml, with the secrets in .env.local.</p>`
+        : d.transport === "none"
+            ? `<p class="error">Email is not set up: in production, verification and password-reset emails fail until <code>email:</code> (gmail or resend) is configured in b17_auth.yaml.</p>`
+            : ""}
+${d.notice ? `<p class="notice">${escape(d.notice)}</p>` : ""}
+${d.error ? `<p class="error">${escape(d.error)}</p>` : ""}
+${d.link ? `<p class="link"><code>${escape(d.link)}</code> <button type="button" class="small" data-copy="${escape(d.link)}">copy</button> <span class="muted small">works once; the next "invite" or "email" issues a new one</span></p>` : ""}
 ${body}
 </main>
 <script nonce="${escape(d.nonce)}">
 for (const f of document.querySelectorAll("form[data-confirm]")) {
   f.addEventListener("submit", (e) => { if (!confirm(f.dataset.confirm)) e.preventDefault() })
 }
+for (const b of document.querySelectorAll("button[data-copy]")) {
+  b.addEventListener("click", () => navigator.clipboard.writeText(b.dataset.copy).then(() => { b.textContent = "copied" }))
+}
 </script>
 </body>
 </html>`;

package/dist/core/admin.d.ts

@@ -1,13 +1,31 @@
-import type { Session } from "./org.ts";
+import { type Session } from "./org.ts";
 export declare const ADMIN_PATH = "/auth/admin";
 export declare function isAdmin(session: Pick<Session, "user"> | null, admins: readonly string[]): boolean;
+/**
+ * Who may change what a role may do, per scope. Pure.
+ *   every organization (scope "")   a system admin (admins: in the yaml)
+ *   one organization (its id)       a system admin, or that organization's owner
+ * The owner role itself is never editable: it holds everything.
+ */
+export declare function mayEditRoles(admin: boolean, scope: string, roleInScope: string | null): boolean;
 /** The forms on the page. Each is one POST with `action` and a few fields. */
-export declare const USER_ACTIONS: readonly ["add", "set-password", "sign-out", "verify", "send-verify", "remove"];
+/**
+ * add: two flows by the button pressed (`mode`): Register (email + password, ready and verified)
+ *      or Invite (email only; a seven-day link to set a password, which verifies and signs in)
+ * invite: send the Invite link again to an existing user
+ */
+export declare const USER_ACTIONS: readonly ["add", "invite", "set-password", "sign-out", "verify", "send-verify", "remove"];
 export declare const ORG_ACTIONS: readonly ["create", "add-member", "set-role", "remove-member", "remove-org"];
+/** set-permissions: save the ticked boxes · defaults: back to the yaml starting point (scope "") · follow: drop an organization's own rule (scope id) */
+export declare const ROLE_ACTIONS: readonly ["set-permissions", "defaults", "follow"];
 export type UserAction = (typeof USER_ACTIONS)[number];
 export type OrgAction = (typeof ORG_ACTIONS)[number];
+export type RoleAction = (typeof ROLE_ACTIONS)[number];
 export declare const isUserAction: (a: string) => a is UserAction;
 export declare const isOrgAction: (a: string) => a is OrgAction;
+export declare const isRoleAction: (a: string) => a is RoleAction;
+/** A role is one word: letters, digits, - or _ */
+export declare const ROLE_NAME: RegExp;
 /**
  * What an admin may not do to themselves: remove or lock out the account
  * they are using. (Their own password change is fine: it ends their other
@@ -15,12 +33,24 @@ export declare const isOrgAction: (a: string) => a is OrgAction;
  */
 export declare function refusedOnSelf(action: UserAction, targetEmail: string, selfEmail: string): string | null;
 /**
- * Where to land after an action: the view the form was on. Only two shapes
- * exist, so the value is rebuilt from parts, never taken from the form as is.
+ * Where to land after an action: the view the form was on. Only a few
+ * shapes exist, so the value is rebuilt from parts, never taken from the form as is.
  */
 export declare function backTo(fields: {
     org?: string;
     tab?: string;
 }): string;
-/** Roles the page offers in its dropdowns: whatever the yaml defines, plus any role already in use. */
+/** Roles the page offers in its dropdowns: whatever is defined or saved, plus any role already in use. Owner first. */
 export declare function roleChoices(defined: readonly string[], inUse: readonly string[]): string[];
+/**
+ * The Roles grid: one checkbox per catalogue entry, named `p:<id>`. Which
+ * are on for a role follows from its effective grants, wildcards included
+ * ("all" ticks every box). Pure.
+ */
+export declare function checkedFor(granted: readonly string[], catalogueIds: readonly string[]): string[];
+/**
+ * The grid posted back: the catalogue entries whose box was on, in
+ * catalogue order. Ids outside the catalogue are ignored, so a form can
+ * never grant something the app does not gate. Pure.
+ */
+export declare function grantedFromFields(fields: Record<string, string>, catalogueIds: readonly string[]): string[];

package/dist/core/admin.js

@@ -3,20 +3,45 @@
 //
 //   admins: ben@example.com …   (b17_auth.yaml, or AUTH_ADMINS) may open
 //                               /auth/admin and do what the CLI does:
-//                               users and memberships. Never the yaml.
+//                               users, memberships, and what each role
+//                               may do (saved in the database; the yaml
+//                               is the starting point). Never the yaml.
 //
 // An admin is an email, not a role: a role lives in one organization,
 // the admin page spans all of them.
 // ─────────────────────────────────────────────────────────────
+import { OWNER, hasPermission } from "./org.js";
+import { PERMISSION_ID } from "./options.js";
 export const ADMIN_PATH = "/auth/admin";
 export function isAdmin(session, admins) {
     return !!session && admins.includes(session.user.email.toLowerCase());
 }
+/**
+ * Who may change what a role may do, per scope. Pure.
+ *   every organization (scope "")   a system admin (admins: in the yaml)
+ *   one organization (its id)       a system admin, or that organization's owner
+ * The owner role itself is never editable: it holds everything.
+ */
+export function mayEditRoles(admin, scope, roleInScope) {
+    if (admin)
+        return true;
+    return scope !== "" && roleInScope === OWNER;
+}
 /** The forms on the page. Each is one POST with `action` and a few fields. */
-export const USER_ACTIONS = ["add", "set-password", "sign-out", "verify", "send-verify", "remove"];
+/**
+ * add: two flows by the button pressed (`mode`): Register (email + password, ready and verified)
+ *      or Invite (email only; a seven-day link to set a password, which verifies and signs in)
+ * invite: send the Invite link again to an existing user
+ */
+export const USER_ACTIONS = ["add", "invite", "set-password", "sign-out", "verify", "send-verify", "remove"];
 export const ORG_ACTIONS = ["create", "add-member", "set-role", "remove-member", "remove-org"];
+/** set-permissions: save the ticked boxes · defaults: back to the yaml starting point (scope "") · follow: drop an organization's own rule (scope id) */
+export const ROLE_ACTIONS = ["set-permissions", "defaults", "follow"];
 export const isUserAction = (a) => USER_ACTIONS.includes(a);
 export const isOrgAction = (a) => ORG_ACTIONS.includes(a);
+export const isRoleAction = (a) => ROLE_ACTIONS.includes(a);
+/** A role is one word: letters, digits, - or _ */
+export const ROLE_NAME = /^[a-z0-9_-]{1,32}$/i;
 /**
  * What an admin may not do to themselves: remove or lock out the account
  * they are using. (Their own password change is fine: it ends their other
@@ -32,17 +57,34 @@ export function refusedOnSelf(action, targetEmail, selfEmail) {
     return null;
 }
 /**
- * Where to land after an action: the view the form was on. Only two shapes
- * exist, so the value is rebuilt from parts, never taken from the form as is.
+ * Where to land after an action: the view the form was on. Only a few
+ * shapes exist, so the value is rebuilt from parts, never taken from the form as is.
  */
 export function backTo(fields) {
     if (fields.org && /^[0-9a-f-]{36}$/i.test(fields.org))
         return `org=${fields.org}`;
-    if (fields.tab === "users" || fields.tab === "settings")
+    if (fields.tab === "users" || fields.tab === "settings" || fields.tab === "roles")
         return `tab=${fields.tab}`;
     return "";
 }
-/** Roles the page offers in its dropdowns: whatever the yaml defines, plus any role already in use. */
+/** Roles the page offers in its dropdowns: whatever is defined or saved, plus any role already in use. Owner first. */
 export function roleChoices(defined, inUse) {
-    return [...new Set(["owner", "admin", "member", ...defined, ...inUse])];
+    return [...new Set([OWNER, "admin", "member", ...defined, ...inUse])];
+}
+/**
+ * The Roles grid: one checkbox per catalogue entry, named `p:<id>`. Which
+ * are on for a role follows from its effective grants, wildcards included
+ * ("all" ticks every box). Pure.
+ */
+export function checkedFor(granted, catalogueIds) {
+    const s = { authorization: { role: null, permissions: [...granted] } };
+    return catalogueIds.filter((id) => hasPermission(s, id));
+}
+/**
+ * The grid posted back: the catalogue entries whose box was on, in
+ * catalogue order. Ids outside the catalogue are ignored, so a form can
+ * never grant something the app does not gate. Pure.
+ */
+export function grantedFromFields(fields, catalogueIds) {
+    return catalogueIds.filter((id) => PERMISSION_ID.test(id) && !!fields[`p:${id}`]);
 }

package/dist/core/config.d.ts

@@ -7,9 +7,9 @@ export declare const COOKIE_NAME = "auth_session";
 export declare function cookieName(production: boolean): string;
 /** The default; b17_auth.yaml `sessionDays` overrides it */
 export declare const SESSION_DAYS = 7;
-export declare const SIGN_IN_PATH = "/auth/sign-in";
+/** The built-in pages; b17_auth.yaml `pages:` can move them (core/pages.ts) */
+export { SIGN_IN_PATH, SIGN_UP_PATH } from "./pages.ts";
 export declare const SIGN_OUT_PATH = "/auth/sign-out";
-export declare const SIGN_UP_PATH = "/auth/sign-up";
 export declare const TABLE = "users";
 export declare function getSecret(): string;
 export declare function getDatabaseUrl(): string;

package/dist/core/config.js

@@ -20,9 +20,9 @@ export function cookieName(production) {
 }
 /** The default; b17_auth.yaml `sessionDays` overrides it */
 export const SESSION_DAYS = 7;
-export const SIGN_IN_PATH = "/auth/sign-in";
+/** The built-in pages; b17_auth.yaml `pages:` can move them (core/pages.ts) */
+export { SIGN_IN_PATH, SIGN_UP_PATH } from "./pages.js";
 export const SIGN_OUT_PATH = "/auth/sign-out";
-export const SIGN_UP_PATH = "/auth/sign-up";
 export const TABLE = "users";
 export function getSecret() {
     const secret = options().secret;

package/dist/core/db.d.ts

@@ -72,15 +72,39 @@ export type UserState = {
 export declare function userState(id: string, store?: Db): Promise<UserState | null>;
 /** The user's current session_epoch, or null if the user is gone */
 export declare function sessionEpoch(id: string, store?: Db): Promise<number | null>;
-/** Everything a session needs, in one query: the user's state and their active organization. */
+/** Everything a session needs, in one query: the user's state, their active organization, and what the admin page saved for their role. */
 export type SessionRow = UserState & {
     id: string;
     email: string;
     org_id: string | null;
     org_name: string | null;
     role: string | null;
+    /** permissions saved on /auth/admin for this role in this organization, or null */
+    stored_org?: string[] | null;
+    /** permissions saved on /auth/admin for this role in every organization, or null */
+    stored_all?: string[] | null;
 };
 export declare function sessionRow(id: string, store?: Db): Promise<SessionRow | null>;
+export type StoredRole = {
+    scope: string;
+    name: string;
+    permissions: string[];
+    updated_at: string;
+};
+/** Every saved role, all scopes. */
+export declare function storedRoles(store?: Db): Promise<StoredRole[]>;
+/** Save what a role may do: for every organization (scope "") or one (its id). Replaces the previous list. */
+export declare function setRolePermissions(scope: string, name: string, permissions: string[], store?: Db): Promise<void>;
+/** Forget an organization's own rule for a role: it follows the rule for every organization again. False if there was none. */
+export declare function resetRole(scope: string, name: string, store?: Db): Promise<boolean>;
+/**
+ * The starting point, written once: every role from b17_auth.yaml `roles:`
+ * that has no row for every organization yet. A role the admin page has
+ * already saved is never touched. Returns the names written.
+ */
+export declare function seedRoles(defaults: Record<string, string[]>, store?: Db): Promise<string[]>;
+/** The user's role in one organization, or null when they are not a member. */
+export declare function memberRole(userId: string, orgId: string, store?: Db): Promise<string | null>;
 export type OrgRow = {
     id: string;
     name: string;

package/dist/core/db.js

@@ -146,6 +146,22 @@ export const MIGRATIONS = [
             `CREATE UNIQUE INDEX IF NOT EXISTS users_email_lower ON users (LOWER(email))`,
         ],
     },
+    {
+        id: 8,
+        name: "roles",
+        statements: [
+            // What a role may do, as saved on /auth/admin. b17_auth.yaml is the
+            // starting point; a row here wins. scope '' = every organization,
+            // an organization's id = that organization only.
+            `CREATE TABLE IF NOT EXISTS roles (
+        scope       TEXT NOT NULL DEFAULT '',
+        name        TEXT NOT NULL,
+        permissions TEXT[] NOT NULL,
+        updated_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (scope, name)
+      )`,
+        ],
+    },
 ];
 /**
  * The package's tables have plain names (users, orgs, members, tokens).
@@ -274,7 +290,8 @@ export async function sessionRow(id, store = db()) {
     if (!UUID.test(id))
         return null;
     await ensureSchema(store);
-    const rows = await store.query(`SELECT u.id, u.email, u.session_epoch, u.email_verified_at, o.id AS org_id, o.name AS org_name, m.role
+    const rows = await store.query(`SELECT u.id, u.email, u.session_epoch, u.email_verified_at, o.id AS org_id, o.name AS org_name, m.role,
+            ro.permissions AS stored_org, ra.permissions AS stored_all
      FROM users u
      LEFT JOIN members m
        ON m.user_id = u.id
@@ -283,6 +300,8 @@ export async function sessionRow(id, store = db()) {
         (SELECT f.org_id FROM members f WHERE f.user_id = u.id ORDER BY f.created_at, f.org_id LIMIT 1)
       )
      LEFT JOIN orgs o ON o.id = m.org_id
+     LEFT JOIN roles ro ON ro.scope = o.id::text AND ro.name = m.role
+     LEFT JOIN roles ra ON ra.scope = '' AND ra.name = m.role
      WHERE u.id = $1`, [id]);
     const r = rows[0];
     if (!r)
@@ -295,8 +314,50 @@ export async function sessionRow(id, store = db()) {
         org_id: r.org_id,
         org_name: r.org_name,
         role: r.role,
+        stored_org: r.stored_org ?? null,
+        stored_all: r.stored_all ?? null,
     };
 }
+/** Every saved role, all scopes. */
+export async function storedRoles(store = db()) {
+    await ensureSchema(store);
+    return store.query(`SELECT scope, name, permissions, updated_at FROM roles ORDER BY scope, name`);
+}
+/** Save what a role may do: for every organization (scope "") or one (its id). Replaces the previous list. */
+export async function setRolePermissions(scope, name, permissions, store = db()) {
+    await ensureSchema(store);
+    await store.query(`INSERT INTO roles (scope, name, permissions, updated_at) VALUES ($1, $2, $3, now())
+     ON CONFLICT (scope, name) DO UPDATE SET permissions = EXCLUDED.permissions, updated_at = now()`, [scope, name, permissions]);
+}
+/** Forget an organization's own rule for a role: it follows the rule for every organization again. False if there was none. */
+export async function resetRole(scope, name, store = db()) {
+    await ensureSchema(store);
+    const rows = await store.query(`DELETE FROM roles WHERE scope = $1 AND name = $2 RETURNING name`, [scope, name]);
+    return rows.length > 0;
+}
+/**
+ * The starting point, written once: every role from b17_auth.yaml `roles:`
+ * that has no row for every organization yet. A role the admin page has
+ * already saved is never touched. Returns the names written.
+ */
+export async function seedRoles(defaults, store = db()) {
+    await ensureSchema(store);
+    const written = [];
+    for (const [name, permissions] of Object.entries(defaults)) {
+        const rows = await store.query(`INSERT INTO roles (scope, name, permissions) VALUES ('', $1, $2) ON CONFLICT (scope, name) DO NOTHING RETURNING name`, [name, permissions]);
+        if (rows.length)
+            written.push(name);
+    }
+    return written;
+}
+/** The user's role in one organization, or null when they are not a member. */
+export async function memberRole(userId, orgId, store = db()) {
+    if (!UUID.test(userId) || !UUID.test(orgId))
+        return null;
+    await ensureSchema(store);
+    const rows = await store.query(`SELECT role FROM members WHERE user_id = $1 AND org_id = $2`, [userId, orgId]);
+    return rows[0]?.role ?? null;
+}
 export async function createOrg(name, store = db()) {
     await ensureSchema(store);
     const [row] = await store.query(`INSERT INTO orgs (name) VALUES ($1) RETURNING id, name, created_at`, [name.trim()]);

package/dist/core/guard.d.ts

@@ -19,9 +19,12 @@ export declare function matchesPattern(pathname: string, pattern: string): boole
 export type AccessRules = {
     public?: readonly string[];
     protected?: readonly string[];
+    /** The app's own sign-in / sign-up pages (b17_auth.yaml `pages:`): exact paths, always open */
+    pages?: readonly string[];
 };
 /**
- * Paths reachable without a session. The auth pages and Next internals
+ * Paths reachable without a session. The auth pages (the package's under
+ * /auth/, and the app's own named under `pages:`) and Next internals
  * always are. Then one of two modes from b17_auth.yaml:
  *
  *   protected: /app/* /api/*   only these need a session; everything else is open