@madauth/server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Neuy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @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 browser side is [`@madauth/web`](https://www.npmjs.com/package/@madauth/web).
+
+## Run it
+
+With Docker:
+
+```bash
+docker run --rm -p 8787:8787 --env-file .env -v madauth-data:/data ghcr.io/inouiw/madauth-server
+```
+
+Or with Node.js 22.13 or newer:
+
+```bash
+npx @madauth/server generate-key
+```
+
+```bash
+npm install @madauth/server
+```
+
+```ts
+import { createApp, loadConfig } from '@madauth/server';
+
+const app = createApp(await loadConfig(process.env)); // a Hono app: app.fetch(request) → response
+```
+
+The package also contains self-contained bundles for AWS Lambda (`dist/standalone/lambda.mjs`) and Azure Functions (`dist/standalone/azure.mjs`).
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@madauth/server` | `createApp`, `loadConfig`, the store adapter types and the SQL schema |
+| `@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/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.
+
+## License
+
+MIT

package/dist/bin.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import {
+  createTablesSql
+} from "./chunk-3WIWWKRI.js";
+import {
+  ConfigError,
+  Users,
+  checkPasswordPolicy,
+  hashPassword,
+  isValidEmail,
+  loadUserStoreConfig,
+  normalizeEmail
+} from "./chunk-V2XKGETK.js";
+import {
+  generateSigningKey
+} from "./chunk-JDQLSL36.js";
+import {
+  generateWebhookSecret
+} from "./chunk-AVZE6FFR.js";
+
+// src/cli.ts
+import { createInterface } from "readline";
+var usage = `Usage: npx @madauth/server <command>
+
+Commands:
+  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`;
+var terminalIo = {
+  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 "";
+    }
+    stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.resume();
+    return new Promise((resolve, reject) => {
+      let value = "";
+      const finish = () => {
+        stdin.off("data", onData);
+        stdin.setRawMode(false);
+        stdin.pause();
+        process.stdout.write("\n");
+      };
+      const onData = (chunk) => {
+        for (const ch of chunk) {
+          if (ch === "\r" || ch === "\n") {
+            finish();
+            resolve(value);
+            return;
+          }
+          if (ch === "") {
+            finish();
+            reject(new Error("Cancelled."));
+            return;
+          }
+          value = ch === "\x7F" || ch === "\b" ? [...value].slice(0, -1).join("") : value + ch;
+        }
+      };
+      stdin.on("data", onData);
+    });
+  }
+};
+async function runCli(args, io = terminalIo, env = process.env) {
+  const [command, ...rest] = args;
+  try {
+    if (command === "generate-key") {
+      return { output: JSON.stringify(await generateSigningKey()), exitCode: 0 };
+    }
+    if (command === "generate-webhook-secret") {
+      return { output: generateWebhookSecret(), exitCode: 0 };
+    }
+    if (command === "schema") {
+      const i = rest.indexOf("--dialect");
+      const dialect = i >= 0 ? rest[i + 1] : "postgres";
+      if (!["postgres", "mysql", "sqlite"].includes(dialect)) return { output: usage, exitCode: 1 };
+      return { output: createTablesSql(dialect), exitCode: 0 };
+    }
+    if (command === "create-user") {
+      return await createUser(rest[0], io, env);
+    }
+  } catch (e) {
+    return { output: e instanceof ConfigError ? e.message : String(e), exitCode: 1 };
+  }
+  return { output: usage, exitCode: command ? 1 : 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 password = await io.askSecret(`Password for ${email}: `);
+  const policy = checkPasswordPolicy(password, minLength);
+  if (policy) return { output: policy, exitCode: 1 };
+  const users = new Users(store);
+  const user = await users.createPasswordUser({
+    email: email.trim(),
+    emailNormalized: normalizeEmail(email),
+    name: null,
+    passwordHash: await hashPassword(password),
+    emailVerified: true
+  });
+  if (!user) return { output: `A user with the e-mail address ${email} already exists.`, exitCode: 1 };
+  return { output: `Created user ${user.id} (${user.email}).`, exitCode: 0 };
+}
+
+// src/bin.ts
+var { output, exitCode } = await runCli(process.argv.slice(2));
+(exitCode ? console.error : console.log)(output);
+process.exitCode = exitCode;

package/dist/chunk-3WIWWKRI.js

@@ -0,0 +1,81 @@
+// src/store/schema.ts
+var madauthSchema = {
+  version: 1,
+  models: {
+    user: {
+      fields: {
+        id: { type: "string", primaryKey: true },
+        email: { type: "string" },
+        emailNormalized: { type: "string", unique: true },
+        emailVerified: { type: "boolean" },
+        name: { type: "string", nullable: true },
+        sessionVersion: { type: "number" },
+        lastMailAt: { type: "number" },
+        createdAt: { type: "number" }
+      }
+    },
+    /** How a user signs in. `key` is e.g. `password:<userId>`; later `google:<sub>` or `totp:<userId>`. */
+    account: {
+      fields: {
+        id: { type: "string", primaryKey: true },
+        userId: { type: "string", index: true },
+        key: { type: "string", unique: true },
+        secret: { type: "string", nullable: true },
+        failedAttempts: { type: "number" },
+        lockedUntil: { type: "number" },
+        createdAt: { type: "number" }
+      }
+    },
+    /** A pending e-mail verification or password reset. `id` is the SHA-256 of the link token. */
+    verification: {
+      fields: {
+        id: { type: "string", primaryKey: true },
+        userId: { type: "string", index: true },
+        purpose: { type: "string" },
+        codeHash: { type: "string" },
+        attempts: { type: "number" },
+        expiresAt: { type: "number" }
+      }
+    }
+  }
+};
+
+// src/store/sql.ts
+function tableName(model) {
+  return `madauth_${model}`;
+}
+function columnName(field) {
+  return field.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+var columnTypes = {
+  sqlite: { string: "TEXT", number: "INTEGER", boolean: "INTEGER" },
+  // DOUBLE PRECISION keeps numbers as JavaScript numbers in most Postgres drivers (BIGINT often becomes a string).
+  postgres: { string: "TEXT", number: "DOUBLE PRECISION", boolean: "BOOLEAN" },
+  mysql: { string: "TEXT", number: "DOUBLE", boolean: "BOOLEAN" }
+};
+function createTablesSql(dialect, schema = madauthSchema) {
+  const statements = [];
+  for (const [model, { fields }] of Object.entries(schema.models)) {
+    const table = tableName(model);
+    const columns = Object.entries(fields).map(([field, def]) => {
+      const keyed = def.primaryKey || def.unique || def.index;
+      const type = dialect === "mysql" && def.type === "string" && keyed ? "VARCHAR(255)" : columnTypes[dialect][def.type];
+      const constraints = def.primaryKey ? " PRIMARY KEY" : `${def.nullable ? "" : " NOT NULL"}${def.unique ? " UNIQUE" : ""}`;
+      return `  ${columnName(field)} ${type}${constraints}`;
+    });
+    statements.push(`CREATE TABLE ${table} (
+${columns.join(",\n")}
+);`);
+    for (const [field, def] of Object.entries(fields)) {
+      if (def.index) statements.push(`CREATE INDEX ${table}_${columnName(field)} ON ${table} (${columnName(field)});`);
+    }
+  }
+  return statements.join("\n");
+}
+
+export {
+  madauthSchema,
+  tableName,
+  columnName,
+  createTablesSql
+};

package/dist/chunk-AVZE6FFR.js

@@ -0,0 +1,99 @@
+// src/webhooks.ts
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "crypto";
+var WEBHOOK_TYPES = [
+  "email.verify",
+  "email.reset",
+  "email.already_registered",
+  "signup.before",
+  "user.created",
+  "email.verified",
+  "password.reset",
+  "user.signed_in"
+];
+var isEmailType = (type) => type.startsWith("email.") && type !== "email.verified";
+var SECRET_PREFIX = "whsec_";
+var WEBHOOK_TOLERANCE_SECONDS = 5 * 60;
+function generateWebhookSecret() {
+  return `${SECRET_PREFIX}${randomBytes(32).toString("base64")}`;
+}
+function checkWebhookSecret(secret) {
+  if (!secret.startsWith(SECRET_PREFIX)) return `must start with "${SECRET_PREFIX}"`;
+  const key = Buffer.from(secret.slice(SECRET_PREFIX.length), "base64");
+  if (key.length < 24 || key.length > 64) return "must contain 24 to 64 bytes in base64";
+  return null;
+}
+function hmac(secret, content) {
+  const key = Buffer.from(secret.slice(SECRET_PREFIX.length), "base64");
+  return createHmac("sha256", key).update(content).digest("base64");
+}
+function signWebhook(secret, id, timestamp, body) {
+  return `v1,${hmac(secret, `${id}.${timestamp}.${body}`)}`;
+}
+function header(headers, name) {
+  if (headers instanceof Headers) return headers.get(name) ?? void 0;
+  const key = Object.keys(headers).find((k) => k.toLowerCase() === name);
+  const value = key === void 0 ? void 0 : headers[key];
+  return Array.isArray(value) ? value[0] : value;
+}
+function verifyWebhook(secret, headers, body, options = {}) {
+  const id = header(headers, "webhook-id");
+  const timestamp = Number(header(headers, "webhook-timestamp"));
+  const signatures = header(headers, "webhook-signature");
+  if (!id || !Number.isInteger(timestamp) || !signatures || checkWebhookSecret(secret)) return false;
+  const now = Math.floor((options.now ?? Date.now()) / 1e3);
+  if (Math.abs(now - timestamp) > (options.toleranceSeconds ?? WEBHOOK_TOLERANCE_SECONDS)) return false;
+  const expected = Buffer.from(hmac(secret, `${id}.${timestamp}.${body}`));
+  return signatures.split(" ").some((entry) => {
+    const [version, signature] = entry.split(",");
+    const actual = Buffer.from(signature ?? "");
+    return version === "v1" && actual.length === expected.length && timingSafeEqual(actual, expected);
+  });
+}
+function createWebhookClient(settings, fetchImpl = fetch) {
+  const wants = (type) => isEmailType(type) || !settings.events || settings.events.has(type);
+  return {
+    wants,
+    async call(type, data, timeoutMs) {
+      if (!wants(type)) return { ok: true, body: void 0 };
+      const id = `msg_${randomUUID()}`;
+      const timestamp = Math.floor(Date.now() / 1e3);
+      const body = JSON.stringify({ type, data });
+      let response;
+      try {
+        response = await fetchImpl(settings.url, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "webhook-id": id,
+            "webhook-timestamp": String(timestamp),
+            "webhook-signature": signWebhook(settings.secret, id, timestamp, body)
+          },
+          body,
+          signal: AbortSignal.timeout(timeoutMs)
+        });
+      } catch (e) {
+        const reason = e.name === "TimeoutError" ? `no answer within ${timeoutMs} ms` : e.message;
+        return { ok: false, reason };
+      }
+      const text = await response.text().catch(() => "");
+      if (!response.ok) return { ok: false, reason: `HTTP ${response.status}` };
+      let parsed;
+      try {
+        parsed = text ? JSON.parse(text) : void 0;
+      } catch {
+        parsed = void 0;
+      }
+      return { ok: true, body: parsed };
+    }
+  };
+}
+
+export {
+  WEBHOOK_TYPES,
+  WEBHOOK_TOLERANCE_SECONDS,
+  generateWebhookSecret,
+  checkWebhookSecret,
+  signWebhook,
+  verifyWebhook,
+  createWebhookClient
+};

