@madauth/server 0.1.0

package/dist/store/sqlite.d.ts

@@ -0,0 +1,9 @@
+import { S as StoreAdapter } from '../schema-Dotc6LU7.js';
+
+/**
+ * Stores madAuth's records in a SQLite file using Node's built-in `node:sqlite` (Node 22.13 or newer).
+ * Creates the tables on first use. Pass `':memory:'` for a database that lives only in memory.
+ */
+declare function createSqliteAdapter(path: string): StoreAdapter;
+
+export { createSqliteAdapter };

package/dist/testing.d.ts

@@ -0,0 +1,26 @@
+import { S as StoreAdapter } from './schema-Dotc6LU7.js';
+
+/** The parts of a test runner the contract needs; Vitest, Jest and node:test with `expect` all fit. */
+interface ContractRunner {
+    describe(name: string, fn: () => void): void;
+    it(name: string, fn: () => Promise<void>): void;
+    expect(actual: unknown): {
+        toEqual(expected: unknown): void;
+        toBe(expected: unknown): void;
+    };
+}
+/**
+ * Checks that a {@link StoreAdapter} behaves the way madAuth relies on. Run it from your own tests:
+ *
+ * ```ts
+ * import { describe, it, expect } from 'vitest';
+ * import { storeAdapterContract } from '@madauth/server/testing';
+ * storeAdapterContract({ describe, it, expect }, () => createMyAdapter(process.env.TEST_DB_URL!));
+ * ```
+ *
+ * `createAdapter` is called once per test. The tests only add records with fresh ids, so a shared test
+ * database works as well as an empty one.
+ */
+declare function storeAdapterContract(t: ContractRunner, createAdapter: () => StoreAdapter | Promise<StoreAdapter>): void;
+
+export { type ContractRunner, storeAdapterContract };

package/dist/testing.js

