@madauth/server 0.3.0-beta.2 → 0.5.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # @madauth/server
 
-The server of [madAuth](https://github.com/inouiw/madAuth), a self-hostable alternative to Cognito / Auth0: Google and e-mail & password sign-in with madAuth sessions. It runs with Node, in Docker, on AWS Lambda, on Azure Functions or inside your own Node server.
+The server of [madAuth](https://github.com/inouiw/madAuth), a self-hostable alternative to Cognito / Auth0: Google, GitHub, e-mail & password, e-mail link and authenticator-app (TOTP) sign-in with madAuth sessions. It runs with Node, in Docker, on AWS Lambda, on Azure Functions or inside your own Node server.
 
 The browser side is [`@madauth/web`](https://www.npmjs.com/package/@madauth/web).
 
@@ -53,7 +53,8 @@ The package also contains self-contained bundles for AWS Lambda (`dist/standalon
 ## Documentation
 
 - [Getting started](https://github.com/inouiw/madAuth/blob/main/docs/getting-started.md): set up madAuth on your machine, step by step.
-- [Running the madAuth server](https://github.com/inouiw/madAuth/blob/main/docs/server.md): the configuration, Google Cloud Console setup, webhooks, hosting and custom store adapters.
+- [Running the madAuth server](https://github.com/inouiw/madAuth/blob/main/docs/server.md): the configuration, Google Cloud Console setup, the sign-in methods and their policies, the authenticator app, webhooks, hosting and custom store adapters.
+- [Password security](https://github.com/inouiw/madAuth/blob/main/docs/password-security.md) and [Authenticator app security](https://github.com/inouiw/madAuth/blob/main/docs/totp-security.md): what the server does to protect accounts.
 
 ## License
 

package/dist/bin.js

@@ -2,35 +2,45 @@
 import {
   createTablesSql,
   upgradeTablesSql
-} from "./chunk-56MOVFO4.js";
+} from "./chunk-O2URPWA6.js";
 import {
   madauthSchema
-} from "./chunk-CD7Y4T66.js";
+} from "./chunk-NP75Y3IV.js";
 import {
+  DEFAULT_PASSWORD_RULES,
+  MAX_MIN_LENGTH,
+  METHODS,
+  SECOND_FACTOR_POLICIES,
   SIGN_IN_METHODS,
   Settings,
   Users,
   anyOn,
+  canSignUp,
   checkPasswordPolicy,
   claimsFromJson,
+  hasSecondFactor,
   hashPassword,
+  initialMethods,
+  isConfigured,
   isOn,
+  isPasswordScore,
   isValidEmail,
   loadConfig,
   loadStore,
-  loadUserStoreConfig,
+  methodConfig,
   normalizeEmail,
   parseClaims,
   parseRoles,
-  passwordAccountKey
-} from "./chunk-TI35AZ2U.js";
+  passwordAccountKey,
+  policyOf
+} from "./chunk-NYIEFI4B.js";
 import {
   generateSigningKey
 } from "./chunk-JDQLSL36.js";
 import {
   DEV_WEBHOOK_RECEIVER_URL,
   generateWebhookSecret
-} from "./chunk-3QRKWLR7.js";
+} from "./chunk-SISM7YUZ.js";
 
 // src/cli.ts
 import { existsSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -42,25 +52,44 @@ var usage = `Usage: npx @madauth/server <command> [--env-file <path>]
 Commands:
   init                         Ask a few questions, write the configuration to .env and print the next steps.
                                An answer given as an option is not asked for: --app-url <url>,
-                               --google-client-id <id>, --google-client-secret <secret>, --password or
-                               --no-password, --database <url>, --webhook-url <url>. --yes takes the
-                               default for the rest. --out <path> writes another file, --force overwrites.
+                               --google-client-id <id>, --google-client-secret <secret>,
+                               --github-client-id <id>, --github-client-secret <secret>, --password or
+                               --no-password, --totp or --no-totp (sign-up with the authenticator app),
+                               --email-link or --no-email-link (passwordless sign-in by e-mail),
+                               --sms or --no-sms (SMS codes as a second factor),
+                               --database <url>, --webhook-url <url>. --yes takes the default for the
+                               rest. --out <path> writes another file, --force overwrites.
   start                        Start the server on PORT (default ${PORT})
   generate-key                 Print a new private ES256 key to use as MADAUTH_SIGNING_KEY
   generate-webhook-secret      Print a new secret to use as WEBHOOK_SECRET (madAuth and your receiver)
-  create-user <email>          Create a user with a password (asks for it), already verified.
-                               Uses DATABASE_URL and PASSWORD_MIN_LENGTH from the environment.
+  create-user <email>          Create a user with a password (asks for it), already verified. The password
+                               must follow the password rules. Uses DATABASE_URL from the environment.
   set-roles <email> [role...]  Set the roles of a user (the claim "roles"), e.g. to make the first admin:
                                set-roles you@example.com admin. Without roles, removes them all.
                                The user must exist: signed in once, or created with create-user.
   get-roles <email>            Print the roles of a user.
   set-claims <email> <json>    Replace the claims of a user, e.g. '{"roles":["admin"],"plan":"pro"}'.
   get-claims <email>           Print the claims of a user as JSON.
-  set-methods [method...]      Switch sign-in methods on and off while the server runs: the listed ones
-                               (google, password) are on, the others off. Without any, all are on.
-  get-methods                  Print which sign-in methods are switched on.
-                               The claims commands use DATABASE_URL from the environment; the methods
-                               commands need the server's whole configuration (e.g. --env-file .env).
+  set-methods [method[=policy]...]
+                               Switch sign-in methods on and off while the server runs: the listed ones
+                               are on, the others off. Methods: google, github, password, totp (the
+                               authenticator app on its own), email-link (passwordless sign-in by e-mail),
+                               and sms (SMS codes as a second factor, next to the app). google, github,
+                               password and email-link take a policy for the second factor: none (default),
+                               optional or required, e.g. set-methods google password=required totp email-link=optional sms
+  get-methods                  Print which sign-in methods are switched on, with their policies.
+  set-password-rules [min-length=<n>] [min-score=<0-4>]
+                               Set the rules for new passwords: the minimum length (default 8, at most 128)
+                               and how hard to guess they must be, 0 (anything) to 4 (default 2: no common
+                               passwords or simple patterns). What is left out takes its default, e.g.
+                               set-password-rules min-length=10 min-score=3. Uses DATABASE_URL.
+  get-password-rules           Print the rules for new passwords.
+  remove-totp <email>          Remove a user's authenticator app and recovery codes: the last resort when
+                               both are lost. With a required policy, the user sets it up again next time.
+  remove-sms <email>           Remove a user's phone number for SMS codes, when they lost the phone.
+                               The claims commands, remove-totp and remove-sms use DATABASE_URL from the
+                               environment; the methods commands need the server's whole configuration
+                               (e.g. --env-file .env).
   schema [--dialect <name>] [--from <version>]
                                Print the SQL that creates madAuth's tables for a custom store adapter.
                                Dialects: postgres (default), mysql, sqlite. With --from, print only the
@@ -156,7 +185,12 @@ function parseCliArgs(args) {
       "app-url": { type: "string" },
       "google-client-id": { type: "string" },
       "google-client-secret": { type: "string" },
+      "github-client-id": { type: "string" },
+      "github-client-secret": { type: "string" },
       password: { type: "boolean" },
+      totp: { type: "boolean" },
+      "email-link": { type: "boolean" },
+      sms: { type: "boolean" },
       database: { type: "string" },
       "webhook-url": { type: "string" },
       yes: { type: "boolean" },
@@ -179,7 +213,17 @@ ${usage}`, exitCode: 1 };
   }
   const { values: options, positionals } = parsed;
   const [command, ...rest] = positionals;
-  const argumentLimits = { "set-roles": Infinity, "set-methods": Infinity, "set-claims": 2, "create-user": 1, "get-roles": 1, "get-claims": 1 };
+  const argumentLimits = {
+    "set-roles": Infinity,
+    "set-methods": Infinity,
+    "set-password-rules": Infinity,
+    "set-claims": 2,
+    "create-user": 1,
+    "get-roles": 1,
+    "get-claims": 1,
+    "remove-totp": 1,
+    "remove-sms": 1
+  };
   const maxArguments = command ? argumentLimits[command] ?? 0 : 0;
   if (rest.length > maxArguments) {
     return { output: `Unexpected argument: ${rest.at(-1)}
@@ -223,6 +267,15 @@ ${usage}`, exitCode: 1 };
     if (command === "set-methods" || command === "get-methods") {
       return await methods(command, rest, env);
     }
+    if (command === "set-password-rules" || command === "get-password-rules") {
+      return await passwordRules(command, rest, env);
+    }
+    if (command === "remove-totp") {
+      return await removeTotp(rest[0], env);
+    }
+    if (command === "remove-sms") {
+      return await removeSms(rest[0], env);
+    }
   } catch (e) {
     return { output: e instanceof Error ? e.message : String(e), exitCode: 1 };
   }
@@ -255,18 +308,37 @@ async function init(options, io) {
     return fail("--google-client-secret needs a Google client ID.");
   }
   const clientSecret = clientId ? (options["google-client-secret"] ?? await askClientSecret()).trim() : "";
+  const githubClientId = await answer(options["github-client-id"], "GitHub client ID (empty: no GitHub sign-in)");
+  if (!githubClientId && options["github-client-secret"] !== void 0) {
+    return fail("--github-client-secret needs a GitHub client ID.");
+  }
+  const githubClientSecret = githubClientId ? (options["github-client-secret"] ?? (options.yes ? "" : await io.askSecret("GitHub client secret: "))).trim() : "";
+  if (githubClientId && !githubClientSecret) {
+    return fail("GitHub sign-in needs the client secret of the OAuth App too (--github-client-secret).");
+  }
   const password = options.password ?? /^y/i.test(await answer(void 0, "E-mail & password sign-in? (yes/no)", "yes"));
-  if (!password && options["webhook-url"] !== void 0) {
-    return fail("--webhook-url is for e-mail & password sign-in, which is turned off.");
+  const totp = options.totp ?? /^y/i.test(await answer(void 0, "Sign-up with the authenticator app alone, without a password? (yes/no)", "no"));
+  const emailLink = options["email-link"] ?? /^y/i.test(await answer(void 0, "Passwordless sign-in with an e-mail link? (yes/no)", "no"));
+  const sms = options.sms ?? /^y/i.test(await answer(void 0, "SMS codes as a second factor, sent by your webhook receiver? (yes/no)", "no"));
+  const emails = password || totp || emailLink;
+  const webhook = emails || sms;
+  if (!webhook && options["webhook-url"] !== void 0) {
+    return fail("--webhook-url is for the e-mails of e-mail & password sign-in, of the e-mail link and of sign-up with the authenticator app, and for SMS codes, which are turned off.");
   }
-  if (!clientId && !password) {
-    return fail("No sign-in method is chosen. Give a Google client ID, turn on e-mail & password sign-in, or both.");
+  if (!clientId && !githubClientId && !emails) {
+    return fail("No sign-in method is chosen. Give a Google or GitHub client ID, turn on e-mail & password sign-in, the e-mail link or sign-up with the authenticator app.");
   }
   const database = await answer(options.database, "Database for the users", "sqlite:./madauth.db");
   if (!/^(sqlite|dynamodb):./.test(database)) {
     return fail(`The database must be sqlite:<path> or dynamodb:<table> but is "${database}".`);
   }
-  const webhookUrl = password ? await answer(options["webhook-url"], "Webhook URL, where madAuth hands over its e-mails", "http://localhost:8790/webhook") : "";
+  const webhookUrl = webhook ? await answer(options["webhook-url"], `Webhook URL, where madAuth hands over its ${emails ? sms ? "e-mails and SMS" : "e-mails" : "SMS"}`, "http://localhost:8790/webhook") : "";
+  const events = [
+    ...password ? ["email.send_verification", "email.send_password_reset", "email.send_already_registered", "email.send_password_reset_no_password"] : [],
+    ...totp ? ["email.send_verification", "email.send_already_registered"] : [],
+    ...emailLink ? ["email.send_signin_link", "email.send_already_registered"] : [],
+    ...sms ? ["sms.send_code", "user.second_factor_enabled", "user.second_factor_disabled"] : []
+  ].filter((type, i, all) => all.indexOf(type) === i).join(",");
   const variable = (name, value, comment) => `# ${comment}
 ${name}=${value}
 `;
@@ -288,14 +360,12 @@ ${name}=${value}
     variable("ALLOWED_ORIGINS", origin, "Origins of your apps, comma-separated. Only these may call the server."),
     clientId && variable("GOOGLE_CLIENT_ID", clientId, "Google sign-in: your OAuth client ID, of the type Web application."),
     clientSecret && variable("GOOGLE_CLIENT_SECRET", clientSecret, "Client secret of the same client. It enables the redirect flow."),
+    githubClientId && variable("GITHUB_CLIENT_ID", githubClientId, "GitHub sign-in: the client ID of your OAuth App."),
+    githubClientSecret && variable("GITHUB_CLIENT_SECRET", githubClientSecret, "Client secret of the same OAuth App."),
     variable("DATABASE_URL", database, "Where the users are stored, whichever way they sign in."),
-    password && variable("WEBHOOK_URL", webhookUrl, "Your webhook receiver. madAuth hands its e-mails to it."),
-    password && variable("WEBHOOK_SECRET", generateWebhookSecret(), "Signs every webhook call. Your receiver needs the same one."),
-    password && variable(
-      "WEBHOOK_EVENTS",
-      "email.verify,email.reset,email.already_registered,email.no_password",
-      "The types your webhook receiver handles; only these are sent. Add e.g. signup.before or user.created."
-    ),
+    webhook && variable("WEBHOOK_URL", webhookUrl, `Your webhook receiver. madAuth hands its ${sms ? "e-mails and SMS" : "e-mails"} to it.`),
+    webhook && variable("WEBHOOK_SECRET", generateWebhookSecret(), "Signs every webhook call. Your receiver needs the same one."),
+    webhook && variable("WEBHOOK_EVENTS", events, "The types your webhook receiver handles; only these are sent. Add e.g. user.signing_up or user.signed_up."),
     variable("PORT", String(PORT), "Port the server listens on.")
   ].filter(Boolean).join("");
   await loadConfig({ ...parseEnv(content), DATABASE_URL: void 0 }, { store: {} });
@@ -306,21 +376,27 @@ ${name}=${value}
 
 Next steps:
 
-${nextSteps(file, origin, google, password)}`, exitCode: 0 };
+${nextSteps(file, origin, google, !!githubClientId, password, totp, emailLink, sms)}`, exitCode: 0 };
 }
-function nextSteps(file, origin, google, password) {
+function nextSteps(file, origin, google, github, password, totp = false, emailLink = false, sms = false) {
   const server = `http://localhost:${PORT}`;
   const envFile = /[^\w./-]/.test(file) ? `'${file.replaceAll("'", `'\\''`)}'` : file;
-  const providers = [google, password && "Password"].filter(Boolean);
+  const providers = [google, github && "GitHub", password && "Password", totp && "Totp", emailLink && "EmailLink"].filter(Boolean);
+  const methodList = [google && "google", github && "github", password && "password", totp && "totp", emailLink && "email-link"].filter(Boolean).join(" ");
   const googleOrigins = /* @__PURE__ */ new Set([origin, ...new URL(origin).hostname === "localhost" ? ["http://localhost"] : []]);
   const steps = [
     ["Start the madAuth server:", "", `  npx @madauth/server start --env-file ${envFile}`],
-    password && [
-      "madAuth hands its e-mails to your webhook receiver. For development, start the development receiver,",
+    (password || totp || emailLink || sms) && [
+      `madAuth hands its ${sms ? "e-mails and SMS" : "e-mails"} to your webhook receiver. For development, start the development receiver,`,
       `which prints them, with the same WEBHOOK_URL and WEBHOOK_SECRET as in ${file}:`,
       "",
       `  ${DEV_WEBHOOK_RECEIVER_URL}`
     ],
+    totp && (google || github || password) && [
+      "Signing in with the authenticator app alone is off until an admin lists it. Once the server runs:",
+      "",
+      `  npx @madauth/server set-methods ${methodList} --env-file ${envFile}`
+    ],
     [
       "Proxy /auth and /.well-known from your app to the server, so that its cookies are first-party.",
       "With Vite, in vite.config.ts:",
@@ -347,6 +423,11 @@ function nextSteps(file, origin, google, password) {
       `  Authorized JavaScript origins: ${[...googleOrigins].join(" and ")}`,
       ...google === "GoogleRedirect" ? [`  Authorized redirect URIs: ${origin}/auth/google/callback`] : []
     ],
+    github && [
+      "In your GitHub OAuth App (https://github.com/settings/developers), set:",
+      "",
+      `  Authorization callback URL: ${origin}/auth/github/callback`
+    ],
     [
       `Never commit ${file}: it holds the signing key and your secrets. Production needs an https app URL`,
       "and a signing key of its own: run init again for it."
@@ -401,36 +482,107 @@ ${usage}`, exitCode: 1 };
   const roles = Array.isArray(current.roles) ? current.roles : [];
   return { output: roles.length ? `${address}: ${roles.join(" ")}` : `${address} has no roles.`, exitCode: 0 };
 }
-async function methods(command, names, env) {
+async function methods(command, args, env) {
   const config = await loadConfig(env);
-  const available = (method) => method === "google" ? !!config.google : !!config.password;
-  const settings = new Settings(config.store);
+  const forMethods = methodConfig(config);
+  const configured = (method) => isConfigured(forMethods, method);
+  const signsUp = (method) => canSignUp(forMethods, method);
+  const settings = new Settings(config.store, initialMethods(forMethods));
   if (command === "set-methods") {
-    const unknown = names.filter((name) => !SIGN_IN_METHODS.includes(name));
-    if (unknown.length) {
-      return { output: `Unknown sign-in method ${unknown.join(", ")}. Methods: ${SIGN_IN_METHODS.join(", ")}.`, exitCode: 1 };
-    }
     const next = {};
-    for (const method of SIGN_IN_METHODS) next[method] = !names.length || names.includes(method);
-    if (!anyOn(available, next)) {
-      const configured = SIGN_IN_METHODS.filter(available);
-      return { output: `That would switch off every sign-in method. The server is configured for: ${configured.join(", ")}.`, exitCode: 1 };
+    for (const arg of args) {
+      const [name, policy, ...more] = arg.split("=");
+      if (!METHODS.includes(name) || more.length) {
+        return { output: `Unknown sign-in method "${arg}". Methods: ${METHODS.join(", ")}, e.g. set-methods google password=required totp sms.`, exitCode: 1 };
+      }
+      const method = name;
+      if (policy !== void 0 && (!hasSecondFactor(method) || !SECOND_FACTOR_POLICIES.includes(policy))) {
+        return {
+          output: `"${arg}": google, github, password and email-link take a policy for the second factor: ${SECOND_FACTOR_POLICIES.join(", ")}.`,
+          exitCode: 1
+        };
+      }
+      next[method] = hasSecondFactor(method) ? { secondFactor: policy ?? "none" } : {};
+    }
+    if (!anyOn(signsUp, next)) {
+      const usable = SIGN_IN_METHODS.filter(signsUp);
+      return {
+        output: `That would leave no sign-in method on that creates users, so nobody could sign up. On this server these do: ${usable.join(", ")}.`,
+        exitCode: 1
+      };
     }
     await settings.changeMethods(() => next, null);
   }
   const current = await settings.methods();
-  const on = SIGN_IN_METHODS.filter((method) => isOn(method, available, current));
-  const off = SIGN_IN_METHODS.filter((method) => available(method) && !isOn(method, available, current));
+  const describe = (method) => {
+    const policy = hasSecondFactor(method) ? policyOf(method, current) : "none";
+    return policy !== "none" ? `${method} (second factor ${policy})` : method;
+  };
+  const on = METHODS.filter((method) => isOn(method, configured, current)).map(describe);
+  const off = METHODS.filter((method) => configured(method) && !isOn(method, configured, current));
   return { output: `Switched on: ${on.join(", ")}.${off.length ? ` Switched off: ${off.join(", ")}.` : ""}`, exitCode: 0 };
 }
+function describeRules(rules) {
+  return `New passwords: at least ${rules.minLength} characters, and a strength score of at least ${rules.minScore} (0 to 4).`;
+}
+async function passwordRules(command, args, env) {
+  const settings = new Settings(await loadStore(env));
+  if (command === "set-password-rules") {
+    const fail = (output2) => ({ output: output2, exitCode: 1 });
+    const rules = { ...DEFAULT_PASSWORD_RULES };
+    for (const arg of args) {
+      const [name, value, ...more] = arg.split("=");
+      const number = value !== void 0 && /^\d+$/.test(value) && !more.length ? Number(value) : NaN;
+      if (name === "min-length") {
+        if (!(number >= 1 && number <= MAX_MIN_LENGTH)) return fail(`min-length must be a whole number from 1 to ${MAX_MIN_LENGTH} but is "${value ?? ""}".`);
+        rules.minLength = number;
+      } else if (name === "min-score") {
+        if (!isPasswordScore(number)) return fail(`min-score must be 0, 1, 2, 3 or 4 but is "${value ?? ""}".`);
+        rules.minScore = number;
+      } else {
+        return fail(`Unknown password rule "${arg}". Rules: min-length=<n>, min-score=<0-4>, e.g. set-password-rules min-length=10 min-score=3.`);
+      }
+    }
+    await settings.setPasswordRules(rules, null);
+  }
+  return { output: describeRules(await settings.passwordRules()), exitCode: 0 };
+}
+async function removeTotp(email, env) {
+  if (!isValidEmail(email)) return { output: `"${email ?? ""}" is not an e-mail address.
+
+${usage}`, exitCode: 1 };
+  const users = new Users(await loadStore(env));
+  const address = normalizeEmail(email);
+  const user = await users.findByEmail(address);
+  if (!user) return { output: `No user has the e-mail address ${address}.`, exitCode: 1 };
+  const removed = await users.removeTotp(user.id);
+  return {
+    output: removed ? `Removed the authenticator app of ${address}.` : `${address} has no authenticator app.`,
+    exitCode: 0
+  };
+}
+async function removeSms(email, env) {
+  if (!isValidEmail(email)) return { output: `"${email ?? ""}" is not an e-mail address.
+
+${usage}`, exitCode: 1 };
+  const users = new Users(await loadStore(env));
+  const address = normalizeEmail(email);
+  const user = await users.findByEmail(address);
+  if (!user) return { output: `No user has the e-mail address ${address}.`, exitCode: 1 };
+  const removed = await users.removeSms(user.id);
+  return {
+    output: removed ? `Removed the phone number of ${address}.` : `${address} has no phone number for SMS codes.`,
+    exitCode: 0
+  };
+}
 async function createUser(email, io, env) {
   if (!isValidEmail(email)) return { output: `"${email ?? ""}" is not an e-mail address.
 
 ${usage}`, exitCode: 1 };
-  const { store, minLength } = await loadUserStoreConfig(env);
+  const store = await loadStore(env);
   const password = await io.askSecret(`Password for ${email}: `);
-  const policy = checkPasswordPolicy(password, minLength);
-  if (policy) return { output: policy, exitCode: 1 };
+  const problem = await checkPasswordPolicy(password, await new Settings(store).passwordRules(), [email]);
+  if (problem) return { output: problem.message, exitCode: 1 };
   const users = new Users(store);
   const passwordHash = await hashPassword(password);
   const user = await users.createUser({