@binary1702/auth 0.2.4 → 0.3.0

package/dist/core/admin-html.js

@@ -0,0 +1,252 @@
+// ─────────────────────────────────────────────────────────────
+// 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
+//   ?tab=users            every user: verification, memberships, actions
+//   ?tab=settings         the resolved settings, read-only
+//
+// 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 { SIGN_OUT_PATH } from "./config.js";
+import { PASSWORD_MAX, PASSWORD_MIN } from "./signup.js";
+import { 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; } }
+  * { box-sizing: border-box; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.45 system-ui, -apple-system, sans-serif; }
+  main { max-width: 960px; margin: 0 auto; padding: 24px 20px 60px; }
+  h1 { font-size: 18px; margin: 0; }
+  h2 { font-size: 15px; margin: 0 0 10px; }
+  a { color: var(--accent); text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  .top { display: flex; gap: 14px; align-items: baseline; flex-wrap: wrap; margin-bottom: 14px; }
+  .top .who { color: var(--muted); font-size: 13px; margin-left: auto; }
+  .tabs { display: flex; gap: 4px; border-bottom: 1px solid var(--line); margin-bottom: 18px; }
+  .tabs a { padding: 8px 12px; color: var(--muted); border-bottom: 2px solid transparent; font-weight: 500; }
+  .tabs a.on { color: var(--fg); border-bottom-color: var(--fg); }
+  .tabs a:hover { text-decoration: none; color: var(--fg); }
+  .crumb { font-size: 13px; color: var(--muted); margin-bottom: 10px; }
+  .notice, .error { padding: 8px 12px; border-radius: 8px; font-size: 13px; margin: 0 0 14px; }
+  .notice { background: color-mix(in srgb, var(--ok) 12%, var(--bg)); color: var(--ok); }
+  .error { background: color-mix(in srgb, var(--err) 12%, var(--bg)); color: var(--err); }
+  .card { border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; margin-bottom: 16px; }
+  .card.panel { background: var(--panel); }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th { text-align: left; color: var(--muted); font-weight: 500; padding: 4px 10px 8px 0; }
+  td { padding: 9px 10px 9px 0; border-top: 1px solid var(--line); vertical-align: middle; }
+  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); }
+  .ok { color: var(--ok); }
+  .warn { color: var(--err); }
+  .right { text-align: right; white-space: nowrap; }
+  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; }
+  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); }
+  .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); }
+  details summary { cursor: pointer; color: var(--muted); font-size: 13px; }
+  details.inline { display: inline-block; vertical-align: middle; margin-right: 6px; }
+  details.inline summary { display: inline-block; font-size: 12.5px; padding: 5px 10px; border: 1px solid transparent; border-radius: 6px; list-style: none; }
+  details.inline summary::-webkit-details-marker { display: none; }
+  details.inline[open] summary { color: var(--fg); }
+  details.inline form { margin-left: 4px; }
+  .nowrap { white-space: nowrap; }
+  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; }
+`;
+const hidden = (fields) => Object.entries(fields)
+    .map(([k, v]) => `<input type="hidden" name="${escape(k)}" value="${escape(v)}">`)
+    .join("");
+const roleSelect = (name, roles, current) => `<select name="${name}">${roles.map((r) => `<option value="${escape(r)}"${r === current ? " selected" : ""}>${escape(r)}</option>`).join("")}</select>`;
+// The CSP allows no inline handlers; a nonce'd script below wires these up
+const confirmRemove = (what) => `data-confirm="Remove ${escape(what)}? This cannot be undone."`;
+const chips = (perms) => perms.length ? perms.map((p) => (p === "*" ? `<span class="chip all">everything</span>` : `<span class="chip">${escape(p)}</span>`)).join("") : `<span class="chip">nothing</span>`;
+export function adminPage(d) {
+    const usersPath = `${ADMIN_PATH}/users`;
+    const orgsPath = `${ADMIN_PATH}/orgs`;
+    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)}`;
+    let body = "";
+    // ── organizations ───────────────────────────────────────────
+    if (d.view.tab === "orgs") {
+        const rows = d.orgs
+            .map((org) => {
+            const roles = [...new Set(org.members.map((m) => m.role))];
+            return `<tr class="row">
+  <td><a href="${orgLink(org.id)}"><b>${escape(org.name)}</b></a><br><code class="muted">${escape(org.id)}</code></td>
+  <td>${org.members.length} member${org.members.length === 1 ? "" : "s"}</td>
+  <td>${roles.length ? roles.map((r) => `<span class="pill">${escape(r)}</span>`).join(" ") : '<span class="muted">none yet</span>'}</td>
+  <td class="right"><a href="${orgLink(org.id)}">open →</a></td>
+</tr>`;
+        })
+            .join("\n");
+        body = `
+<div class="card">
+<h2>Organizations <span class="muted">(${d.orgs.length})</span></h2>
+${d.orgs.length ? `<table><thead><tr><th>organization</th><th>members</th><th>roles in use</th><th></th></tr></thead><tbody>${rows}</tbody></table>` : '<p class="empty">No organizations yet. Create the first one below.</p>'}
+</div>
+<div class="card panel">
+<form class="grid" method="post" action="${orgsPath}">${hidden({ action: "create" })}
+  <label>New organization <input name="name" required autocomplete="off" placeholder="name"></label>
+  <button type="submit" class="primary">Create</button>
+</form>
+</div>`;
+    }
+    // ── one organization ────────────────────────────────────────
+    if (d.view.tab === "org") {
+        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>`;
+        }
+        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 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="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>'}
+</div>
+<div class="card">
+<h2>Members <span class="muted">(${org.members.length})</span></h2>
+${memberRows ? `<table><thead><tr><th>user</th><th>role</th><th>permissions here</th><th></th></tr></thead><tbody>${memberRows}</tbody></table>` : '<p class="empty">No members yet.</p>'}
+</div>
+<div class="card panel">
+<form class="grid" method="post" action="${orgsPath}">${hidden({ action: "add-member", org: org.id })}
+  <label>Add a member <input type="email" name="email" placeholder="email of an existing user" required></label>
+  <label>as ${roleSelect("role", d.roles, "member")}</label>
+  <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>`;
+        }
+    }
+    // ── users ───────────────────────────────────────────────────
+    if (d.view.tab === "users") {
+        const rows = d.users
+            .map((u) => {
+            const self = u.email === d.self;
+            const memberships = u.memberships.length
+                ? u.memberships.map((m) => `<a href="${orgLink(m.org_id)}">${escape(m.org)}</a> <span class="muted">(${escape(m.role)})</span>`).join(" · ")
+                : '<span class="muted">none</span>';
+            const status = u.verified
+                ? '<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>`;
+            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>
+  <td>${memberships}</td>
+  <td class="right">
+    <details class="inline"><summary class="quiet">password</summary><form class="inline" method="post" action="${usersPath}">${hidden({ action: "set-password", email: u.email, tab: "users" })}<input type="password" name="password" placeholder="new password" minlength="${PASSWORD_MIN}" maxlength="${PASSWORD_MAX}" required autocomplete="new-password" size="14"><button type="submit">set</button></form></details>
+    ${self
+                ? ""
+                : `<form class="inline" method="post" action="${usersPath}">${hidden({ action: "sign-out", email: u.email, tab: "users" })}<button type="submit" class="quiet">sign out</button></form>
+    <form class="inline" method="post" action="${usersPath}" ${confirmRemove(u.email)}>${hidden({ action: "remove", email: u.email, tab: "users" })}<button type="submit" class="quiet danger">remove</button></form>`}
+  </td>
+</tr>`;
+        })
+            .join("\n");
+        body = `
+<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>
+</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>
+</form>
+</div>`;
+    }
+    // ── settings ────────────────────────────────────────────────
+    if (d.view.tab === "settings") {
+        const permissionRows = Object.entries(o.permissions)
+            .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>
+<table><tbody>
+<tr><td>name</td><td>${escape(o.name || "(none: the request's host)")}</td></tr>
+<tr><td>signup</td><td>${escape(o.signup)}${o.emailDomain ? ` · only @${escape(o.emailDomain)}` : ""}</td></tr>
+<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>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>
+</div>`;
+    }
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Admin${o.name ? ` · ${escape(o.name)}` : ""}</title>
+<style>${STYLE}</style>
+</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">
+  <a href="${link("orgs")}" class="${tab === "orgs" ? "on" : ""}">Organizations</a>
+  <a href="${link("users")}" class="${tab === "users" ? "on" : ""}">Users</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>` : ""}
+${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() })
+}
+</script>
+</body>
+</html>`;
+}

package/dist/core/admin.d.ts

@@ -0,0 +1,26 @@
+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;
+/** 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"];
+export declare const ORG_ACTIONS: readonly ["create", "add-member", "set-role", "remove-member", "remove-org"];
+export type UserAction = (typeof USER_ACTIONS)[number];
+export type OrgAction = (typeof ORG_ACTIONS)[number];
+export declare const isUserAction: (a: string) => a is UserAction;
+export declare const isOrgAction: (a: string) => a is OrgAction;
+/**
+ * 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
+ * sessions, and the page signs them in again.)
+ */
+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.
+ */
+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. */
+export declare function roleChoices(defined: readonly string[], inUse: readonly string[]): string[];

package/dist/core/admin.js

@@ -0,0 +1,48 @@
+// ─────────────────────────────────────────────────────────────
+// The admin page's rules. Pure.
+//
+//   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.
+//
+// An admin is an email, not a role: a role lives in one organization,
+// the admin page spans all of them.
+// ─────────────────────────────────────────────────────────────
+export const ADMIN_PATH = "/auth/admin";
+export function isAdmin(session, admins) {
+    return !!session && admins.includes(session.user.email.toLowerCase());
+}
+/** 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"];
+export const ORG_ACTIONS = ["create", "add-member", "set-role", "remove-member", "remove-org"];
+export const isUserAction = (a) => USER_ACTIONS.includes(a);
+export const isOrgAction = (a) => ORG_ACTIONS.includes(a);
+/**
+ * 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
+ * sessions, and the page signs them in again.)
+ */
+export function refusedOnSelf(action, targetEmail, selfEmail) {
+    if (targetEmail.toLowerCase() !== selfEmail.toLowerCase())
+        return null;
+    if (action === "remove")
+        return "You cannot remove the account you are signed in with.";
+    if (action === "sign-out")
+        return "Use /auth/sign-out to end your own session.";
+    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.
+ */
+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")
+        return `tab=${fields.tab}`;
+    return "";
+}
+/** Roles the page offers in its dropdowns: whatever the yaml defines, plus any role already in use. */
+export function roleChoices(defined, inUse) {
+    return [...new Set(["owner", "admin", "member", ...defined, ...inUse])];
+}

package/dist/core/config.d.ts

@@ -1,8 +1,15 @@
 export declare const COOKIE_NAME = "auth_session";
+/**
+ * In production the cookie carries the __Host- prefix: the browser then
+ * refuses it unless it is Secure, has Path=/ and no Domain, so a
+ * subdomain or a plain-http page cannot plant one. Pure.
+ */
+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";
 export declare const SIGN_OUT_PATH = "/auth/sign-out";
 export declare const SIGN_UP_PATH = "/auth/sign-up";
-export declare const TABLE = "auth_users";
+export declare const TABLE = "users";
 export declare function getSecret(): string;
 export declare function getDatabaseUrl(): string;

package/dist/core/config.js

@@ -1,24 +1,38 @@
 // ─────────────────────────────────────────────────────────────
-// Configuration. Two env vars, nothing else.
+// Constants, and the two values nothing works without.
 //
-//   DATABASE_URL  Postgres connection string (Neon)
-//   AUTH_SECRET   signs the session cookie; generated by the CLI
+// Everything configurable comes from core/options.ts: b17_auth.yaml
+// with ${NAME} references, or the env vars on their own:
+//
+//   DATABASE_URL   Postgres connection string (Neon)      required
+//   AUTH_SECRET    signs the session cookie               generated by the CLI
+//   the rest       see core/options.ts
 // ─────────────────────────────────────────────────────────────
+import { options } from "./options.js";
 export const COOKIE_NAME = "auth_session";
+/**
+ * In production the cookie carries the __Host- prefix: the browser then
+ * refuses it unless it is Secure, has Path=/ and no Domain, so a
+ * subdomain or a plain-http page cannot plant one. Pure.
+ */
+export function cookieName(production) {
+    return production ? `__Host-${COOKIE_NAME}` : COOKIE_NAME;
+}
+/** The default; b17_auth.yaml `sessionDays` overrides it */
 export const SESSION_DAYS = 7;
 export const SIGN_IN_PATH = "/auth/sign-in";
 export const SIGN_OUT_PATH = "/auth/sign-out";
 export const SIGN_UP_PATH = "/auth/sign-up";
-export const TABLE = "auth_users";
+export const TABLE = "users";
 export function getSecret() {
-    const secret = process.env.AUTH_SECRET;
+    const secret = options().secret;
     if (!secret || secret.length < 16) {
         throw new Error("AUTH_SECRET is missing. Run: npx @binary1702/auth");
     }
     return secret;
 }
 export function getDatabaseUrl() {
-    const url = process.env.DATABASE_URL;
+    const url = options().database;
     if (!url) {
         throw new Error("DATABASE_URL is missing. Run: npx @binary1702/auth");
     }

package/dist/core/db.d.ts

@@ -1,16 +1,147 @@
 import { TABLE } from "./config.ts";
 import type { User } from "./session.ts";
-export declare function ensureSchema(): Promise<void>;
-type Row = {
+export type Statement = {
+    text: string;
+    params?: unknown[];
+};
+/** What the package needs from a database: parameterised queries, and a transaction if it has one. */
+export interface Db {
+    query<T = Record<string, unknown>>(text: string, params?: unknown[]): Promise<T[]>;
+    /** Run statements in one transaction. A store without it runs them one by one. */
+    transaction?(statements: Statement[]): Promise<void>;
+}
+/** The real store, created once per process from DATABASE_URL. */
+export declare function db(): Db;
+export type Migration = {
+    id: number;
+    name: string;
+    statements: string[];
+};
+/**
+ * Ordered, append-only. Never edit a step that has shipped: add a new
+ * one. Step 1 is the 0.2.5 schema exactly, so an existing install
+ * applies it as a no-op through IF NOT EXISTS.
+ */
+export declare const MIGRATIONS: Migration[];
+/**
+ * The package's tables have plain names (users, orgs, members, tokens).
+ * A database that already holds a `users` table of its own would be
+ * silently shared by CREATE TABLE IF NOT EXISTS, so a fresh install
+ * checks first. Pure: decides from what the store reports.
+ */
+export declare function foreignUsersTable(columns: string[]): boolean;
+export declare const FOREIGN_USERS_TABLE = "This database already has a `users` table that is not this package's. Point DATABASE_URL at a database (or Postgres schema) of its own.";
+/** The steps still to run, in order. Pure. */
+export declare function pendingSteps(applied: number[], steps?: Migration[]): Migration[];
+/** Everything a pending step needs to run, including recording that it ran. Pure. */
+export declare function migrationStatements(steps: Migration[]): Statement[];
+/**
+ * Apply pending migrations. Memoized per store and per process, so
+ * route handlers can call it on every request for free after the first.
+ * A failure clears the memo so the next call retries.
+ */
+export declare function ensureSchema(store?: Db): Promise<void>;
+export type UserRow = {
     id: string;
     email: string;
     password_hash: string;
+    epoch: number;
+    /** When the email was verified, or null */
+    verified_at: string | Date | null;
+};
+export declare function findUser(email: string, store?: Db): Promise<UserRow | null>;
+/** Two sign-ups raced on one email and the second lost: the handler answers 409. */
+export declare class DuplicateUserError extends Error {
+    constructor(email: string);
+}
+/** Postgres's unique_violation */
+export declare const isUniqueViolation: (err: unknown) => boolean;
+export declare function createUser(email: string, passwordHash: string, opts?: {
+    verified?: boolean;
+}, store?: Db): Promise<User & {
+    epoch: number;
+    verified: boolean;
+}>;
+/** Replace a hash with one made under stronger parameters. No epoch bump: nothing about the session changes. */
+export declare function rehashPassword(id: string, passwordHash: string, store?: Db): Promise<void>;
+/** What a session check needs about the user: current epoch and verification. Null if the user is gone. */
+export type UserState = {
+    epoch: number;
+    verified: boolean;
+};
+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. */
+export type SessionRow = UserState & {
+    id: string;
+    email: string;
+    org_id: string | null;
+    org_name: string | null;
+    role: string | null;
+};
+export declare function sessionRow(id: string, store?: Db): Promise<SessionRow | null>;
+export type OrgRow = {
+    id: string;
+    name: string;
+    created_at: string;
+};
+export declare function createOrg(name: string, store?: Db): Promise<OrgRow>;
+/** By id (UUID) or exact name. Null if there is no such organization. */
+export declare function findOrg(idOrName: string, store?: Db): Promise<OrgRow | null>;
+export declare function listOrgs(store?: Db): Promise<(OrgRow & {
+    members: number;
+})[]>;
+/** Add or update a membership. Becomes the user's active org if they had none. */
+export declare function addMember(orgId: string, userId: string, role: string, store?: Db): Promise<void>;
+export declare function removeMember(orgId: string, userId: string, store?: Db): Promise<boolean>;
+export declare function removeOrg(orgId: string, store?: Db): Promise<boolean>;
+export type Membership = {
+    org_id: string;
+    org: string;
+    role: string;
+};
+export type AdminUser = {
+    id: string;
+    email: string;
+    created_at: string;
+    verified: boolean;
+    memberships: Membership[];
+};
+export type AdminOrg = {
+    id: string;
+    name: string;
+    created_at: string;
+    members: {
+        user_id: string;
+        email: string;
+        role: string;
+    }[];
 };
-export declare function findUser(email: string): Promise<Row | null>;
-export declare function createUser(email: string, passwordHash: string): Promise<User>;
-export declare function countUsers(): Promise<number>;
-export declare function listUsers(): Promise<(User & {
+/** Every user with their memberships, one query. */
+export declare function adminUsers(store?: Db): Promise<AdminUser[]>;
+/** Every organization with its members, one query. */
+export declare function adminOrgs(store?: Db): Promise<AdminOrg[]>;
+/** Switch the user's active organization. False unless they are a member of it: the client's choice is checked, never trusted. */
+export declare function setActiveOrg(userId: string, orgId: string, store?: Db): Promise<boolean>;
+/** Record that the user followed the verification link. Idempotent. Null if the user is gone. */
+export declare function markVerified(id: string, store?: Db): Promise<User | null>;
+/** Revoke every session of this user. False if there is no such user. */
+export declare function revokeSessions(email: string, store?: Db): Promise<boolean>;
+/** Delete the user. Their sessions die with the row. False if none. */
+export declare function removeUser(email: string, store?: Db): Promise<boolean>;
+export declare function countUsers(store?: Db): Promise<number>;
+export declare function listUsers(store?: Db): Promise<(User & {
     created_at: string;
 })[]>;
-export declare function setPassword(email: string, passwordHash: string): Promise<boolean>;
+/** Change a password. Also revokes every session, old password's included. */
+export declare function setPassword(email: string, passwordHash: string, store?: Db): Promise<boolean>;
+/**
+ * Same, by id, for a reset link. Also marks the email verified: following
+ * the link proved the address. Returns the user with the new epoch so the
+ * caller can sign them in; null if the user is gone.
+ */
+export declare function setPasswordById(id: string, passwordHash: string, store?: Db): Promise<(User & {
+    epoch: number;
+}) | null>;
 export { TABLE };