@binary1702/auth 0.2.5 → 0.4.0

package/dist/cli.js

@@ -10,7 +10,7 @@
 //   3. AUTH_SECRET   → generate, write .env.local
 //   4. app/auth/[...path]/route.ts
 //   5. proxy.ts
-//   6. create auth_users table
+//   6. create users table
 //   7. create the first user
 //
 // Subcommands:
@@ -19,6 +19,10 @@
 //   remove-user [email]           delete a user (signs them out everywhere)
 //   sign-out-everywhere [email]   end every session of a user
 //   list-users
+//   add-org <name>                create an organization
+//   add-member <email> <org> [role]   put a user in an org (role defaults to "member")
+//   remove-member <email> <org>
+//   list-orgs
 // ─────────────────────────────────────────────────────────────
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
 import { join, dirname } from "node:path";
@@ -77,7 +81,7 @@ function closePrompts() {
 }
 async function ask(question, opts = {}) {
     rl();
-    const suffix = opts.default ? c.dim(` (${opts.default})`) : "";
+    const suffix = opts.default ? c.dim(` (${opts.default})`) : opts.optional ? c.dim(" (Enter to skip)") : "";
     stdout.write(`  ${question}${suffix}: `);
     if (opts.hidden)
         muted = true;
@@ -90,8 +94,12 @@ async function ask(question, opts = {}) {
         muted = false;
         stdout.write("\n");
     }
-    if (line === null)
+    if (line === null) {
+        // Piped input that stops short: an optional prompt is simply skipped
+        if (opts.optional)
+            return "";
         return fail("Input ended before all prompts were answered.");
+    }
     return opts.hidden ? line : line.trim() || opts.default || "";
 }
 // ── env file ──────────────────────────────────────────────────
@@ -118,11 +126,14 @@ const PROXY_FILE = `import { proxy } from "${PKG}/next/proxy"
 
 export default proxy
 
-// Everything except the auth pages, Next internals, and static files.
+// Everything except Next's build output. The proxy itself lets the
+// auth pages and static files through.
 export const config = {
-  matcher: ["/((?!auth|_next/static|_next/image|favicon.ico|.*\\\\..*).*)"],
+  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
 }
 `;
