@madauth/server 0.1.0 → 0.2.0-beta.1

package/README.md

@@ -1,27 +1,35 @@
 # @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 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 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 browser side is [`@madauth/web`](https://www.npmjs.com/package/@madauth/web).
 
 ## Run it
 
-With Docker:
+With Node.js 22.13 or newer:
 
 ```bash
-docker run --rm -p 8787:8787 --env-file .env -v madauth-data:/data ghcr.io/inouiw/madauth-server
+npm install @madauth/server
 ```
 
-Or with Node.js 22.13 or newer:
+```bash
+npx @madauth/server init
+```
 
 ```bash
-npx @madauth/server generate-key
+npx @madauth/server start --env-file .env
 ```
 
+`init` asks a few questions and writes the configuration to `.env`, with a new signing key, then prints the next steps. `start` runs the server on port 8787. See [Getting started](https://github.com/inouiw/madAuth/blob/main/docs/getting-started.md).
+
+With Docker:
+
 ```bash
-npm install @madauth/server
+docker run --rm -p 8787:8787 --env-file .env -v madauth-data:/data ghcr.io/inouiw/madauth-server
 ```
 
+Or inside your own Node server:
+
 ```ts
 import { createApp, loadConfig } from '@madauth/server';
 
@@ -38,12 +46,14 @@ The package also contains self-contained bundles for AWS Lambda (`dist/standalon
 | `@madauth/server/verify` | verify a madAuth session in your own backend |
 | `@madauth/server/webhook` | verify webhook calls in your receiver |
 | `@madauth/server/sqlite` | the SQLite store |
+| `@madauth/server/dynamodb` | the Amazon DynamoDB store |
 | `@madauth/server/node`, `/lambda`, `/azure` | hosting entry points |
 | `@madauth/server/testing` | a contract test suite for custom store adapters |
 
 ## Documentation
 
-See [Running the madAuth server](https://github.com/inouiw/madAuth/blob/main/docs/server.md) for the configuration, Google Cloud Console setup, webhooks, hosting and custom store adapters.
+- [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.
 
 ## License
 

package/dist/bin.js

@@ -1,46 +1,105 @@
 #!/usr/bin/env node
 import {
-  createTablesSql
-} from "./chunk-3WIWWKRI.js";
+  createTablesSql,
+  upgradeTablesSql
+} from "./chunk-CNL562LZ.js";
 import {
-  ConfigError,
+  madauthSchema
+} from "./chunk-XNBWZZHT.js";
+import {
+  Roles,
   Users,
   checkPasswordPolicy,
   hashPassword,
   isValidEmail,
+  loadConfig,
+  loadStore,
   loadUserStoreConfig,
-  normalizeEmail
-} from "./chunk-V2XKGETK.js";
+  normalizeEmail,
+  parseRoles
+} from "./chunk-5CKEMC6M.js";
 import {
   generateSigningKey
 } from "./chunk-JDQLSL36.js";
 import {
+  DEV_WEBHOOK_RECEIVER_URL,
   generateWebhookSecret
-} from "./chunk-AVZE6FFR.js";
+} from "./chunk-6EJDVZCD.js";
 
 // src/cli.ts