package/dist/chunk-JDQLSL36.js

@@ -0,0 +1,32 @@
+// src/keys.ts
+import { calculateJwkThumbprint, exportJWK, generateKeyPair, importJWK } from "jose";
+var SIGNING_ALG = "ES256";
+async function generateSigningKey() {
+  const { privateKey } = await generateKeyPair(SIGNING_ALG, { extractable: true });
+  const jwk = await exportJWK(privateKey);
+  return { ...jwk, alg: SIGNING_ALG, kid: await calculateJwkThumbprint(jwk) };
+}
+function assertPrivateSigningJwk(jwk) {
+  if (jwk.kty !== "EC" || jwk.crv !== "P-256" || !jwk.d || !jwk.x || !jwk.y) {
+    throw new Error('must be a private EC P-256 JWK (kty "EC", crv "P-256", with d, x and y)');
+  }
+}
+async function importSigningKeys(jwk) {
+  assertPrivateSigningJwk(jwk);
+  const { d: _d, ...pub } = jwk;
+  const kid = jwk.kid ?? await calculateJwkThumbprint(pub);
+  const publicJwk = { kty: pub.kty, crv: pub.crv, x: pub.x, y: pub.y, alg: SIGNING_ALG, use: "sig", kid };
+  return {
+    privateKey: await importJWK({ ...jwk, alg: SIGNING_ALG }, SIGNING_ALG),
+    publicKey: await importJWK(publicJwk, SIGNING_ALG),
+    publicJwk,
+    kid
+  };
+}
+
+export {
+  SIGNING_ALG,
+  generateSigningKey,
+  assertPrivateSigningJwk,
+  importSigningKeys
+};

