@madauth/server 0.4.0-beta.1 → 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, e-mail & password 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 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).
 

package/dist/bin.js

@@ -2,11 +2,14 @@
 import {
   createTablesSql,
   upgradeTablesSql
-} from "./chunk-OMIX3ERC.js";
+} from "./chunk-O2URPWA6.js";
 import {
   madauthSchema
-} from "./chunk-GA4TF7EI.js";
+} from "./chunk-NP75Y3IV.js";
 import {
+  DEFAULT_PASSWORD_RULES,
+  MAX_MIN_LENGTH,
+  METHODS,
   SECOND_FACTOR_POLICIES,
   SIGN_IN_METHODS,
   Settings,
@@ -15,28 +18,29 @@ import {
   canSignUp,
   checkPasswordPolicy,
   claimsFromJson,
+  hasSecondFactor,
   hashPassword,
   initialMethods,
   isConfigured,
   isOn,
+  isPasswordScore,
   isValidEmail,
   loadConfig,
   loadStore,
-  loadUserStoreConfig,
   methodConfig,
   normalizeEmail,
   parseClaims,
   parseRoles,
   passwordAccountKey,
   policyOf
-} from "./chunk-ISJGOCF3.js";
+} from "./chunk-NYIEFI4B.js";
 import {
   generateSigningKey
 } from "./chunk-JDQLSL36.js";
 import {
   DEV_WEBHOOK_RECEIVER_URL,
   generateWebhookSecret
-} from "./chunk-Y7ZSUROX.js";
+} from "./chunk-SISM7YUZ.js";
 
 // src/cli.ts
 import { existsSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -48,15 +52,18 @@ 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
+                               --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.
@@ -65,15 +72,24 @@ Commands:
   get-claims <email>           Print the claims of a user as JSON.
   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, password, totp (the authenticator
-                               app on its own). google and password take a policy for the authenticator
-                               app as a second factor: none (default), optional or required, e.g.
-                               set-methods google password=required totp
+                               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.
-                               The claims commands and remove-totp use DATABASE_URL from the environment;
-                               the methods commands need the server's whole configuration (e.g. --env-file .env).
+  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
@@ -169,8 +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" },
@@ -196,11 +216,13 @@ ${usage}`, exitCode: 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-totp": 1,
+    "remove-sms": 1
   };
   const maxArguments = command ? argumentLimits[command] ?? 0 : 0;
   if (rest.length > maxArguments) {
@@ -245,9 +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 };
   }
@@ -280,21 +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"));
   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 emails = password || totp;
-  if (!emails && options["webhook-url"] !== void 0) {
-    return fail("--webhook-url is for the e-mails of e-mail & password sign-in and of sign-up with the authenticator app, which are turned off.");
+  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 && !emails) {
-    return fail("No sign-in method is chosen. Give a Google client ID, turn on e-mail & password sign-in or sign-up with the authenticator app.");
+  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 = emails ? await answer(options["webhook-url"], "Webhook URL, where madAuth hands over its e-mails", "http://localhost:8790/webhook") : "";
-  const events = password ? "email.verify,email.reset,email.already_registered,email.no_password" : "email.verify,email.already_registered";
+  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}
 `;
@@ -316,10 +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."),
-    emails && variable("WEBHOOK_URL", webhookUrl, "Your webhook receiver. madAuth hands its e-mails to it."),
-    emails && variable("WEBHOOK_SECRET", generateWebhookSecret(), "Signs every webhook call. Your receiver needs the same one."),
-    emails && variable("WEBHOOK_EVENTS", events, "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: {} });
@@ -330,23 +376,23 @@ ${name}=${value}
 
 Next steps:
 
-${nextSteps(file, origin, google, password, totp)}`, exitCode: 0 };
+${nextSteps(file, origin, google, !!githubClientId, password, totp, emailLink, sms)}`, exitCode: 0 };
 }
-function nextSteps(file, origin, google, password, totp = false) {
+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", totp && "Totp"].filter(Boolean);
-  const methodList = [google && "google", password && "password", totp && "totp"].filter(Boolean).join(" ");
+  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 || totp) && [
-      "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 || password) && [
+    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}`
@@ -377,6 +423,11 @@ function nextSteps(file, origin, google, password, totp = false) {
       `  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."
@@ -441,17 +492,17 @@ async function methods(command, args, env) {
     const next = {};
     for (const arg of args) {
       const [name, policy, ...more] = arg.split("=");
-      if (!SIGN_IN_METHODS.includes(name) || more.length) {
-        return { output: `Unknown sign-in method "${arg}". Methods: ${SIGN_IN_METHODS.join(", ")}, e.g. set-methods google password=required totp.`, exitCode: 1 };
+      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 && (method === "totp" || !SECOND_FACTOR_POLICIES.includes(policy))) {
+      if (policy !== void 0 && (!hasSecondFactor(method) || !SECOND_FACTOR_POLICIES.includes(policy))) {
         return {
-          output: `"${arg}": google and password take a policy for the authenticator app as a second factor: ${SECOND_FACTOR_POLICIES.join(", ")}.`,
+          output: `"${arg}": google, github, password and email-link take a policy for the second factor: ${SECOND_FACTOR_POLICIES.join(", ")}.`,
           exitCode: 1
         };
       }
-      next[method] = method === "totp" ? {} : { secondFactor: policy ?? "none" };
+      next[method] = hasSecondFactor(method) ? { secondFactor: policy ?? "none" } : {};
     }
     if (!anyOn(signsUp, next)) {
       const usable = SIGN_IN_METHODS.filter(signsUp);
@@ -464,13 +515,38 @@ async function methods(command, args, env) {
   }
   const current = await settings.methods();
   const describe = (method) => {
-    const policy = policyOf(method, current);
-    return method !== "totp" && policy !== "none" ? `${method} (authenticator app ${policy})` : method;
+    const policy = hasSecondFactor(method) ? policyOf(method, current) : "none";
+    return policy !== "none" ? `${method} (second factor ${policy})` : method;
   };
-  const on = SIGN_IN_METHODS.filter((method) => isOn(method, configured, current)).map(describe);
-  const off = SIGN_IN_METHODS.filter((method) => configured(method) && !isOn(method, configured, current));
+  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.
 
@@ -485,14 +561,28 @@ ${usage}`, exitCode: 1 };
     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({