@binary1702/auth 0.2.5 → 0.4.0

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

@@ -0,0 +1,95 @@
+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 = {
+    from?: string;
+    replyTo?: string;
+    gmail?: {
+        /** the mailbox to send as */
+        user: string;
+        /** service account (Workspace, domain-wide delegation): its email and private key */
+        clientEmail?: string;
+        privateKey?: string;
+        /** or an OAuth client with a refresh token (a plain Gmail account) */
+        clientId?: string;
+        clientSecret?: string;
+        refreshToken?: string;
+    };
+    resend?: {
+        apiKey: string;
+    };
+};
+export type Options = {
+    /** App name: page titles and email subjects. Falls back to the request's host. */
+    name?: string;
+    signup: SignupMode;
+    inviteCode?: string;
+    emailDomain?: string;
+    requireVerified: boolean;
+    sessionDays: number;
+    /** Paths that need a session, exact or `prefix/*`; everything else is open. Use this OR `public`. */
+    protected: string[];
+    /** The reverse: everything needs a session except these (and static files). */
+    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;
+    /** 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;
+/** Keys whose value must be a ${…} reference in the file, never a literal */
+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 {
+    constructor(message: string);
+}
+/** Replace every ${NAME} in a value from env. A missing variable is an error naming both. */
+export declare function interpolate(value: string, env: Env, key: string): string;
+/**
+ * Literal secrets in a committed file are how keys leak. Returns the keys
+ * that hold a literal where a ${…} reference belongs. Pure.
+ */
+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, 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
+ * started in), or from AUTH_CONFIG when that is set, and merge with env.
+ * Memoized; re-read in development when the file changes.
+ */
+export declare function loadOptions(cwd?: string, env?: Env): Options;
+/** The current options. What every handler reads. */
+export declare function options(): Options;
+/** Drop the memo (tests, CLI after writing the file). */
+export declare function resetOptions(): void;

package/dist/core/options.js