package/dist/chunk-PRRKLEW7.js

@@ -0,0 +1,54 @@
+import {
+  SIGNING_ALG
+} from "./chunk-JDQLSL36.js";
+
+// src/user.ts
+var SESSION_COOKIE = "madauth_session";
+var SESSION_TYP = "madauth-session+jwt";
+
+// src/tokens.ts
+import { SignJWT, base64url, jwtVerify } from "jose";
+function randomString(bytes = 32) {
+  return base64url.encode(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+async function signToken(keys, issuer, typ, claims, ttlSeconds) {
+  return new SignJWT(claims).setProtectedHeader({ alg: SIGNING_ALG, kid: keys.kid, typ }).setIssuer(issuer).setIssuedAt().setExpirationTime(`${ttlSeconds}s`).sign(keys.privateKey);
+}
+async function readToken(keys, issuer, typ, token) {
+  if (!token) return null;
+  try {
+    const { payload } = await jwtVerify(token, keys.publicKey, { issuer, typ, algorithms: [SIGNING_ALG] });
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function signSession(keys, issuer, ttlSeconds, user, amr, extra = {}) {
+  const claims = {
+    ...extra,
+    sub: user.id,
+    email: user.email,
+    email_verified: user.email ? true : void 0,
+    name: user.name,
+    picture: user.picture,
+    amr
+  };
+  return signToken(keys, issuer, SESSION_TYP, claims, ttlSeconds);
+}
+function userFromClaims(claims) {
+  const user = { id: claims.sub };
+  if (claims.email) user.email = claims.email;
+  if (claims.name) user.name = claims.name;
+  if (claims.picture) user.picture = claims.picture;
+  return user;
+}
+
+export {
+  SESSION_COOKIE,
+  SESSION_TYP,
+  randomString,
+  signToken,
+  readToken,
+  signSession,
+  userFromClaims
+};