@madauth/server 0.3.0-beta.2 → 0.4.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, 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 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,41 @@
 import {
   createTablesSql,
   upgradeTablesSql
-} from "./chunk-56MOVFO4.js";
+} from "./chunk-OMIX3ERC.js";
 import {
   madauthSchema
-} from "./chunk-CD7Y4T66.js";
+} from "./chunk-GA4TF7EI.js";
 import {
+  SECOND_FACTOR_POLICIES,
   SIGN_IN_METHODS,
   Settings,
   Users,
   anyOn,
+  canSignUp,
   checkPasswordPolicy,
   claimsFromJson,
   hashPassword,
+  initialMethods,
+  isConfigured,
   isOn,
   isValidEmail,
   loadConfig,
   loadStore,
   loadUserStoreConfig,
+  methodConfig,
   normalizeEmail,
   parseClaims,
   parseRoles,
-  passwordAccountKey
-} from "./chunk-TI35AZ2U.js";
+  passwordAccountKey,
+  policyOf
+} from "./chunk-ISJGOCF3.js";
 import {
   generateSigningKey
 } from "./chunk-JDQLSL36.js";
 import {
   DEV_WEBHOOK_RECEIVER_URL,
   generateWebhookSecret
-} from "./chunk-3QRKWLR7.js";
+} from "./chunk-Y7ZSUROX.js";
 
 // src/cli.ts
 import { existsSync, readFileSync, rmSync, writeFileSync } from "fs";
@@ -43,8 +49,9 @@ 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.
+                               --no-password, --totp or --no-totp (sign-up with the authenticator app),
+                               --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)
@@ -56,11 +63,17 @@ Commands:
   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, 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
+  get-methods                  Print which sign-in methods are switched on, with their policies.
+  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).
   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
@@ -157,6 +170,7 @@ function parseCliArgs(args) {
       "google-client-id": { type: "string" },
       "google-client-secret": { type: "string" },
       password: { type: "boolean" },
+      totp: { type: "boolean" },
       database: { type: "string" },
       "webhook-url": { type: "string" },
       yes: { type: "boolean" },
@@ -179,7 +193,15 @@ ${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-claims": 2,
+    "create-user": 1,
+    "get-roles": 1,
+    "get-claims": 1,
+    "remove-totp": 1
+  };
   const maxArguments = command ? argumentLimits[command] ?? 0 : 0;
   if (rest.length > maxArguments) {
     return { output: `Unexpected argument: ${rest.at(-1)}
@@ -223,6 +245,9 @@ ${usage}`, exitCode: 1 };
     if (command === "set-methods" || command === "get-methods") {
       return await methods(command, rest, env);
     }
+    if (command === "remove-totp") {
+      return await removeTotp(rest[0], env);
+    }
   } catch (e) {
     return { output: e instanceof Error ? e.message : String(e), exitCode: 1 };
   }
@@ -256,17 +281,20 @@ async function init(options, io) {
   }
   const clientSecret = clientId ? (options["google-client-secret"] ?? await askClientSecret()).trim() : "";
   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 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.");
   }
-  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 && !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.");
   }
   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 = 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 variable = (name, value, comment) => `# ${comment}
 ${name}=${value}
 `;
@@ -289,13 +317,9 @@ ${name}=${value}
     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."),
     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."
-    ),
+    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."),
     variable("PORT", String(PORT), "Port the server listens on.")
   ].filter(Boolean).join("");
   await loadConfig({ ...parseEnv(content), DATABASE_URL: void 0 }, { store: {} });
@@ -306,21 +330,27 @@ ${name}=${value}
 
 Next steps:
 
-${nextSteps(file, origin, google, password)}`, exitCode: 0 };
+${nextSteps(file, origin, google, password, totp)}`, exitCode: 0 };
 }
-function nextSteps(file, origin, google, password) {
+function nextSteps(file, origin, google, password, totp = false) {
   const server = `http://localhost:${PORT}`;
   const envFile = /[^\w./-]/.test(file) ? `'${file.replaceAll("'", `'\\''`)}'` : file;
-  const providers = [google, password && "Password"].filter(Boolean);
+  const providers = [google, password && "Password", totp && "Totp"].filter(Boolean);
+  const methodList = [google && "google", password && "password", totp && "totp"].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 && [
+    (password || totp) && [
       "madAuth hands its 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) && [
+      "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:",
@@ -401,28 +431,60 @@ ${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 (!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 };
+      }
+      const method = name;
+      if (policy !== void 0 && (method === "totp" || !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(", ")}.`,
+          exitCode: 1
+        };
+      }
+      next[method] = method === "totp" ? {} : { 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 = policyOf(method, current);
+    return method !== "totp" && policy !== "none" ? `${method} (authenticator app ${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));
   return { output: `Switched on: ${on.join(", ")}.${off.length ? ` Switched off: ${off.join(", ")}.` : ""}`, 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 createUser(email, io, env) {
   if (!isValidEmail(email)) return { output: `"${email ?? ""}" is not an e-mail address.