@@ -0,0 +1,377 @@
+// ─────────────────────────────────────────────────────────────
+// One typed object for everything configurable, built from three
+// layers, each overriding the one before:
+//
+//   DEFAULTS         what the package does with no configuration
+//   b17_auth.yaml    the app's choices, with ${NAME} pulled from env
+//   env vars         the deploy-time override, and the only home of secrets
+//
+// No file → the env vars work exactly as they always did. The pure
+// part is resolveOptions(); loadOptions() adds the file read and a
+// per-process memo (re-read in development when the file changes).
+// ─────────────────────────────────────────────────────────────
+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",
+    requireVerified: false,
+    sessionDays: 7,
+    protected: [],
+    public: [],
+    admins: [],
+    pages: {},
+    email: {},
+    // An owner can do everything unless a file says otherwise. A sole
+    // 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 */
+export const SECRET_KEYS = ["database", "secret", "inviteCode", "email.gmail.privateKey", "email.gmail.clientSecret", "email.gmail.refreshToken", "email.resend.apiKey"];
+// ── env layer ─────────────────────────────────────────────────
+const truthy = (v) => /^(true|1|yes)$/i.test(v ?? "");
+/** The env vars as they were before the file existed. Pure. */
+export function fromEnv(env) {
+    const o = {};
+    if (env.AUTH_SIGNUP === "open")
+        o.signup = env.AUTH_INVITE_CODE ? "invite" : "open";
+    if (env.AUTH_INVITE_CODE)
+        o.inviteCode = env.AUTH_INVITE_CODE;
+    if (env.AUTH_EMAIL_DOMAIN)
+        o.emailDomain = env.AUTH_EMAIL_DOMAIN;
+    if (env.AUTH_REQUIRE_VERIFIED !== undefined)
+        o.requireVerified = truthy(env.AUTH_REQUIRE_VERIFIED);
+    if (env.AUTH_PROTECTED)
+        o.protected = words(env.AUTH_PROTECTED);
+    if (env.AUTH_PUBLIC)
+        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)
+        o.secret = env.AUTH_SECRET;
+    const email = {};
+    if (env.AUTH_EMAIL_FROM)
+        email.from = env.AUTH_EMAIL_FROM;
+    if (env.AUTH_EMAIL_REPLY_TO)
+        email.replyTo = env.AUTH_EMAIL_REPLY_TO;
+    if (env.AUTH_GMAIL_USER) {
+        email.gmail = {
+            user: env.AUTH_GMAIL_USER,
+            clientEmail: env.AUTH_GMAIL_CLIENT_EMAIL,
+            privateKey: env.AUTH_GMAIL_PRIVATE_KEY,
+            clientId: env.AUTH_GMAIL_CLIENT_ID,
+            clientSecret: env.AUTH_GMAIL_CLIENT_SECRET,
+            refreshToken: env.AUTH_GMAIL_REFRESH_TOKEN,
+        };
+    }
+    if (env.AUTH_RESEND_API_KEY)
+        email.resend = { apiKey: env.AUTH_RESEND_API_KEY };
+    if (Object.keys(email).length)
+        o.email = email;
+    // 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 rolesFromJson(raw, name) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${name} is not valid JSON. Expected: {"admin":["invoices.view"],"member":[]}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        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(`${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)))];
+}
+// ── file layer ────────────────────────────────────────────────
+export class OptionsError extends Error {
+    constructor(message) {
+        super(`${CONFIG_FILE}: ${message}`);
+        this.name = "OptionsError";
+    }
+}
+/** Replace every ${NAME} in a value from env. A missing variable is an error naming both. */
+export function interpolate(value, env, key) {
+    return value.replace(/\$\{([A-Z0-9_]+)\}/gi, (_, name) => {
+        const v = env[name];
+        if (v === undefined || v === "")
+            throw new OptionsError(`${key} refers to \${${name}}, which is not set in the environment`);
+        return v;
+    });
+}
+const isRef = (v) => typeof v === "string" && /^\$\{[A-Z0-9_]+\}$/i.test(v.trim());
+/**
+ * Literal secrets in a committed file are how keys leak. Returns the keys
+ * that hold a literal where a ${…} reference belongs. Pure.
+ */
+export function literalSecrets(tree) {
+    const get = (path) => path.split(".").reduce((n, k) => (n && typeof n === "object" ? n[k] : undefined), tree);
+    return SECRET_KEYS.filter((k) => {
+        const v = get(k);
+        return typeof v === "string" && v.trim() !== "" && !isRef(v);
+    });
+}
+/** `key:` with nothing after it and nothing under it: the same as leaving the key out */
+const isEmpty = (v) => typeof v === "object" && v !== null && Object.keys(v).length === 0;
+function str(tree, key, env) {
+    const v = tree[key];
+    if (v === undefined || isEmpty(v))
+        return undefined;
+    if (typeof v !== "string")
+        throw new OptionsError(`${key} must be a value, not a section`);
+    return interpolate(v, env, key);
+}
+function section(tree, key) {
+    const v = tree[key];
+    if (v === undefined)
+        return undefined;
+    if (typeof v !== "object")
+        throw new OptionsError(`${key} must be a section with indented keys under it`);
+    return v;
+}
+/** 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", "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}"`);
+    const name = str(tree, "name", env);
+    if (name)
+        o.name = name;
+    const signup = str(tree, "signup", env);
+    if (signup !== undefined) {
+        if (!["open", "closed", "invite"].includes(signup))
+            throw new OptionsError(`signup must be open, closed or invite, not "${signup}"`);
+        o.signup = signup;
+    }
+    const invite = str(tree, "inviteCode", env);
+    if (invite)
+        o.inviteCode = invite;
+    const domain = str(tree, "emailDomain", env);
+    if (domain)
+        o.emailDomain = domain;
+    const rv = str(tree, "requireVerified", env);
+    if (rv !== undefined) {
+        if (!/^(true|false)$/i.test(rv))
+            throw new OptionsError(`requireVerified must be true or false`);
+        o.requireVerified = truthy(rv);
+    }
+    const days = str(tree, "sessionDays", env);
+    if (days !== undefined) {
+        if (!/^\d+$/.test(days) || Number(days) < 1)
+            throw new OptionsError(`sessionDays must be a whole number of days`);
+        o.sessionDays = Number(days);
+    }
+    for (const key of ["protected", "public"]) {
+        const v = str(tree, key, env);
+        if (v === undefined)
+            continue;
+        o[key] = words(v);
+        for (const p of o[key])
+            if (!p.startsWith("/"))
+                throw new OptionsError(`${key} paths start with /, not "${p}"`);
+    }
+    if (o.protected?.length && o.public?.length) {
+        throw new OptionsError("use either protected: (only these need sign-in) or public: (everything but these), not both");
+    }
+    const admins = str(tree, "admins", env);
+    if (admins !== undefined) {
+        o.admins = words(admins).map((e) => e.toLowerCase());
+        for (const a of o.admins)
+            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;
+    const secret = str(tree, "secret", env);
+    if (secret)
+        o.secret = secret;
+    const email = section(tree, "email");
+    if (email) {
+        const e = {};
+        const from = str(email, "from", env);
+        if (from)
+            e.from = from;
+        const replyTo = str(email, "replyTo", env);
+        if (replyTo)
+            e.replyTo = replyTo;
+        const gmail = section(email, "gmail");
+        if (gmail) {
+            const user = str(gmail, "user", env);
+            if (!user)
+                throw new OptionsError("email.gmail needs `user: <mailbox to send as>`");
+            e.gmail = {
+                user,
+                clientEmail: str(gmail, "clientEmail", env),
+                privateKey: str(gmail, "privateKey", env),
+                clientId: str(gmail, "clientId", env),
+                clientSecret: str(gmail, "clientSecret", env),
+                refreshToken: str(gmail, "refreshToken", env),
+            };
+        }
+        const resend = section(email, "resend");
+        if (resend) {
+            const apiKey = str(resend, "apiKey", env);
+            if (!apiKey)
+                throw new OptionsError("email.resend needs `apiKey: ${AUTH_RESEND_API_KEY}`");
+            e.resend = { apiKey };
+        }
+        o.email = e;
+    }
+    const perms = section(tree, "permissions");
+    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) {
+    const map = {};
+    for (const [role, v] of Object.entries(tree)) {
+        if (isEmpty(v)) {
+            map[role] = []; // `member:` with nothing: a role that exists and may do nothing yet
+            continue;
+        }
+        if (typeof v !== "string")
+            throw new OptionsError(`${where}.${role} must be a list of permissions separated by spaces`);
+        map[role] = normalizePermissions(words(interpolate(v, env, `${where}.${role}`)));
+    }
+    return map;
+}
+// ── merge ─────────────────────────────────────────────────────
+/** 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: {}, pages: {}, permissions: {}, roles: {} };
+    for (const layer of layers) {
+        for (const [k, v] of Object.entries(layer)) {
+            if (v === undefined)
+                continue;
+            if (k === "email" || k === "pages" || k === "permissions" || k === "roles")
+                Object.assign(out[k], v);
+            else
+                out[k] = v;
+        }
+    }
+    return out;
+}
+// ── loading ───────────────────────────────────────────────────
+let cache = null;
+/**
+ * Read b17_auth.yaml from the project root (the directory the server was
+ * started in), or from AUTH_CONFIG when that is set, and merge with env.
+ * Memoized; re-read in development when the file changes.
+ */
+export function loadOptions(cwd = process.cwd(), env = process.env) {
+    const path = env.AUTH_CONFIG ? (env.AUTH_CONFIG.startsWith("/") ? env.AUTH_CONFIG : join(cwd, env.AUTH_CONFIG)) : join(cwd, CONFIG_FILE);
+    const exists = existsSync(path);
+    const mtime = exists ? statSync(path).mtimeMs : 0;
+    if (cache && cache.path === path && (cache.options.production || cache.mtime === mtime))
+        return cache.options;
+    const file = exists ? parseYaml(readFileSync(path, "utf8")) : null;
+    const options = resolveOptions(file, env);
+    cache = { options, path, mtime };
+    return options;
+}
+/** The current options. What every handler reads. */
+export function options() {
+    return loadOptions();
+}
+/** Drop the memo (tests, CLI after writing the file). */
+export function resetOptions() {
+    cache = null;
+}