+// Written by 0.2.5 and earlier: skipped /authors, /api/export.csv, …
+const OLD_MATCHER = "(?!auth|_next/static|_next/image|favicon.ico|.*";
 function writeIfMissing(rel, content) {
     const abs = join(cwd, rel);
     if (existsSync(abs)) {
@@ -156,7 +167,7 @@ function stepInstall() {
         fail(`npm install ${PKG} failed`);
     done(`${PKG} installed`);
 }
-async function stepEnv() {
+async function stepEnv(opts = {}) {
     const env = readEnv();
     if (env.DATABASE_URL) {
         process.env.DATABASE_URL = env.DATABASE_URL;
@@ -178,12 +189,88 @@ async function stepEnv() {
         writeEnv("AUTH_SECRET", randomBytes(32).toString("base64url"));
         done("AUTH_SECRET generated → .env.local");
     }
+    // Email: verification and password-reset links. Optional. Without it,
+    // development prints the emails to the console and production refuses
+    // to send, so the install still works. See core/email.ts.
+    for (const k of ["AUTH_GMAIL_USER", "AUTH_GMAIL_CLIENT_EMAIL", "AUTH_GMAIL_PRIVATE_KEY", "AUTH_RESEND_API_KEY", "AUTH_EMAIL_FROM"]) {
+        if (env[k])
+            process.env[k] = env[k];
+    }
+    if (env.AUTH_GMAIL_USER && env.AUTH_GMAIL_CLIENT_EMAIL && env.AUTH_GMAIL_PRIVATE_KEY) {
+        if (opts.askEmail)
+            skip("email: Gmail API as " + env.AUTH_GMAIL_USER);
+        return;
+    }
+    if (env.AUTH_RESEND_API_KEY && env.AUTH_EMAIL_FROM) {
+        if (opts.askEmail)
+            skip("email: Resend from " + env.AUTH_EMAIL_FROM);
+        return;
+    }
+    if (!opts.askEmail)
+        return; // subcommands only need the database
+    // Once b17_auth.yaml exists, email is configured there (its comments show how); stop asking
+    if (existsSync(join(cwd, CONFIG_FILE)))
+        return;
+    console.log(c.dim("  Email for verification and password reset. gmail = Gmail API with a service account,"));
+    console.log(c.dim("  resend = resend.com API key. Skip it for now if you like."));
+    const which = (await ask("Email transport (gmail / resend)", { optional: true })).toLowerCase();
+    if (which === "gmail") {
+        const user = await ask("Mailbox to send as (AUTH_GMAIL_USER)", { default: env.AUTH_GMAIL_USER });
+        if (!user.includes("@"))
+            fail("That does not look like an email address.");
+        const path = await ask("Path to the service account's JSON key file");
+        const abs = path.startsWith("/") ? path : join(cwd, path);
+        if (!existsSync(abs))
+            fail(`No file at ${abs}`);
+        let sa;
+        try {
+            sa = JSON.parse(readFileSync(abs, "utf8"));
+        }
+        catch {
+            return fail("That file is not JSON.");
+        }
+        if (!sa.client_email || !sa.private_key)
+            fail("That JSON has no client_email / private_key: it is not a service account key.");
+        writeEnv("AUTH_GMAIL_USER", user);
+        writeEnv("AUTH_GMAIL_CLIENT_EMAIL", sa.client_email);
+        // One line: the PEM's newlines as the two characters \n, which the package restores
+        writeEnv("AUTH_GMAIL_PRIVATE_KEY", sa.private_key.replace(/\n/g, "\\n"));
+        done(`AUTH_GMAIL_USER, AUTH_GMAIL_CLIENT_EMAIL, AUTH_GMAIL_PRIVATE_KEY → .env.local (${sa.client_email})`);
+        console.log(c.dim(`    In Google Admin, grant that service account domain-wide delegation for the scope:`));
+        console.log(c.dim(`    https://www.googleapis.com/auth/gmail.send`));
+        return;
+    }
+    if (which === "resend") {
+        const key = env.AUTH_RESEND_API_KEY || (await ask("Resend API key (AUTH_RESEND_API_KEY)", { hidden: true }));
+        if (!key.trim())
+            fail("No key given.");
+        const from = env.AUTH_EMAIL_FROM || (await ask("From address (AUTH_EMAIL_FROM)", { default: "Auth <onboarding@resend.dev>" }));
+        if (!env.AUTH_RESEND_API_KEY)
+            writeEnv("AUTH_RESEND_API_KEY", key.trim());
+        if (!env.AUTH_EMAIL_FROM)
+            writeEnv("AUTH_EMAIL_FROM", from);
+        done("AUTH_RESEND_API_KEY, AUTH_EMAIL_FROM → .env.local");
+        return;
+    }
+    if (which)
+        fail(`Unknown transport "${which}". Use gmail, resend, or press Enter to skip.`);
+    skip("email not configured: dev prints emails to the console");
 }
 function stepFiles(appDir, src) {
     writeIfMissing(`${appDir}/auth/[...path]/route.ts`, ROUTE_FILE);
     const proxyPath = src ? "src/proxy.ts" : "proxy.ts";
     const legacy = [src ? "src/middleware.ts" : "middleware.ts", proxyPath].filter((p) => existsSync(join(cwd, p)));
     if (legacy.length) {
+        const text = readFileSync(join(cwd, legacy[0]), "utf8");
+        if (text.includes(`${PKG}/next/proxy`) && !text.includes(OLD_MATCHER)) {
+            skip(`${legacy[0]} exists`); // ours, current: nothing to say
+            return;
+        }
+        if (text.includes(OLD_MATCHER)) {
+            console.log(`  ${c.red("!")} ${legacy[0]} has the old matcher, which leaves /auth* and dotted paths unguarded.`);
+            console.log(`    Replace its matcher with: ${c.bold('["/((?!_next/static|_next/image|favicon.ico).*)"]')}`);
+            return;
+        }
         skip(`${legacy[0]} exists, not touched. Add to it:`);
         console.log(c.dim(PROXY_FILE.replace(/^/gm, "      ")));
         return;
@@ -194,10 +281,109 @@ async function db() {
     // Imported lazily: needs DATABASE_URL in process.env first.
     return import("./core/db.js");
 }
+// ── b17_auth.yaml ─────────────────────────────────────────────
+const CONFIG_FILE = "b17_auth.yaml";
+function appName() {
+    try {
+        const name = String(JSON.parse(readFileSync(join(cwd, "package.json"), "utf8")).name ?? "");
+        return name.replace(/^@[^/]+\//, "").replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+    }
+    catch {
+        return "My App";
+    }
+}
+/** The file the install writes once. Secrets are ${…} references into .env.local. */
+function configTemplate(env) {
+    const gmail = env.AUTH_GMAIL_USER && env.AUTH_GMAIL_CLIENT_EMAIL && env.AUTH_GMAIL_PRIVATE_KEY;
+    const resend = env.AUTH_RESEND_API_KEY;
+    const from = env.AUTH_EMAIL_FROM || (gmail ? env.AUTH_GMAIL_USER : "");
+    return `# ${CONFIG_FILE}  ·  @binary1702/auth
+# One place for all of it. Secrets stay in .env.local and appear here as \${NAME}.
+# Docs: https://www.npmjs.com/package/@binary1702/auth#b17_authyaml
+
+name: ${appName()}                                    # page titles, email subjects
+signup: closed                                       # open | closed | invite  (invite also needs inviteCode)
+# inviteCode: \${AUTH_INVITE_CODE}
+# emailDomain: example.com                            # only these addresses may sign up
+# requireVerified: true                               # no session until the email link is clicked
+# protected: /app/* /api/*                           # only these need sign-in; everything else is open. * = anything below
+#                                                    # (or the reverse: public: / /pricing  = everything needs sign-in except these)
+# admins: you@example.com                            # who may open /auth/admin (users, organizations, roles)
+# home: /app                                         # the signed-in home: after sign-in, and where a signed-in visitor to / goes
+# pages:                                             # your own sign-in / sign-up pages instead of the built-in ones;
+#   signIn: /sign-in                                 # they call signIn() / signUp() from @binary1702/auth/react
+#   signUp: /sign-up
+
+database: \${DATABASE_URL}
+secret: \${AUTH_SECRET}
+
+email:
+${from ? `  from: ${from}` : "  # from: NoReply (My App) <no-reply@example.com>"}
+  # replyTo: support@example.com
+${gmail
+        ? `  gmail:
+    user: ${env.AUTH_GMAIL_USER}                       # the mailbox the service account acts as
+    clientEmail: \${AUTH_GMAIL_CLIENT_EMAIL}
+    privateKey: \${AUTH_GMAIL_PRIVATE_KEY}`
+        : resend
+            ? `  resend:
+    apiKey: \${AUTH_RESEND_API_KEY}`
+            : `  # gmail:                                           # one of the two; see the README
+  #   user: you@example.com
+  #   clientEmail: \${AUTH_GMAIL_CLIENT_EMAIL}
+  #   privateKey: \${AUTH_GMAIL_PRIVATE_KEY}
+  # resend:
+  #   apiKey: \${AUTH_RESEND_API_KEY}`}
+
+# permissions:                                       # what the app gates: id: label. The rows on /auth/admin › Roles
+#   invoices.read: See invoices
+#   invoices.create: Create invoices
+
+roles:                                                # role: what it may do to start with. all = everything, x.* = a prefix
+  owner: all                                          # (/auth/admin › Roles saves changes in the database)
+  admin: all
+  member:
+`;
+}
+async function stepConfig() {
+    const abs = join(cwd, CONFIG_FILE);
+    if (existsSync(abs)) {
+        const { parseYaml } = await import("./core/yaml.js");
+        const { literalSecrets } = await import("./core/options.js");
+        let bad = [];
+        try {
+            bad = literalSecrets(parseYaml(readFileSync(abs, "utf8")));
+        }
+        catch (e) {
+            fail(`${CONFIG_FILE}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        if (bad.length) {
+            const ignored = spawnSync("git", ["check-ignore", "-q", CONFIG_FILE], { cwd }).status === 0;
+            if (!ignored) {
+                fail(`${CONFIG_FILE} holds a literal secret under ${bad.join(", ")}. Move it to .env.local and reference it as \${NAME}, or git-ignore the file.`);
+            }
+        }
+        skip(`${CONFIG_FILE} exists`);
+        return;
+    }
+    writeFileSync(abs, configTemplate(readEnv()));
+    done(`${CONFIG_FILE} written: app name, sign-up policy, email, permissions`);
+}
+/** The roles from b17_auth.yaml, written into the database once. A role the admin page already saved is left alone. */
+async function stepRoles() {
+    const { seedRoles } = await db();
+    const { options, resetOptions } = await import("./core/options.js");
+    resetOptions(); // the file may have been written a step ago
+    const written = await seedRoles(options().roles);
+    if (written.length)
+        done(`roles written to the database: ${written.join(", ")}  ${c.dim("(the starting point; /auth/admin › Roles decides from here)")}`);
+    else
+        skip("roles already in the database");
+}
 async function stepSchema() {
-    const { ensureSchema } = await db();
+    const { ensureSchema, MIGRATIONS } = await db();
     await ensureSchema().catch((e) => fail(`Could not reach the database: ${e.message}`));
-    done("auth_users table ready");
+    done(`database schema ready (${MIGRATIONS.length} migration${MIGRATIONS.length === 1 ? "" : "s"})`);
 }
 async function createUserInteractive(presetEmail) {
     const { createUser, findUser } = await db();
@@ -213,7 +399,8 @@ async function createUserInteractive(presetEmail) {
     const again = await ask("Password again", { hidden: true });
     if (password !== again)
         fail("Passwords do not match.");
-    await createUser(email, await hashPassword(password));
+    // Created by whoever runs the CLI: no verification email to wait for
+    await createUser(email, await hashPassword(password), { verified: true });
     done(`user "${email}" created`);
 }
 async function stepFirstUser() {
@@ -230,15 +417,15 @@ function finish() {
     console.log(`
 ${c.bold("Done.")} Start the dev server and open ${c.bold("/auth/sign-in")}.
 
-Get the user in any route or server component:
+Get the session in any route, server component or action:
 
-  import { requireUser } from "${PKG}/next"
-  const user = await requireUser()   // { id, email }
+  import { getSession, requirePermission } from "${PKG}/next"
+  const session = await getSession()   // { user, organization, authorization } or null
 
-Add users later:  npx ${PKG} add-user
-Or let people register themselves at /auth/sign-up:
-  AUTH_SIGNUP=open            in .env.local (anyone)
-  AUTH_INVITE_CODE=<code>     optional, the form then needs it
+Settings live in ${c.bold(CONFIG_FILE)}: app name, who may sign up (signup: open | invite),
+which paths need sign-in (protected:), email, roles → permissions. Secrets stay in .env.local.
+Add users later:  npx ${PKG} add-user     Organizations:  npx ${PKG} add-org <name>
+Working with an AI agent in this app? Point it at node_modules/${PKG}/AGENTS.md
 `);
 }
 // ── main ──────────────────────────────────────────────────────
@@ -252,11 +439,53 @@ async function main() {
   npx ${PKG} remove-user [email]           delete; also signs them out everywhere
   npx ${PKG} sign-out-everywhere [email]   end every session of a user
   npx ${PKG} list-users
+
+  npx ${PKG} add-org <name>                     create an organization
+  npx ${PKG} add-member <email> <org> [role]    add a user to an org (role: member, admin, owner, …)
+  npx ${PKG} remove-member <email> <org>
+  npx ${PKG} list-orgs
 `);
         return;
     }
     stepProject();
     const USER_CMDS = ["add-user", "set-password", "remove-user", "sign-out-everywhere", "list-users"];
+    const ORG_CMDS = ["add-org", "add-member", "remove-member", "list-orgs"];
+    if (ORG_CMDS.includes(cmd)) {
+        await stepEnv();
+        const d = await db();
+        const [, email, orgName, role] = process.argv.slice(2);
+        const org = async (name) => {
+            if (!name)
+                fail(`Usage: npx ${PKG} ${cmd} <email> <org>`);
+            return (await d.findOrg(name)) ?? fail(`No organization "${name}". Create it: npx ${PKG} add-org "${name}"`);
+        };
+        const user = async (e) => {
+            if (!e)
+                fail(`Usage: npx ${PKG} ${cmd} <email> <org>`);
+            return (await d.findUser(e)) ?? fail(`No user "${e}".`);
+        };
+        if (cmd === "add-org") {
+            if (!arg)
+                fail(`Usage: npx ${PKG} add-org <name>`);
+            const o = await d.createOrg(arg);
+            done(`organization "${o.name}" created  ${c.dim(o.id)}`);
+        }
+        if (cmd === "list-orgs") {
+            for (const o of await d.listOrgs())
+                console.log(`  ${o.name}  ${c.dim(o.id)}  ${o.members} member${o.members === 1 ? "" : "s"}`);
+        }
+        if (cmd === "add-member") {
+            const [u, o] = [await user(email), await org(orgName)];
+            await d.addMember(o.id, u.id, role || "member");
+            done(`"${u.email}" is ${role || "member"} of "${o.name}"`);
+        }
+        if (cmd === "remove-member") {
+            const [u, o] = [await user(email), await org(orgName)];
+            (await d.removeMember(o.id, u.id)) ? done(`"${u.email}" removed from "${o.name}"`) : fail(`"${u.email}" is not a member of "${o.name}".`);
+        }
+        console.log();
+        return;
+    }
     if (USER_CMDS.includes(cmd)) {
         await stepEnv();
         const d = await db();
@@ -295,9 +524,11 @@ async function main() {
         fail(`Unknown command "${cmd}". Try: npx ${PKG} help`);
     const { appDir, src } = stepProject();
     stepInstall();
-    await stepEnv();
+    await stepEnv({ askEmail: true });
     stepFiles(appDir, src);
+    await stepConfig();
     await stepSchema();
+    await stepRoles();
     await stepFirstUser();
     finish();
 }

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

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