+import { existsSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { createInterface } from "readline";
-var usage = `Usage: npx @madauth/server <command>
+import { parseArgs, parseEnv } from "util";
+var PORT = 8787;
+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.
+  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.
-  schema [--dialect <name>]    Print the SQL that creates madAuth's tables for a custom store adapter.
-                               Dialects: postgres (default), mysql, sqlite`;
+  set-roles <email> [role...]  Set the roles of an e-mail address, e.g. to make the first admin:
+                               set-roles you@example.com admin. Without roles, removes them all.
+                               Uses DATABASE_URL from the environment.
+  get-roles <email>            Print the roles of an e-mail address.
+  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
+                               changes since that schema version, to upgrade existing tables.
+
+Options:
+  --env-file <path>            Read environment variables from this file, for any command. A variable
+                               that is already set in the environment wins.`;
+var piped;
+async function readPipedLine() {
+  if (!piped) {
+    const reader = createInterface({ input: process.stdin, terminal: false });
+    const input = piped = { reader, lines: reader[Symbol.asyncIterator](), ended: false };
+    reader.once("close", () => input.ended = true);
+  }
+  if (!piped.ended) piped.reader.resume();
+  const next = await piped.lines.next();
+  if (!piped.ended) piped.reader.pause();
+  return next.done ? "" : next.value;
+}
 var terminalIo = {
+  async ask(question, defaultValue = "") {
+    const prompt = `${question}${defaultValue ? ` [${defaultValue}]` : ""}: `;
+    if (!process.stdin.isTTY) {
+      process.stdout.write(prompt);
+      const line = await readPipedLine();
+      process.stdout.write("\n");
+      return line.trim() || defaultValue;
+    }
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve, reject) => {
+      let answered = false;
+      rl.on("SIGINT", () => rl.close());
+      rl.on("close", () => {
+        if (answered) return;
+        process.stdout.write("\n");
+        reject(new Error("Cancelled."));
+      });
+      rl.question(prompt, (answer) => {
+        answered = true;
+        rl.close();
+        resolve(answer.trim() || defaultValue);
+      });
+    });
+  },
   async askSecret(question) {
     process.stdout.write(question);
     const stdin = process.stdin;
     if (!stdin.isTTY) {
-      const rl = createInterface({ input: stdin, terminal: false });
-      for await (const line of rl) {
-        rl.close();
-        process.stdout.write("\n");
-        return line;
-      }
-      return "";
+      const line = await readPipedLine();
+      process.stdout.write("\n");
+      return line;
     }
     stdin.setRawMode(true);
     stdin.setEncoding("utf8");
@@ -72,9 +131,61 @@ var terminalIo = {
     });
   }
 };
+function parseCliArgs(args) {
+  return parseArgs({
+    args,
+    options: {
+      "env-file": { type: "string" },
+      dialect: { type: "string" },
+      // schema: print only the changes since this schema version.
+      from: { type: "string" },
+      // init: an answer for each question, then where and how to write the file.
+      "app-url": { type: "string" },
+      "google-client-id": { type: "string" },
+      "google-client-secret": { type: "string" },
+      password: { type: "boolean" },
+      database: { type: "string" },
+      "webhook-url": { type: "string" },
+      yes: { type: "boolean" },
+      out: { type: "string" },
+      force: { type: "boolean" }
+    },
+    allowPositionals: true,
+    // --no-password
+    allowNegative: true
+  });
+}
 async function runCli(args, io = terminalIo, env = process.env) {
-  const [command, ...rest] = args;
+  let parsed;
   try {
+    parsed = parseCliArgs(args);
+  } catch (e) {
+    return { output: `${e.message}
+
+${usage}`, exitCode: 1 };
+  }
+  const { values: options, positionals } = parsed;
+  const [command, ...rest] = positionals;
+  const maxArguments = command === "set-roles" ? Infinity : command === "create-user" || command === "get-roles" ? 1 : 0;
+  if (rest.length > maxArguments) {
+    return { output: `Unexpected argument: ${rest.at(-1)}
+
+${usage}`, exitCode: 1 };
+  }
+  try {
+    const envFile = options["env-file"];
+    if (envFile !== void 0) {
+      if (!existsSync(envFile)) return { output: `--env-file: ${envFile} does not exist.`, exitCode: 1 };
+      env = withEnvFile(envFile, env);
+    }
+    if (command === "init") {
+      return await init(options, io);
+    }
+    if (command === "start") {
+      const { start } = await import("./entry/node.js");
+      await start({ env });
+      return { output: "", exitCode: 0 };
+    }
     if (command === "generate-key") {
       return { output: JSON.stringify(await generateSigningKey()), exitCode: 0 };
     }
@@ -82,19 +193,170 @@ async function runCli(args, io = terminalIo, env = process.env) {
       return { output: generateWebhookSecret(), exitCode: 0 };
     }
     if (command === "schema") {
-      const i = rest.indexOf("--dialect");
-      const dialect = i >= 0 ? rest[i + 1] : "postgres";
+      const dialect = options.dialect ?? "postgres";
       if (!["postgres", "mysql", "sqlite"].includes(dialect)) return { output: usage, exitCode: 1 };
-      return { output: createTablesSql(dialect), exitCode: 0 };
+      if (options.from === void 0) return { output: createTablesSql(dialect), exitCode: 0 };
+      const from = Number(options.from);
+      if (!Number.isInteger(from) || from < 1 || from > madauthSchema.version) return { output: usage, exitCode: 1 };
+      return { output: upgradeTablesSql(dialect, from) || "-- The tables are up to date.", exitCode: 0 };
     }
     if (command === "create-user") {
       return await createUser(rest[0], io, env);
     }
+    if (command === "set-roles" || command === "get-roles") {
+      return await roles(command, rest[0], rest.slice(1), env);
+    }
   } catch (e) {
-    return { output: e instanceof ConfigError ? e.message : String(e), exitCode: 1 };
+    return { output: e instanceof Error ? e.message : String(e), exitCode: 1 };
   }
   return { output: usage, exitCode: command ? 1 : 0 };
 }
+function withEnvFile(path, env) {
+  const merged = parseEnv(readFileSync(path, "utf8"));
+  for (const [name, value] of Object.entries(env)) {
+    if (value !== void 0) merged[name] = value;
+  }
+  return merged;
+}
+function httpOrigin(value) {
+  const url = URL.canParse(value) ? new URL(value) : void 0;
+  return url && (url.protocol === "http:" || url.protocol === "https:") ? url.origin : void 0;
+}
+async function init(options, io) {
+  const fail = (output2) => ({ output: output2, exitCode: 1 });
+  const file = options.out ?? ".env";
+  if (existsSync(file) && !options.force) {
+    return fail(`${file} already exists. Use --force to overwrite it, or --out <path> to write another file.`);
+  }
+  const answer = async (given, question, defaultValue = "") => (given ?? (options.yes ? defaultValue : await io.ask(question, defaultValue))).trim();
+  const appUrl = await answer(options["app-url"], "App URL, the address your users open", "http://localhost:5173");
+  const origin = httpOrigin(appUrl);
+  if (!origin) return fail(`The app URL must be an http(s) URL, e.g. https://app.example.com, but is "${appUrl}".`);
+  const clientId = await answer(options["google-client-id"], "Google client ID (empty: no Google sign-in)");
+  const askClientSecret = () => options.yes ? "" : io.askSecret("Google client secret (empty: no redirect flow): ");
+  if (!clientId && options["google-client-secret"] !== void 0) {
+    return fail("--google-client-secret needs a Google client ID.");
+  }
+  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.database !== void 0 || options["webhook-url"] !== void 0)) {
+    return fail("--database and --webhook-url are for e-mail & password sign-in, which is 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.");
+  }
+  const database = password ? await answer(options.database, "Database for the users", "sqlite:./madauth.db") : "";
+  if (password && !/^(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 variable = (name, value, comment) => `# ${comment}
+${name}=${value}
+`;
+  const content = [
+    "# Configuration of the madAuth server, written by npx @madauth/server init. It holds secrets: never commit it.\n",
+    "# All settings: https://github.com/inouiw/madAuth/blob/main/docs/server.md#configuration\n\n",
+    variable(
+      "MADAUTH_ISSUER",
+      origin,
+      "Public address of the madAuth server: the origin of your app, which proxies /auth and /.well-known to it."
+    ),
+    // In single quotes, as JSON is full of double quotes. Node's parser removes them; Docker's --env-file
+    // keeps them, and the server removes them then.
+    variable(
+      "MADAUTH_SIGNING_KEY",
+      `'${JSON.stringify(await generateSigningKey())}'`,
+      "Private key that signs the sessions. Keep it secret, and use the same one on every instance."
+    ),
+    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."),
+    password && variable("DATABASE_URL", database, "E-mail & password sign-in: where the users are stored."),
+    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",
+      "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 }, password ? { store: {} } : {});
+  if (options.force) rmSync(file, { force: true });
+  writeFileSync(file, content, { mode: 384, flag: "wx" });
+  const google = clientSecret ? "GoogleRedirect" : clientId ? "GoogleFedcm" : void 0;
+  return { output: `Wrote ${file}.
+
+Next steps:
+
+${nextSteps(file, origin, google, password)}`, exitCode: 0 };
+}
+function nextSteps(file, origin, google, password) {
+  const server = `http://localhost:${PORT}`;
+  const envFile = /[^\w./-]/.test(file) ? `'${file.replaceAll("'", `'\\''`)}'` : file;
+  const providers = [google, password && "Password"].filter(Boolean);
+  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,",
+      `which prints them, with the same WEBHOOK_URL and WEBHOOK_SECRET as in ${file}:`,
+      "",
+      `  ${DEV_WEBHOOK_RECEIVER_URL}`
+    ],
+    [
+      "Proxy /auth and /.well-known from your app to the server, so that its cookies are first-party.",
+      "With Vite, in vite.config.ts:",
+      "",
+      "  server: {",
+      "    proxy: {",
+      `      '/auth': '${server}',`,
+      `      '/.well-known': '${server}',`,
+      "    },",
+      "  },"
+    ],
+    [
+      "Sign users in from your app (npm install @madauth/web):",
+      "",
+      `  import { Madauth, ${providers.join(", ")} } from '@madauth/web';`,
+      "",
+      `  Madauth.initialize({ providers: [${providers.map((provider) => `new ${provider}()`).join(", ")}] });`,
+      "  Madauth.onAuthStateChanged((user) => console.log(user)); // the user, or null",
+      "  signInButton.onclick = () => Madauth.signIn();"
+    ],
+    google && [
+      "In the Google Cloud Console (https://console.cloud.google.com/apis/credentials), add to your OAuth client:",
+      "",
+      `  Authorized JavaScript origins: ${[...googleOrigins].join(" and ")}`,
+      ...google === "GoogleRedirect" ? [`  Authorized redirect URIs: ${origin}/auth/google/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."
+    ]
+  ].filter((step) => !!step);
+  return steps.map((lines, i) => `${i + 1}. ${lines.map((line, j) => j && line ? `   ${line}` : line).join("\n")}`).join("\n\n");
+}
+async function roles(command, email, names, env) {
+  if (!isValidEmail(email)) return { output: `"${email ?? ""}" is not an e-mail address.
+
+${usage}`, exitCode: 1 };
+  const store = await loadStore(env);
+  const address = normalizeEmail(email);
+  const assignments = new Roles(store);
+  if (command === "set-roles") {
+    const parsed = parseRoles(names);
+    if (!parsed) {
+      return {
+        output: 'Role names consist of lower-case letters, digits, "-" and "_", and start with a letter, e.g. admin.',
+        exitCode: 1
+      };
+    }
+    await assignments.set(address, parsed, null);
+  }
+  const current = await assignments.get(address);
+  return { output: current.length ? `${address}: ${current.join(" ")}` : `${address} has no roles.`, exitCode: 0 };
+}
 async function createUser(email, io, env) {
   if (!isValidEmail(email)) return { output: `"${email ?? ""}" is not an e-mail address.
 
@@ -117,5 +379,5 @@ ${usage}`, exitCode: 1 };
 
 // src/bin.ts
 var { output, exitCode } = await runCli(process.argv.slice(2));
-(exitCode ? console.error : console.log)(output);
+if (output) (exitCode ? console.error : console.log)(output);
 process.exitCode = exitCode;