package/dist/core/org.d.ts

@@ -0,0 +1,43 @@
+import type { User } from "./session.ts";
+import type { SessionRow } from "./db.ts";
+export type Organization = {
+    id: string;
+    name: string;
+};
+export type Authorization = {
+    role: string | null;
+    permissions: string[];
+};
+export type Session = {
+    user: User;
+    organization: Organization | null;
+    authorization: Authorization;
+};
+/** 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;
+/**
+ * The check. Pure. A granted entry matches when it is
+ *   "*"            everything
+ *   "invoices.*"   any permission under that prefix ("invoices.view", "invoices.a.b")
+ *   exact          the permission itself
+ */
+export declare function hasPermission(session: Pick<Session, "authorization">, permission: string): boolean;
+/** What a signed-out client sees from the React side. The HTTP endpoint answers 401 instead. */
+export declare const NO_SESSION: {
+    user: null;
+    organization: null;
+    authorization: Authorization;
+};

package/dist/core/org.js

@@ -0,0 +1,65 @@
+// ─────────────────────────────────────────────────────────────
+// The session contract: one JSON shape for "who is this, where are
+// they, what may they do". Served by GET /auth/session and returned
+// by getSession() on the server. Three keys, nothing else.
+//
+//   user            { id, email }
+//   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"). What a role may do comes from the database,
+// the `roles` table, as set on /auth/admin:
+//
+//   scope = the organization's id   that organization's own rule for the role
+//   scope = ""                       the rule for every organization without its own
+//
+// 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 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 [];
+    if (role === OWNER)
+        return ["*"];
+    return stored.org ?? stored.all ?? [];
+}
+/** Build the contract from the store's row. Pure. */
+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 },
+    };
+}
+/**
+ * The check. Pure. A granted entry matches when it is
+ *   "*"            everything
+ *   "invoices.*"   any permission under that prefix ("invoices.view", "invoices.a.b")
+ *   exact          the permission itself
+ */
+export function hasPermission(session, permission) {
+    return session.authorization.permissions.some((granted) => granted === "*" || granted === permission || (granted.endsWith(".*") && permission.startsWith(granted.slice(0, -1))));
+}
+/** What a signed-out client sees from the React side. The HTTP endpoint answers 401 instead. */
+export const NO_SESSION = {
+    user: null,
+    organization: null,
+    authorization: { role: null, 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;