@binary1702/auth 0.3.0 → 0.4.0

package/dist/core/guard.js

@@ -47,7 +47,8 @@ export function matchesPattern(pathname, pattern) {
     return pathname === pattern;
 }
 /**
- * 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
@@ -61,6 +62,8 @@ export function isPublic(pathname, rules = {}) {
     const r = Array.isArray(rules) ? { public: rules } : rules;
     if (/^\/auth(\/|$)/.test(pathname))
         return true;
+    if (r.pages?.includes(pathname))
+        return true;
     if (pathname.startsWith("/_next/"))
         return true;
     if (r.protected?.length)

package/dist/core/html.d.ts

@@ -1,3 +1,4 @@
+import { type Pages } from "./pages.ts";
 export declare const escape: (s: string) => string;
 /**
  * Headers every auth page is served with. Pure.
@@ -8,6 +9,7 @@ export declare const escape: (s: string) => string;
  */
 export declare function securityHeaders(scriptNonce?: string): Record<string, string>;
 export declare function setSiteName(name: string | undefined): void;
+export declare function setPages(p: Pages | undefined): void;
 /** "Didn't get the email?" A second form, POSTing to /auth/verify/resend. */
 export declare function resendForm(email?: string): string;
 export declare function signInPage(opts?: {
@@ -25,10 +27,15 @@ export declare function forgotPage(opts?: {
     error?: string;
     message?: string;
 }): string;
-/** The form behind the emailed link: a new password, the token hidden. */
+/**
+ * The form behind an emailed link: a new password, the token hidden. A
+ * reset link, or (`invite`) the welcome link an added user gets: same
+ * form, posted to /auth/invite, worded for a first password.
+ */
 export declare function resetPage(opts: {
     token: string;
     error?: string;
+    invite?: boolean;
 }): string;
 export declare function signUpPage(opts?: {
     error?: string;

package/dist/core/html.js

@@ -3,9 +3,10 @@
 // consumer never builds a form or a page. Every untrusted value goes
 // through escape().
 // ─────────────────────────────────────────────────────────────
-import { SIGN_IN_PATH, SIGN_UP_PATH } from "./config.js";
+import { pagePath } from "./pages.js";
 import { VERIFY_PATH } from "./verify.js";
 import { FORGOT_PATH, RESET_PATH } from "./reset.js";
+import { INVITE_PATH } from "./invite.js";
 import { PASSWORD_MAX, PASSWORD_MIN } from "./signup.js";
 export const escape = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 /**
@@ -50,6 +51,13 @@ let siteName = "";
 export function setSiteName(name) {
     siteName = name ?? "";
 }
+/** Where links to sign-in / sign-up point: the app's own pages when b17_auth.yaml names them */
+let pages = {};
+export function setPages(p) {
+    pages = p ?? {};
+}
+const SIGN_IN_PATH = () => pagePath(pages, "signIn");
+const SIGN_UP_PATH = () => pagePath(pages, "signUp");
 function shell(title, body) {
     return `<!doctype html>
 <html lang="en">
@@ -92,7 +100,7 @@ export function resendForm(email) {
 export function signInPage(opts = {}) {
     return page({
         title: opts.title ?? "Sign in",
-        action: SIGN_IN_PATH,
+        action: SIGN_IN_PATH(),
         error: opts.error,
         notice: opts.notice,
         next: opts.next,
@@ -100,7 +108,7 @@ export function signInPage(opts = {}) {
         fields: `
   <label>Email <input name="email" type="email" autocomplete="email" autofocus required value="${escape(opts.email ?? "")}"></label>
   <label>Password <input name="password" type="password" autocomplete="current-password" required></label>`,
-        alt: `<p class="alt"><a href="${FORGOT_PATH}">Forgot password?</a>${opts.canSignUp ? ` · No account? <a href="${SIGN_UP_PATH}${nextQuery(opts.next)}">Create one</a>` : ""}</p>`,
+        alt: `<p class="alt"><a href="${FORGOT_PATH}">Forgot password?</a>${opts.canSignUp ? ` · No account? <a href="${SIGN_UP_PATH()}${nextQuery(opts.next)}">Create one</a>` : ""}</p>`,
         after: opts.resend ? resendForm(opts.email) : undefined,
     });
 }
@@ -110,7 +118,7 @@ export function forgotPage(opts = {}) {
         return messagePage({
             title: "Check your email",
             message: opts.message ?? "",
-            link: { href: SIGN_IN_PATH, text: "Back to sign in" },
+            link: { href: SIGN_IN_PATH(), text: "Back to sign in" },
         });
     }
     return page({
@@ -120,33 +128,38 @@ export function forgotPage(opts = {}) {
         button: "Send reset link",
         fields: `
   <label>Email <input name="email" type="email" autocomplete="email" autofocus required></label>`,
-        alt: `<p class="alt"><a href="${SIGN_IN_PATH}">Back to sign in</a></p>`,
+        alt: `<p class="alt"><a href="${SIGN_IN_PATH()}">Back to sign in</a></p>`,
     });
 }
-/** The form behind the emailed link: a new password, the token hidden. */
+/**
+ * The form behind an emailed link: a new password, the token hidden. A
+ * reset link, or (`invite`) the welcome link an added user gets: same
+ * form, posted to /auth/invite, worded for a first password.
+ */
 export function resetPage(opts) {
     return page({
-        title: "Choose a new password",
-        action: RESET_PATH,
+        title: opts.invite ? `Welcome${siteName ? ` to ${siteName}` : ""}` : "Choose a new password",
+        action: opts.invite ? INVITE_PATH : RESET_PATH,
         error: opts.error,
-        button: "Set password",
+        notice: opts.invite ? "Choose a password to finish setting up your account." : undefined,
+        button: opts.invite ? "Set password and sign in" : "Set password",
         hidden: `\n  <input type="hidden" name="token" value="${escape(opts.token)}">`,
         fields: `
-  <label>New password <input name="password" type="password" autocomplete="new-password" minlength="${PASSWORD_MIN}" maxlength="${PASSWORD_MAX}" autofocus required></label>`,
-        alt: `<p class="alt"><a href="${FORGOT_PATH}">Request a new link</a></p>`,
+  <label>${opts.invite ? "Password" : "New password"} <input name="password" type="password" autocomplete="new-password" minlength="${PASSWORD_MIN}" maxlength="${PASSWORD_MAX}" autofocus required></label>`,
+        alt: opts.invite ? `<p class="alt">Already set it? <a href="${SIGN_IN_PATH()}">Sign in</a></p>` : `<p class="alt"><a href="${FORGOT_PATH}">Request a new link</a></p>`,
     });
 }
 export function signUpPage(opts = {}) {
     return page({
         title: opts.title ?? (opts.first ? "Create the first account" : "Create account"),
-        action: SIGN_UP_PATH,
+        action: SIGN_UP_PATH(),
         error: opts.error,
         next: opts.next,
         button: "Create account",
         fields: `
   <label>Email <input name="email" type="email" autocomplete="email" autofocus required></label>
   <label>Password <input name="password" type="password" autocomplete="new-password" minlength="${PASSWORD_MIN}" maxlength="${PASSWORD_MAX}" required></label>${opts.inviteRequired ? `\n  <label>Invite code <input name="invite" autocomplete="off" required></label>` : ""}`,
-        alt: opts.first ? undefined : `<p class="alt">Have an account? <a href="${SIGN_IN_PATH}${nextQuery(opts.next)}">Sign in</a></p>`,
+        alt: opts.first ? undefined : `<p class="alt">Have an account? <a href="${SIGN_IN_PATH()}${nextQuery(opts.next)}">Sign in</a></p>`,
     });
 }
 /** A page with no form: a result, an error, a "check your email". */

package/dist/core/invite.d.ts

@@ -0,0 +1,7 @@
+import type { EmailMessage } from "./email.ts";
+export declare const INVITE_PATH = "/auth/invite";
+export declare const INVITE_TTL_SECONDS: number;
+export declare const INVITE_LINK_INVALID = "This invitation link is invalid, already used, or older than seven days. Ask for a new one.";
+/** The absolute link that goes in the email */
+export declare function inviteLink(base: string, rawToken: string): string;
+export declare function inviteEmail(to: string, link: string, site: string): EmailMessage;

package/dist/core/invite.js

@@ -0,0 +1,30 @@
+// ─────────────────────────────────────────────────────────────
+// Invitations. Pure: the link, the email, the constants.
+//
+// An admin adds a user by email alone (no password). The account is
+// created with a random password nobody knows, unverified, and the
+// person gets one link: /auth/invite?token=… It is the reset flow with
+// a longer life and different words: POST /auth/invite consumes the
+// `invite` token, sets the password they chose (which marks the email
+// verified, since the link proved it), and signs them in.
+//
+// The same link can be sent again later ("invite" on the admin page):
+// a new token, the old one still dies when either is used or expires.
+// ─────────────────────────────────────────────────────────────
+export const INVITE_PATH = "/auth/invite";
+export const INVITE_TTL_SECONDS = 7 * 24 * 60 * 60;
+export const INVITE_LINK_INVALID = "This invitation link is invalid, already used, or older than seven days. Ask for a new one.";
+/** The absolute link that goes in the email */
+export function inviteLink(base, rawToken) {
+    const url = new URL(INVITE_PATH, base);
+    url.searchParams.set("token", rawToken);
+    return url.toString();
+}
+export function inviteEmail(to, link, site) {
+    return {
+        to,
+        subject: `Your ${site} account: choose a password`,
+        text: `An account on ${site} was created for this address. Open the link below to choose your password and sign in. It works once and expires in seven days.\n\n${link}\n\nIf you were not expecting this, ignore this email: nothing happens until the link is used.`,
+        html: `<p>An account on ${site} was created for this address. Open the link below to choose your password and sign in. It works once and expires in seven days.</p><p><a href="${link}">${link}</a></p><p>If you were not expecting this, ignore this email: nothing happens until the link is used.</p>`,
+    };
+}

package/dist/core/options.d.ts

@@ -1,4 +1,5 @@
 import { type YamlTree } from "./yaml.ts";
+import { type Pages } from "./pages.ts";
 export declare const CONFIG_FILE = "b17_auth.yaml";
 export type SignupMode = "open" | "closed" | "invite";
 export type EmailOptions = {
@@ -33,13 +34,22 @@ export type Options = {
     public: string[];
     /** Emails that may open /auth/admin. Lowercased. */
     admins: string[];
+    /** The app's own sign-in / sign-up pages, by path. Missing: the package's pages under /auth/. */
+    pages: Pages;
+    /** The signed-in home (e.g. /app): after sign-in, the admin page's app link, and where a signed-in visitor to / is sent. Missing: the site root. */
+    home?: string;
     database?: string;
     secret?: string;
     email: EmailOptions;
-    /** role → permissions. "all" (or "*") is everything, "blue.*" a prefix */
-    permissions: Record<string, string[]>;
-    /** organization name → role → permissions, overriding `permissions` there */
-    organizations: Record<string, Record<string, string[]>>;
+    /** What the app gates: permission id → label. The admin page's rows. */
+    permissions: Record<string, string>;
+    /**
+     * role → permissions, written into the database once at install as the
+     * starting point ("all" or "*" is everything, "blue.*" a prefix). After
+     * that the database decides; "Reset to defaults" on /auth/admin brings a
+     * role back to this.
+     */
+    roles: Record<string, string[]>;
     production: boolean;
 };
 export declare const DEFAULTS: Options;
@@ -48,6 +58,15 @@ export declare const SECRET_KEYS: string[];
 export type Env = Record<string, string | undefined>;
 /** The env vars as they were before the file existed. Pure. */
 export declare function fromEnv(env: Env): Partial<Options>;
+/** A permission id: words joined by dots, `area.verb`; a grant may end in `.*` */
+export declare const PERMISSION_ID: RegExp;
+/**
+ * Before 0.4.0, `permissions:` held role → list. Now it is the catalogue
+ * (id → label) and the map is `roles:`. A value that reads as a list of
+ * grants ("all", "x.*", dotted ids only) under the old key is the old
+ * shape: say so, instead of turning role names into permission ids. Pure.
+ */
+export declare function looksLikeRoleMap(values: unknown[]): boolean;
 /** "all" is the file's word for "*"; duplicates dropped. */
 export declare function normalizePermissions(list: string[]): string[];
 export declare class OptionsError extends Error {
@@ -62,7 +81,7 @@ export declare function interpolate(value: string, env: Env, key: string): strin
 export declare function literalSecrets(tree: YamlTree): string[];
 /** The file's contents as options, ${…} resolved. Pure. */
 export declare function fromYaml(tree: YamlTree, env: Env): Partial<Options>;
-/** defaults ← file ← env. Maps (email, permissions, organizations) merge key by key. Pure. */
+/** defaults ← file ← env. Maps (email, pages, permissions, roles) merge key by key. Pure. */
 export declare function resolveOptions(file: YamlTree | null, env: Env): Options;
 /**
  * Read b17_auth.yaml from the project root (the directory the server was

package/dist/core/options.js

@@ -13,6 +13,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { parseYaml, words } from "./yaml.js";
+import { PAGE_KEYS, validateAppPath, validatePagePath } from "./pages.js";
 export const CONFIG_FILE = "b17_auth.yaml";
 export const DEFAULTS = {
     signup: "closed",
@@ -21,11 +22,12 @@ export const DEFAULTS = {
     protected: [],
     public: [],
     admins: [],
+    pages: {},
     email: {},
     // An owner can do everything unless a file says otherwise. A sole
-    // developer never has to write a permissions section at all.
-    permissions: { owner: ["*"] },
-    organizations: {},
+    // developer never has to write a roles section at all.
+    permissions: {},
+    roles: { owner: ["*"] },
     production: false,
 };
 /** Keys whose value must be a ${…} reference in the file, never a literal */
@@ -49,6 +51,24 @@ export function fromEnv(env) {
         o.public = words(env.AUTH_PUBLIC);
     if (env.AUTH_ADMINS)
         o.admins = words(env.AUTH_ADMINS).map((e) => e.toLowerCase());
+    const pages = {};
+    if (env.AUTH_SIGN_IN_PAGE)
+        pages.signIn = env.AUTH_SIGN_IN_PAGE;
+    if (env.AUTH_SIGN_UP_PAGE)
+        pages.signUp = env.AUTH_SIGN_UP_PAGE;
+    for (const [k, v] of Object.entries(pages)) {
+        const bad = validatePagePath(k, v);
+        if (bad)
+            throw new Error(`AUTH_${k === "signIn" ? "SIGN_IN" : "SIGN_UP"}_PAGE: ${bad}`);
+    }
+    if (Object.keys(pages).length)
+        o.pages = pages;
+    if (env.AUTH_HOME) {
+        const bad = validateAppPath("home", env.AUTH_HOME);
+        if (bad)
+            throw new Error(`AUTH_HOME: ${bad}`);
+        o.home = env.AUTH_HOME;
+    }
     if (env.DATABASE_URL)
         o.database = env.DATABASE_URL;
     if (env.AUTH_SECRET)
@@ -72,31 +92,48 @@ export function fromEnv(env) {
         email.resend = { apiKey: env.AUTH_RESEND_API_KEY };
     if (Object.keys(email).length)
         o.email = email;
-    if (env.AUTH_PERMISSIONS)
-        o.permissions = permissionsFromJson(env.AUTH_PERMISSIONS);
+    // AUTH_ROLES is the name since 0.4.0; AUTH_PERMISSIONS meant the same map before and still works
+    const rolesJson = env.AUTH_ROLES ?? env.AUTH_PERMISSIONS;
+    if (rolesJson)
+        o.roles = rolesFromJson(rolesJson, env.AUTH_ROLES ? "AUTH_ROLES" : "AUTH_PERMISSIONS");
     o.production = env.NODE_ENV === "production";
     return o;
 }
-function permissionsFromJson(raw) {
+function rolesFromJson(raw, name) {
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error('AUTH_PERMISSIONS is not valid JSON. Expected: {"admin":["invoices.view"],"member":[]}');
+        throw new Error(`${name} is not valid JSON. Expected: {"admin":["invoices.view"],"member":[]}`);
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("AUTH_PERMISSIONS must be a JSON object mapping role → list of permissions");
+        throw new Error(`${name} must be a JSON object mapping role → list of permissions`);
     }
     const map = {};
     for (const [role, perms] of Object.entries(parsed)) {
         if (!Array.isArray(perms) || !perms.every((p) => typeof p === "string")) {
-            throw new Error(`AUTH_PERMISSIONS: role "${role}" must map to a list of strings`);
+            throw new Error(`${name}: role "${role}" must map to a list of strings`);
         }
         map[role] = normalizePermissions(perms);
     }
     return map;
 }
+/** A permission id: words joined by dots, `area.verb`; a grant may end in `.*` */
+export const PERMISSION_ID = /^[a-z0-9_-]+(\.[a-z0-9_-]+)*$/i;
+const GRANT = /^([a-z0-9_-]+\.)*[a-z0-9_-]+(\.\*)?$/i;
+/**
+ * Before 0.4.0, `permissions:` held role → list. Now it is the catalogue
+ * (id → label) and the map is `roles:`. A value that reads as a list of
+ * grants ("all", "x.*", dotted ids only) under the old key is the old
+ * shape: say so, instead of turning role names into permission ids. Pure.
+ */
+export function looksLikeRoleMap(values) {
+    const strings = values.filter((v) => typeof v === "string" && v.trim() !== "");
+    if (!strings.length)
+        return false;
+    return strings.every((v) => words(v).every((w) => w === "all" || w === "*" || (GRANT.test(w) && w.includes("."))));
+}
 /** "all" is the file's word for "*"; duplicates dropped. */
 export function normalizePermissions(list) {
     return [...new Set(list.map((p) => (p === "all" ? "*" : p)))];
@@ -150,7 +187,10 @@ function section(tree, key) {
 /** The file's contents as options, ${…} resolved. Pure. */
 export function fromYaml(tree, env) {
     const o = {};
-    const known = new Set(["name", "signup", "inviteCode", "emailDomain", "requireVerified", "sessionDays", "protected", "public", "admins", "database", "secret", "email", "permissions", "organizations"]);
+    const known = new Set(["name", "signup", "inviteCode", "emailDomain", "requireVerified", "sessionDays", "protected", "public", "admins", "pages", "home", "database", "secret", "email", "permissions", "roles"]);
+    if (tree.organizations !== undefined) {
+        throw new OptionsError("organizations: is gone; an organization's own roles are set on /auth/admin (open the organization) and saved in the database");
+    }
     for (const k of Object.keys(tree))
         if (!known.has(k))
             throw new OptionsError(`unknown key "${k}"`);
@@ -200,6 +240,28 @@ export function fromYaml(tree, env) {
             if (!a.includes("@"))
                 throw new OptionsError(`admins are email addresses, not "${a}"`);
     }
+    const pages = section(tree, "pages");
+    if (pages) {
+        o.pages = {};
+        for (const key of Object.keys(pages)) {
+            if (!PAGE_KEYS.includes(key))
+                throw new OptionsError(`pages.${key}: the pages are ${PAGE_KEYS.join(" and ")}`);
+            const path = str(pages, key, env);
+            if (path === undefined)
+                continue;
+            const bad = validatePagePath(key, path);
+            if (bad)
+                throw new OptionsError(bad);
+            o.pages[key] = path;
+        }
+    }
+    const home = str(tree, "home", env);
+    if (home !== undefined) {
+        const bad = validateAppPath("home", home);
+        if (bad)
+            throw new OptionsError(bad);
+        o.home = home;
+    }
     const database = str(tree, "database", env);
     if (database)
         o.database = database;
@@ -239,17 +301,22 @@ export function fromYaml(tree, env) {
         o.email = e;
     }
     const perms = section(tree, "permissions");
-    if (perms)
-        o.permissions = roleMap(perms, env, "permissions");
-    const orgs = section(tree, "organizations");
-    if (orgs) {
-        o.organizations = {};
-        for (const [org, roles] of Object.entries(orgs)) {
-            if (typeof roles !== "object")
-                throw new OptionsError(`organizations.${org} must be a section of role: permissions`);
-            o.organizations[org] = roleMap(roles, env, `organizations.${org}`);
+    if (perms) {
+        if (tree.roles === undefined && looksLikeRoleMap(Object.values(perms))) {
+            throw new OptionsError("permissions: now lists what the app gates, one `id: label` per line; the role → permissions map moved to roles:");
+        }
+        o.permissions = {};
+        for (const [id, v] of Object.entries(perms)) {
+            if (!PERMISSION_ID.test(id))
+                throw new OptionsError(`permissions.${id}: an id is words joined by dots, like invoices.create`);
+            if (typeof v === "object" && !isEmpty(v))
+                throw new OptionsError(`permissions.${id} must be a label, not a section`);
+            o.permissions[id] = typeof v === "string" && v.trim() ? interpolate(v, env, `permissions.${id}`) : id;
         }
     }
+    const roles = section(tree, "roles");
+    if (roles)
+        o.roles = roleMap(roles, env, "roles");
     return o;
 }
 function roleMap(tree, env, where) {
@@ -266,15 +333,15 @@ function roleMap(tree, env, where) {
     return map;
 }
 // ── merge ─────────────────────────────────────────────────────
-/** defaults ← file ← env. Maps (email, permissions, organizations) merge key by key. Pure. */
+/** defaults ← file ← env. Maps (email, pages, permissions, roles) merge key by key. Pure. */
 export function resolveOptions(file, env) {
     const layers = [DEFAULTS, file ? fromYaml(file, env) : {}, fromEnv(env)];
-    const out = { ...DEFAULTS, email: {}, permissions: {}, organizations: {} };
+    const out = { ...DEFAULTS, email: {}, pages: {}, permissions: {}, roles: {} };
     for (const layer of layers) {
         for (const [k, v] of Object.entries(layer)) {
             if (v === undefined)
                 continue;
-            if (k === "email" || k === "permissions" || k === "organizations")
+            if (k === "email" || k === "pages" || k === "permissions" || k === "roles")
                 Object.assign(out[k], v);
             else
                 out[k] = v;

package/dist/core/org.d.ts

@@ -1,6 +1,5 @@
 import type { User } from "./session.ts";
 import type { SessionRow } from "./db.ts";
-import type { Options } from "./options.ts";
 export type Organization = {
     id: string;
     name: string;
@@ -14,11 +13,21 @@ export type Session = {
     organization: Organization | null;
     authorization: Authorization;
 };
-export type PermissionSource = Pick<Options, "permissions" | "organizations">;
-/** The effective permissions of a role, in an organization. The organization's own map wins. Pure. */
-export declare function permissionsFor(role: string | null, org: string | null, opts: PermissionSource): string[];
+/** The role whose permissions cannot be taken away */
+export declare const OWNER = "owner";
+/** What the database holds for a role: for this organization, and for every organization. Null = nothing saved there. */
+export type StoredGrants = {
+    org?: string[] | null;
+    all?: string[] | null;
+};
+/** What the session builder needs besides the row */
+export type PermissionSource = {
+    admins?: readonly string[];
+};
+/** The effective permissions of a role. This organization's rule, else the rule for all, else nothing. Owner: everything. Pure. */
+export declare function permissionsFor(role: string | null, stored?: StoredGrants): string[];
 /** Build the contract from the store's row. Pure. */
-export declare function buildSession(row: SessionRow, opts: PermissionSource): Session;
+export declare function buildSession(row: SessionRow, opts?: PermissionSource): Session;
 /**
  * The check. Pure. A granted entry matches when it is
  *   "*"            everything

package/dist/core/org.js

@@ -7,35 +7,45 @@
 //   organization    { id, name } or null when the user is in none
 //   authorization   { role, permissions }
 //
-// Role comes from the membership row (members.role, free text;
-// the CLI defaults to "member"). Permissions are the app's business,
-// so they come from b17_auth.yaml (or AUTH_PERMISSIONS):
+// Role comes from the membership row (members.role, free text; the CLI
+// defaults to "member"). What a role may do comes from the database,
+// the `roles` table, as set on /auth/admin:
 //
-//   permissions:            role → what it may do
-//     owner: all            "all" (or "*") is everything
-//     member: blue.* green.read
-//   organizations:          overrides, by organization name
-//     Acme:
-//       member: blue.read
+//   scope = the organization's id   that organization's own rule for the role
+//   scope = ""                       the rule for every organization without its own
 //
-// Unknown role, no role, or no map: no permissions. All pure; the
-// store feeds it one row.
+// b17_auth.yaml never decides: `permissions:` declares what exists (the
+// catalogue), `roles:` is written into the database once, at install,
+// as the starting point. After that the database is the truth.
+//
+// Two roles are fixed: `owner` always holds everything (so an
+// organization can never lock out its own owner), and an email under
+// `admins:` holds everything (they can grant themselves anything on
+// /auth/admin anyway, and the first account has no organization yet).
+//
+// Unknown role, no role, or nothing saved: no permissions. All pure;
+// the store feeds it one row.
 // ─────────────────────────────────────────────────────────────
-/** The effective permissions of a role, in an organization. The organization's own map wins. Pure. */
-export function permissionsFor(role, org, opts) {
+/** The role whose permissions cannot be taken away */
+export const OWNER = "owner";
+/** The effective permissions of a role. This organization's rule, else the rule for all, else nothing. Owner: everything. Pure. */
+export function permissionsFor(role, stored = {}) {
     if (!role)
         return [];
-    const own = org ? opts.organizations[org]?.[role] : undefined;
-    return own ?? opts.permissions[role] ?? [];
+    if (role === OWNER)
+        return ["*"];
+    return stored.org ?? stored.all ?? [];
 }
 /** Build the contract from the store's row. Pure. */
-export function buildSession(row, opts) {
+export function buildSession(row, opts = {}) {
     const organization = row.org_id && row.org_name !== null ? { id: row.org_id, name: row.org_name } : null;
     const role = organization ? row.role : null;
+    const admin = (opts.admins ?? []).includes(row.email.toLowerCase());
+    const permissions = admin ? ["*"] : permissionsFor(role, { org: row.stored_org, all: row.stored_all });
     return {
         user: { id: row.id, email: row.email },
         organization,
-        authorization: { role, permissions: permissionsFor(role, organization?.name ?? null, opts) },
+        authorization: { role, permissions },
     };
 }
 /**

package/dist/core/pages.d.ts

@@ -0,0 +1,34 @@
+export declare const SIGN_IN_PATH = "/auth/sign-in";
+export declare const SIGN_UP_PATH = "/auth/sign-up";
+export declare const PAGE_KEYS: readonly ["signIn", "signUp"];
+export type PageKey = (typeof PAGE_KEYS)[number];
+/** App paths per page; a missing key means the package's own page */
+export type Pages = Partial<Record<PageKey, string>>;
+/** The app's path for a page, or undefined when the package serves it */
+export declare function pageOverride(pages: Pages | undefined, key: PageKey): string | undefined;
+/** Where a browser is sent for a page: the app's path if named, else the package's */
+export declare function pagePath(pages: Pages | undefined, key: PageKey): string;
+/** The app's pages, for the proxy: they must open without a session */
+export declare function appPages(pages: Pages | undefined): string[];
+/**
+ * An app path is an absolute path on this site, outside /auth/ (which the
+ * package serves), with no pattern, query or fragment. Error text or null.
+ */
+export declare function validateAppPath(key: string, path: string): string | null;
+export declare function validatePagePath(key: string, path: string): string | null;
+/**
+ * Where a signed-in visitor lands when nothing says otherwise: `home:` from
+ * b17_auth.yaml (the app's signed-in home, say /app), else the site root.
+ *   after sign-in with no `next`, or `next` reduced to "/" by safeNext
+ *   the admin page's "app" link
+ *   a signed-in visitor opening "/" (the proxy sends them home: the root is
+ *   the public site, the app is where they were going)
+ */
+export declare function landing(next: string | null | undefined, home: string | undefined): string;
+/** Should the proxy send this signed-in request home? Only the root, only when home is elsewhere. */
+export declare function sendsHome(pathname: string, home: string | undefined): boolean;
+/**
+ * The same URL on the app's page: GET /auth/sign-in?next=/x&error=1 becomes
+ * /sign-in?next=/x&error=1, so a bookmark or an old link keeps working.
+ */
+export declare function movedTo(path: string, search: string): string;