@@ -0,0 +1,99 @@
+// src/testing.ts
+var counter = 0;
+function unique(prefix) {
+  return `${prefix}_${Date.now().toString(36)}_${(counter++).toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function testUser(overrides = {}) {
+  const id = unique("usr_contract");
+  return {
+    id,
+    email: `${id}@Example.com`,
+    emailNormalized: `${id}@example.com`,
+    emailVerified: false,
+    name: null,
+    sessionVersion: 0,
+    lastMailAt: 0,
+    createdAt: 17e11,
+    ...overrides
+  };
+}
+function testVerification(userId) {
+  return { id: unique("ver"), userId, purpose: "reset", codeHash: "h", attempts: 0, expiresAt: 17e11 };
+}
+function storeAdapterContract(t, createAdapter) {
+  const { describe, it, expect } = t;
+  describe("madAuth store adapter contract", () => {
+    it("creates a record and finds it with the same types", async () => {
+      const store = await createAdapter();
+      const user = testUser({ emailVerified: true, name: "Ada", sessionVersion: 3 });
+      expect(await store.create("user", user)).toBe(true);
+      expect(await store.findOne("user", { id: user.id })).toEqual(user);
+      expect(await store.findOne("user", { id: unique("missing") })).toBe(null);
+    });
+    it("keeps false, 0 and null distinct", async () => {
+      const store = await createAdapter();
+      const user = testUser({ emailVerified: false, name: null, sessionVersion: 0 });
+      await store.create("user", user);
+      const found = await store.findOne("user", { id: user.id });
+      expect(found?.emailVerified).toBe(false);
+      expect(found?.name).toBe(null);
+      expect(found?.sessionVersion).toBe(0);
+    });
+    it("refuses a duplicate unique value or primary key and writes nothing", async () => {
+      const store = await createAdapter();
+      const user = testUser({ name: "Original" });
+      await store.create("user", user);
+      const sameEmail = testUser({ emailNormalized: user.emailNormalized, name: "Duplicate" });
+      expect(await store.create("user", sameEmail)).toBe(false);
+      expect(await store.findOne("user", { id: sameEmail.id })).toBe(null);
+      expect(await store.create("user", { ...testUser(), id: user.id, name: "Duplicate" })).toBe(false);
+      expect((await store.findOne("user", { id: user.id }))?.name).toBe("Original");
+    });
+    it("matches every field of the filter, including null", async () => {
+      const store = await createAdapter();
+      const user = testUser({ emailVerified: true, name: null });
+      await store.create("user", user);
+      expect((await store.findOne("user", { emailNormalized: user.emailNormalized, emailVerified: true }))?.id).toBe(user.id);
+      expect(await store.findOne("user", { emailNormalized: user.emailNormalized, emailVerified: false })).toBe(null);
+      expect((await store.findOne("user", { id: user.id, name: null }))?.id).toBe(user.id);
+    });
+    it("finds many records and honours the limit", async () => {
+      const store = await createAdapter();
+      const userId = unique("usr_contract");
+      for (let i = 0; i < 3; i++) await store.create("verification", testVerification(userId));
+      expect((await store.findMany("verification", { userId })).length).toBe(3);
+      expect((await store.findMany("verification", { userId }, { limit: 2 })).length).toBe(2);
+      expect(await store.findMany("verification", { userId: unique("nobody") })).toEqual([]);
+    });
+    it("updates only the given fields of the matching records and counts them", async () => {
+      const store = await createAdapter();
+      const user = testUser({ name: "Ada" });
+      const other = testUser({ name: "Grace" });
+      await store.create("user", user);
+      await store.create("user", other);
+      expect(await store.update("user", { id: user.id }, { emailVerified: true, sessionVersion: 1 })).toBe(1);
+      expect(await store.update("user", { id: unique("missing") }, { sessionVersion: 1 })).toBe(0);
+      expect(await store.findOne("user", { id: user.id })).toEqual({ ...user, emailVerified: true, sessionVersion: 1 });
+      expect(await store.findOne("user", { id: other.id })).toEqual(other);
+    });
+    it("deletes the matching records and counts them", async () => {
+      const store = await createAdapter();
+      const userId = unique("usr_contract");
+      const records = [testVerification(userId), testVerification(userId)];
+      for (const record of records) await store.create("verification", record);
+      expect(await store.delete("verification", { id: records[0].id })).toBe(1);
+      expect(await store.delete("verification", { id: records[0].id })).toBe(0);
+      expect(await store.findOne("verification", { id: records[1].id })).toEqual(records[1]);
+    });
+    it("reports a deleted record to only one of several concurrent deletes", async () => {
+      const store = await createAdapter();
+      const record = testVerification(unique("usr_contract"));
+      await store.create("verification", record);
+      const counts = await Promise.all(Array.from({ length: 10 }, () => store.delete("verification", { id: record.id })));
+      expect(counts.reduce((sum, n) => sum + n, 0)).toBe(1);
+    });
+  });
+}
+export {
+  storeAdapterContract
+};

package/dist/user-3DDyggFV.d.ts

@@ -0,0 +1,10 @@
+/** The signed-in user as returned to apps. */
+interface MadauthUser {
+    /** Stable id, e.g. `google:<sub>`. */
+    id: string;
+    email?: string;
+    name?: string;
+    picture?: string;
+}
+
+export type { MadauthUser as M };

package/dist/verify.d.ts

@@ -0,0 +1,24 @@
+import { JWTVerifyGetKey } from 'jose';
+import { M as MadauthUser } from './user-3DDyggFV.js';
+
+interface SessionVerifierOptions {
+    /** The madAuth server's public base URL (its MADAUTH_ISSUER). */
+    issuer: string;
+    /** Keys to verify with. Defaults to `<issuer>/.well-known/jwks.json` (fetched once, then cached). */
+    jwks?: JWTVerifyGetKey;
+}
+/** Verifies a madAuth session for an app backend. Resolves to the user, or null if there is no valid session. */
+type SessionVerifier = (input: Request | string) => Promise<MadauthUser | null>;
+/**
+ * Creates a function that checks madAuth sessions in your own backend (any Web-standard runtime).
+ * It accepts a `Request` (session cookie or `Authorization: Bearer`), a `Cookie` header or a bare token.
+ *
+ * ```ts
+ * const verifySession = createSessionVerifier({ issuer: 'https://auth.example.com' });
+ * const user = await verifySession(request);
+ * if (!user) return new Response('Unauthorized', { status: 401 });
+ * ```
+ */
+declare function createSessionVerifier(opts: SessionVerifierOptions): SessionVerifier;
+
+export { MadauthUser, type SessionVerifier, type SessionVerifierOptions, createSessionVerifier };

package/dist/verify.js

@@ -0,0 +1,48 @@
+import {
+  SESSION_COOKIE,
+  SESSION_TYP,
+  userFromClaims
+} from "./chunk-PRRKLEW7.js";
+import {
+  SIGNING_ALG
+} from "./chunk-JDQLSL36.js";
+
+// src/verify.ts
+import { createRemoteJWKSet, jwtVerify } from "jose";
+function tokenFromCookieHeader(header) {
+  for (const part of header?.split(";") ?? []) {
+    const [name, ...value] = part.trim().split("=");
+    if (name === SESSION_COOKIE) return decodeURIComponent(value.join("="));
+  }
+  return void 0;
+}
+function tokenFrom(input) {
+  if (typeof input !== "string") {
+    const auth = input.headers.get("authorization");
+    if (auth?.toLowerCase().startsWith("bearer ")) return auth.slice(7).trim();
+    return tokenFromCookieHeader(input.headers.get("cookie"));
+  }
+  return input.includes(`${SESSION_COOKIE}=`) ? tokenFromCookieHeader(input) : input.trim() || void 0;
+}
+function createSessionVerifier(opts) {
+  const issuer = opts.issuer.replace(/\/+$/, "");
+  const keys = opts.jwks ?? createRemoteJWKSet(new URL(`${issuer}/.well-known/jwks.json`));
+  return async (input) => {
+    try {
+      const token = tokenFrom(input);
+      if (!token) return null;
+      const { payload } = await jwtVerify(token, keys, {
+        issuer,
+        typ: SESSION_TYP,
+        algorithms: [SIGNING_ALG]
+      });
+      if (typeof payload.sub !== "string") return null;
+      return userFromClaims(payload);
+    } catch {
+      return null;
+    }
+  };
+}
+export {
+  createSessionVerifier
+};

package/dist/webhook-CT80emTQ.d.ts

@@ -0,0 +1,31 @@
+/** Every `type` madAuth sends. */
+declare const WEBHOOK_TYPES: readonly ["email.verify", "email.reset", "email.already_registered", "signup.before", "user.created", "email.verified", "password.reset", "user.signed_in"];
+type WebhookType = (typeof WEBHOOK_TYPES)[number];
+/** How old a call may be before receivers reject it, so a captured call can't be replayed. */
+declare const WEBHOOK_TOLERANCE_SECONDS: number;
+/** A new secret for WEBHOOK_SECRET: `whsec_` and 32 random bytes in base64. */
+declare function generateWebhookSecret(): string;
+/** The `webhook-signature` header value for a call: `v1,<base64 HMAC-SHA256 of "id.timestamp.body">`. */
+declare function signWebhook(secret: string, id: string, timestamp: number, body: string): string;
+type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+/**
+ * Checks that a webhook call came from madAuth: the signature matches `body` (the raw request body, as
+ * received) and the call is at most five minutes old. For receivers written in JavaScript:
+ *
+ * ```ts
+ * import { verifyWebhook } from '@madauth/server/webhook';
+ * if (!verifyWebhook(process.env.WEBHOOK_SECRET!, request.headers, rawBody)) return new Response(null, { status: 401 });
+ * ```
+ */
+declare function verifyWebhook(secret: string, headers: HeaderSource, body: string, options?: {
+    now?: number;
+    toleranceSeconds?: number;
+}): boolean;
+interface WebhookSettings {
+    url: string;
+    secret: string;
+    /** Types to send besides the e-mails (WEBHOOK_EVENTS); null sends every type. */
+    events: ReadonlySet<string> | null;
+}
+
+export { type WebhookSettings as W, WEBHOOK_TOLERANCE_SECONDS as a, WEBHOOK_TYPES as b, type WebhookType as c, generateWebhookSecret as g, signWebhook as s, verifyWebhook as v };

package/dist/webhook.d.ts

@@ -0,0 +1 @@
+export { a as WEBHOOK_TOLERANCE_SECONDS, b as WEBHOOK_TYPES, c as WebhookType, g as generateWebhookSecret, s as signWebhook, v as verifyWebhook } from './webhook-CT80emTQ.js';

package/dist/webhook.js

@@ -0,0 +1,14 @@
+import {
+  WEBHOOK_TOLERANCE_SECONDS,
+  WEBHOOK_TYPES,
+  generateWebhookSecret,
+  signWebhook,
+  verifyWebhook
+} from "./chunk-AVZE6FFR.js";
+export {
+  WEBHOOK_TOLERANCE_SECONDS,
+  WEBHOOK_TYPES,
+  generateWebhookSecret,
+  signWebhook,
+  verifyWebhook
+};

package/package.json

@@ -0,0 +1,109 @@
+{
+  "name": "@madauth/server",
+  "version": "0.1.0",
+  "description": "madAuth server: Google and e-mail & password sign-in with madAuth sessions, for Docker, AWS Lambda and Azure Functions.",
+  "license": "MIT",
+  "author": "David Neuy",
+  "homepage": "https://github.com/inouiw/madAuth#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inouiw/madAuth.git",
+    "directory": "packages/server"
+  },
+  "bugs": {
+    "url": "https://github.com/inouiw/madAuth/issues"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "login",
+    "sign-in",
+    "google-sign-in",
+    "session",
+    "jwt",
+    "hono",
+    "aws-lambda",
+    "azure-functions"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./verify": {
+      "types": "./dist/verify.d.ts",
+      "import": "./dist/verify.js"
+    },
+    "./sqlite": {
+      "types": "./dist/store/sqlite.d.ts",
+      "import": "./dist/sqlite.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./webhook": {
+      "types": "./dist/webhook.d.ts",
+      "import": "./dist/webhook.js"
+    },
+    "./node": {
+      "types": "./dist/entry/node.d.ts",
+      "import": "./dist/entry/node.js"
+    },
+    "./lambda": {
+      "types": "./dist/entry/lambda.d.ts",
+      "import": "./dist/entry/lambda.js"
+    },
+    "./azure": {
+      "types": "./dist/entry/azure.d.ts",
+      "import": "./dist/entry/azure.js"
+    }
+  },
+  "bin": {
+    "madauth-server": "dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx watch --env-file-if-exists=.env src/main.ts",
+    "start": "node --env-file-if-exists=.env dist/standalone/main.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "generate-key": "tsx src/bin.ts generate-key",
+    "cli": "tsx --env-file-if-exists=.env src/bin.ts"
+  },
+  "dependencies": {
+    "@hono/node-server": "^2.1.3",
+    "hono": "^4.13.12",
+    "jose": "^6.2.12"
+  },
+  "peerDependencies": {
+    "@azure/functions": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@azure/functions": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@azure/functions": "^4.16.5",
+    "@types/aws-lambda": "^8.10.164",
+    "@types/node": "^26.6.4",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}