@nabhiraj/nab-auth 0.1.1 → 1.0.0

package/README.md

@@ -2,32 +2,36 @@
 
 [![license](https://img.shields.io/npm/l/@nabhiraj/nab-auth.svg)](LICENSE)
 
-Configurable authentication for Express and MongoDB. `nab-auth` provides
-Argon2id password hashing, RS256 JWTs, refresh-token rotation, roles,
-registration verification, and optional two-factor authentication.
+`@nabhiraj/nab-auth` is a configurable Express authentication library. It
+provides Argon2id password hashing, RS256 access and refresh tokens, roles,
+registration verification, and optional two-factor authentication. Storage is
+provided by an explicit adapter: MongoDB/Atlas support is bundled, while other
+databases can be added by implementing the auth-store contract.
 
-The library does not load environment variables or send email/SMS itself. The
-host application owns configuration and code delivery.
+The host application owns environment loading, database credentials, JWT key
+locations, and email/SMS delivery. The library does not load `.env` files or
+send messages itself.
 
 ## Features
 
-- Email/password registration and login with Argon2id password hashes
-- Short-lived RS256 access tokens and rotating refresh-token cookies
-- Public-key rotation using JWT `kid` headers
-- Role claims and administrator-protected role management
+- Email/password registration and login with Argon2id hashes
+- RS256 access tokens and refresh-token cookies
+- JWT `kid` support for public-key rotation
+- Role claims and administrator-protected role endpoints
 - Optional registration-code verification and two-factor authentication
-- MongoDB/Atlas storage with unique and TTL indexes created automatically
-- Verifier-only mode for services that only need to validate access tokens
+- Explicit database adapters; MongoDB/Atlas adapter included
+- Verifier-only mode for services that only validate access tokens
 
 ## Requirements
 
-- Node.js 20 or later
-- Express 5
-- MongoDB or MongoDB Atlas
-- An RSA key pair for RS256 JWT signing
+- Node.js 20 or newer
+- Express 5 (peer dependency)
+- An RSA key pair for RS256 signing and verification
+- A database adapter for services that register users, issue tokens, or use
+  the authentication router
 
-`argon2` is a native dependency. Most supported systems use a prebuilt binary;
-unusual platforms may need standard Node.js native build tools.
+`argon2` is a native dependency. Most platforms use a prebuilt binary; unusual
+platforms may require standard Node.js native build tools.
 
 ## Installation
 
@@ -35,26 +39,40 @@ unusual platforms may need standard Node.js native build tools.
 npm install @nabhiraj/nab-auth express
 ```
 
-## Quick start
+## Quick start: MongoDB
+
+The application loads its own environment configuration and passes the values
+to the adapter. The library does not require a particular `.env` package or
+variable naming convention.
 
 ```js
+import "dotenv/config";
 import express from "express";
-import { createAuthenticationLibrary } from "@nabhiraj/nab-auth";
+import {
+  createAuthenticationLibrary,
+  createMongoAuthStore
+} from "@nabhiraj/nab-auth";
 
 const app = express();
 app.use(express.json());
 
 const auth = createAuthenticationLibrary({
-  mongo: {
-    uri: process.env.MY_AUTH_MONGO_URI,
-    databaseName: "my_auth_database"
+  database: {
+    adapter: createMongoAuthStore,
+    adapterConfig: {
+      uri: process.env.MONGODB_URI,
+      databaseName: process.env.MONGODB_DB_NAME,
+      usersCollectionName: process.env.MONGODB_USERS_COLLECTION || "users",
+      potentialUsersCollectionName:
+        process.env.MONGODB_POTENTIAL_USERS_COLLECTION || "potential_users"
+    }
   },
   jwt: {
-    issuer: "my-service",
-    audience: "my-client",
+    issuer: process.env.JWT_ISSUER,
+    audience: process.env.JWT_AUDIENCE,
     keys: {
-      privateKeyPath: process.env.MY_JWT_PRIVATE_KEY_PATH,
-      publicKeyPath: process.env.MY_JWT_PUBLIC_KEY_PATH
+      privateKeyPath: process.env.JWT_PRIVATE_KEY_PATH,
+      publicKeyPath: process.env.JWT_PUBLIC_KEY_PATH
     }
   },
   defaultAdmin: { enabled: false }
@@ -69,10 +87,10 @@ app.use(
   "/auth",
   auth.createAuthRouter(createTokenPayload, {
     sendRegistrationCode: async ({ email, verificationCode }) => {
-      await sendEmail(email, `Your verification code is ${verificationCode}`);
+      await emailProvider.send(email, `Your verification code is ${verificationCode}`);
     },
     sendTwoFactorCode: async ({ email, verificationCode }) => {
-      await sendEmail(email, `Your 2FA code is ${verificationCode}`);
+      await emailProvider.send(email, `Your 2FA code is ${verificationCode}`);
     }
   })
 );
@@ -86,49 +104,139 @@ await auth.connectToDatabase();
 app.listen(3000);
 ```
 
-`sendEmail` is an application function you provide. Configure a code-delivery
-callback only when registration verification or two-factor authentication is
-enabled.
+The order matters: call `connectToDatabase()` before receiving requests, and
+mount `jwtErrorHandler` after routes that use `requireJwt`.
 
 ## Core API
 
 ```js
 import {
+  assertAuthStore,
+  authStoreMethods,
   createAuthenticationLibrary,
   createFileJwtKeyProvider,
+  createMongoAuthStore,
   defaultAuthConfig
 } from "@nabhiraj/nab-auth";
 ```
 
-`createAuthenticationLibrary(config)` creates isolated state: its MongoDB
-client, JWT-key cache, middleware, and router do not share state with another
+`createAuthenticationLibrary(config)` creates isolated state. Its adapter,
+JWT-key cache, middleware, and router are not shared with another library
 instance.
 
 | Member | Purpose |
 | --- | --- |
-| `connectToDatabase()` | Connects to MongoDB and creates configured collections/indexes. |
-| `closeDatabase()` | Closes this instance's MongoDB client. |
-| `createAuthRouter(payloadFactory, options)` | Creates the Express authentication router. |
-| `requireJwt` | Verifies access tokens and sets claims on `req.auth`. |
-| `requireNabAdmin` | Requires the configured administrator role. |
-| `jwtErrorHandler` | Express JWT error middleware; mount after protected routes. |
-| `config` | The merged configuration used by this instance. |
+| `connectToDatabase()` | Creates the configured adapter, connects it, and creates the default admin when enabled. |
+| `closeDatabase()` | Closes the adapter if it was created. |
+| `createAuthRouter(payloadFactory, options)` | Creates the storage-backed Express authentication router. |
+| `requireJwt` | Validates an access token and sets claims on `req.auth`. |
+| `requireNabAdmin` | Requires the configured administrator role after `requireJwt`. |
+| `jwtErrorHandler` | Converts `express-jwt` authentication failures to a `401` response. |
+| `config` | The merged configuration for this library instance. |
+
+`payloadFactory(user)` must return an object. Its properties are included in
+new access tokens; the library adds `sub`, JWT metadata, and
+`tokenType: "access"`.
+
+## Database adapters
+
+There is no default database. A storage-backed service must configure
+`database.adapter` as a factory function and pass adapter-specific values in
+`database.adapterConfig`.
+
+```js
+const auth = createAuthenticationLibrary({
+  database: {
+    adapter: createPostgresAuthStore,
+    adapterConfig: {
+      connectionString: process.env.DATABASE_URL,
+      usersTableName: "users",
+      pendingUsersTableName: "pending_users"
+    }
+  }
+});
+```
+
+Import the adapter in the application and pass the function itself. Do not pass
+a source-file path or make the library dynamically load a module.
+
+### MongoDB adapter
+
+The package exports `createMongoAuthStore`. Its adapter configuration is:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `uri` | Yes | MongoDB or MongoDB Atlas connection URI. |
+| `databaseName` | Yes | Database used exclusively for auth data. |
+| `usersCollectionName` | Yes | Collection for permanent user records. |
+| `potentialUsersCollectionName` | Yes | Collection for pending registration records. |
+
+On `connect()`, the Mongo adapter creates missing collections and indexes:
+
+- Unique indexes for `users.email` and `users.user_id`
+- A unique index for pending-user `email`
+- A TTL index on pending-user `expiresAt`
+
+It also migrates existing Mongo user records that lack `user_id` or `nab_role`.
+
+### Custom adapter contract
+
+An adapter factory receives `adapterConfig` and returns an object that
+implements every method below. `assertAuthStore(store)` validates the shape,
+and `authStoreMethods` exports the method names.
+
+| Method | Required behavior |
+| --- | --- |
+| `connect()` | Open the database connection and prepare storage. |
+| `close()` | Release the database connection/resources. |
+| `findUserByEmail(email)` | Return the user record or `null`. |
+| `findUserByUserId(userId)` | Return the user record or `null`. |
+| `createUser(user)` | Persist the user and return `true`; return `false` when its email already exists. |
+| `upsertPotentialUser(email, hash, generatedAt, expiresAt)` | Create/update the pending registration; return `false` when the email is already registered. |
+| `findPotentialUserByEmail(email)` | Return the pending record or `null`. |
+| `deletePotentialUserByEmail(email)` | Delete the pending registration if present. |
+| `updateUserPassword(userId, hash)` | Update the password hash; return whether a user matched. |
+| `updateUserTwoFactorCode(userId, hash, generatedAt, expiresAt)` | Store a new 2FA code hash; return whether a user matched. |
+| `consumeUserTwoFactorCode(userId, hash)` | Atomically consume exactly that unused 2FA hash; return whether it was consumed. |
+| `addUserRoles(userId, roles)` | Add unique roles and return the updated user or `null`. |
+| `removeUserRole(userId, role)` | Remove a role and return the updated user or `null`. |
+| `replaceUserRoles(userId, roles)` | Replace all roles and return the updated user or `null`. |
+
+User records returned by an adapter must provide at least:
 
-`payloadFactory(user)` creates application-specific access-token claims. The
-library adds standard JWT claims, `sub`, and `tokenType: "access"`.
+```js
+{
+  user_id: "uuid",
+  email: "person@example.com",
+  passwordHash: "argon2 hash",
+  nab_role: ["role"],
+  createdAt: new Date()
+}
+```
+
+Pending records must provide `verificationCodeHash` and `codeExpiresAt` as a
+JavaScript `Date`. User records with a pending 2FA challenge use
+`twoFactorCodeHash` and `twoFactorCodeExpiresAt`.
+
+The core normalizes email before it invokes the store. Custom adapters should
+preserve that normalized email value and enforce unique email storage.
 
 ## Configuration
 
-Every setting is optional unless a feature needs it. Omitted values use
-`defaultAuthConfig`.
+All settings use `defaultAuthConfig` when omitted. `database.adapter` is
+required before calling `connectToDatabase()` or `createAuthRouter()`. A
+verifier-only service can omit it.
 
 ```js
 const auth = createAuthenticationLibrary({
-  mongo: {
-    uri: process.env.MY_AUTH_MONGO_URI,
-    databaseName: "auth_db",
-    usersCollectionName: "users",
-    potentialUsersCollectionName: "potential_user"
+  database: {
+    adapter: createMongoAuthStore,
+    adapterConfig: {
+      uri: process.env.MONGODB_URI,
+      databaseName: process.env.MONGODB_DB_NAME,
+      usersCollectionName: "users",
+      potentialUsersCollectionName: "potential_users"
+    }
   },
   jwt: {
     issuer: "my-service",
@@ -138,8 +246,8 @@ const auth = createAuthenticationLibrary({
     refreshTokenTtl: "7d",
     keyCacheTtlMs: 15 * 60 * 1000,
     keys: {
-      privateKeyPath: process.env.MY_PRIVATE_KEY_PATH,
-      publicKeyPath: process.env.MY_PUBLIC_KEY_PATH
+      privateKeyPath: process.env.JWT_PRIVATE_KEY_PATH,
+      publicKeyPath: process.env.JWT_PUBLIC_KEY_PATH
     }
   },
   authorization: {
@@ -158,11 +266,6 @@ const auth = createAuthenticationLibrary({
     codeDigits: 6,
     codeTtlMs: 10 * 60 * 1000
   },
-  passwordHash: {
-    memoryCost: 19456,
-    timeCost: 2,
-    parallelism: 1
-  },
   refreshCookie: {
     name: "refresh_token",
     httpOnly: true,
@@ -176,57 +279,55 @@ const auth = createAuthenticationLibrary({
   },
   defaultAdmin: {
     enabled: false,
-    email: "admin@admin.com",
-    password: "change-this",
+    email: "admin@example.com",
+    password: "use-a-strong-secret",
     roles: ["nab_admin"]
   }
 });
 ```
 
-Use `refreshCookie.secure: true` for HTTPS production deployments. It defaults
-to `false` only for local HTTP development. `defaultAdmin.enabled` defaults to
-`false`; never enable it with a known or weak password.
+`refreshCookie.secure` defaults to `false` for local HTTP development; set it
+to `true` for HTTPS production deployments. `defaultAdmin.enabled` defaults to
+`false`; do not enable it with a known or weak password.
+
+### Registration and authorization policy
+
+| Setting | Effect |
+| --- | --- |
+| `registration.verificationRequired` | Requires a valid registration code on `POST /register`. |
+| `twoFactor.required` | Requires a valid 2FA code before issuing tokens. |
+| `authorization.userRegistrationRequiresNabAdmin` | Requires a JWT-bearing administrator to register users. |
+| `authorization.passwordChangeRequiresNabAdmin` | Requires a JWT-bearing administrator for all password changes. |
+| `authorization.nabAdminCanChangeOtherUsersPasswords` | Lets an administrator change another user’s password when admin-only password changes are disabled. |
 
 ### Code delivery callbacks
 
+Supply callbacks only if the associated feature is enabled:
+
 ```js
 auth.createAuthRouter(createTokenPayload, {
-  sendRegistrationCode: async ({
-    email,
-    verificationCode,
-    codeGeneratedAt,
-    codeExpiresAt
-  }) => {
+  sendRegistrationCode: async ({ email, verificationCode }) => {
     await emailProvider.send(email, verificationCode);
   },
-  sendTwoFactorCode: async ({
-    email,
-    verificationCode,
-    codeGeneratedAt,
-    codeExpiresAt
-  }) => {
+  sendTwoFactorCode: async ({ email, verificationCode }) => {
     await smsProvider.send(email, verificationCode);
   }
 });
 ```
 
-`codeDelivery.allowCodeInResponseWithoutSender` controls missing callbacks:
+`codeDelivery.allowCodeInResponseWithoutSender` controls a missing callback:
 
-- `true` returns the generated code in the HTTP response. Use only for local
+- `true`: returns the generated code in the HTTP response. Use only for local
   development or automated tests.
-- `false` rejects the request when the required sender callback is absent. Use
-  this in production.
-
-Registration codes are stored as Argon2id hashes in `potential_user` and are
-removed by a MongoDB TTL index. 2FA code hashes are stored on the user and are
-atomically consumed after a successful token issue.
+- `false`: the route fails when a required callback is absent. Use this in
+  production.
 
-## JWT key files and rotation
+## JWT keys and rotation
 
-The built-in key provider loads JSON files lazily and refreshes its cache after
+The built-in file key provider loads JSON files lazily and caches them for
 `jwt.keyCacheTtlMs`.
 
-Private-key JSON has one active signing key:
+Private-key JSON contains the active signing key:
 
 ```json
 {
@@ -235,7 +336,7 @@ Private-key JSON has one active signing key:
 }
 ```
 
-Public-key JSON keeps each currently valid verification key:
+Public-key JSON contains every currently valid verification key:
 
 ```json
 {
@@ -251,84 +352,67 @@ Public-key JSON keeps each currently valid verification key:
 Rotation process:
 
 1. Add the new public key and `kid` to the public-key JSON.
-2. Switch the active private-key JSON to the matching new key and `kid`.
-3. Keep the previous public key until all tokens signed by it have expired.
+2. Switch the private-key JSON to the matching active key and `kid`.
+3. Keep the old public key until tokens signed by it have expired.
 
-Never commit or publish private keys.
-
-### Custom key provider
-
-Use a key provider for KMS, Vault, or a secret manager:
+Never commit private keys. For KMS, Vault, or another secret manager, provide
+`jwt.keyProvider` instead:
 
 ```js
-const auth = createAuthenticationLibrary({
-  jwt: {
-    keyProvider: {
-      async getActiveSigningKey() {
-        return {
-          keyId: "101",
-          privateKey: await secretManager.getActivePrivateKey()
-        };
-      },
-      async getPublicKey(keyId) {
-        return secretManager.getPublicKey(keyId);
-      }
+jwt: {
+  keyProvider: {
+    async getActiveSigningKey() {
+      return {
+        keyId: "101",
+        privateKey: await secretManager.getActivePrivateKey()
+      };
+    },
+    async getPublicKey(keyId) {
+      return secretManager.getPublicKey(keyId);
     }
   }
-});
+}
 ```
 
-When `jwt.keyProvider` is supplied, the file paths are not used.
+When `jwt.keyProvider` is present, `jwt.keys` is not used.
 
 ## HTTP API
 
-Assume the router is mounted at `/auth`.
-
-| Method and route | Request body | Description |
-| --- | --- | --- |
-| `POST /auth/potential-users` | `email` | Generates or refreshes a registration code for an unregistered email. |
-| `POST /auth/register` | `email`, `password`, optional `verificationCode` | Creates a user. The code is required when verification is enabled. |
-| `POST /auth/token` | `email`, `password`, optional `twoFactorCode` | Issues an access token and refresh-token cookie. |
-| `POST /auth/refresh` | Optional `refresh_token` | Returns a new access token and refresh-token cookie; falls back to cookie. |
-| `POST /auth/2fa/code` | `email`, `password` | Generates or refreshes a 2FA code when 2FA is enabled. |
-| `PATCH /auth/password` | `newPassword`, optional `user_id` or `email` | Changes own password, or another user's if policy allows. |
-| `POST /auth/roles` | `roles`, exactly one of `user_id` or `email` | Adds roles. Requires administrator access token. |
-| `DELETE /auth/roles` | `role`, exactly one of `user_id` or `email` | Removes one role. Requires administrator access token. |
-| `PUT /auth/roles` | `roles`, exactly one of `user_id` or `email` | Replaces all roles. Requires administrator access token. |
-
-Access tokens include the application payload and access-token metadata.
-Refresh tokens contain only the subject and required token metadata, not the
-complete application payload.
-
-## Data stored in MongoDB
-
-The users collection contains documents like:
-
-```json
-{
-  "user_id": "2d6c2f40-0a3f-4b2e-9d8c-8f3b7f6e1a20",
-  "email": "alice@example.com",
-  "passwordHash": "<Argon2id hash>",
-  "nab_role": ["editor"],
-  "createdAt": "2026-01-01T00:00:00.000Z"
-}
-```
-
-The library creates unique indexes for `email` and `user_id`, and creates the
-pending-registration collection plus its TTL index.
+Mount the router at `/auth` to use these routes:
+
+| Method and route | Request body | Success | Notes |
+| --- | --- | --- | --- |
+| `POST /auth/potential-users` | `email` | `201` or `202` | Starts/refreshes registration verification. `202` is used when a sender callback is configured. |
+| `POST /auth/register` | `email`, `password`, optional `verificationCode` | `201` | Code required when registration verification is enabled. |
+| `POST /auth/token` | `email`, `password`, optional `twoFactorCode` | `200` | Returns access token and sets refresh-token cookie. |
+| `POST /auth/refresh` | Optional `refresh_token` | `200` | Uses body token first, then the configured cookie. Issues a new refresh token. |
+| `POST /auth/2fa/code` | `email`, `password` | `201` or `202` | Only useful when 2FA is enabled. |
+| `PATCH /auth/password` | `newPassword`, optional `user_id` or `email` | `204` | Requires JWT; authorization settings can require admin access. |
+| `POST /auth/roles` | `roles`, exactly one of `user_id` or `email` | `200` | Requires administrator access token. |
+| `DELETE /auth/roles` | `role`, exactly one of `user_id` or `email` | `200` | Requires administrator access token. |
+| `PUT /auth/roles` | `roles`, exactly one of `user_id` or `email` | `200` | Requires administrator access token. |
+
+Access tokens include the application payload. Refresh tokens contain only the
+subject and token metadata. The library does not persist refresh tokens or
+revoke previously issued refresh tokens; the host application should add a
+token-revocation strategy if that is required.
 
 ## Verifier-only service
 
-A business service that only verifies access tokens does not need MongoDB or a
+A service that only validates access tokens needs no database adapter and no
 private key:
 
 ```js
+import express from "express";
+import { createAuthenticationLibrary } from "@nabhiraj/nab-auth";
+
+const app = express();
 const auth = createAuthenticationLibrary({
   jwt: {
     issuer: "my-service",
     audience: "my-client",
     keys: {
-      publicKeyPath: process.env.MY_JWT_PUBLIC_KEY_PATH
+      publicKeyPath: process.env.JWT_PUBLIC_KEY_PATH
     }
   }
 });
@@ -340,16 +424,39 @@ app.get("/api/business-data", auth.requireJwt, (req, res) => {
 app.use(auth.jwtErrorHandler);
 ```
 
+Do not call `connectToDatabase()` or `createAuthRouter()` in this mode.
+
+## Testing
+
+Run unit and adapter-contract tests:
+
+```bash
+npm test
+```
+
+Run the opt-in live MongoDB end-to-end suite only with dedicated test
+credentials and an isolated test database:
+
+```bash
+npm run test:e2e:mongo
+```
+
+See [E2E_TEST_PLAN.md](E2E_TEST_PLAN.md) for required endpoint and
+configuration coverage. Never point live tests at the host application’s
+database.
+
 ## Production checklist
 
-- Use HTTPS and `refreshCookie.secure: true` in production.
-- Set `codeDelivery.allowCodeInResponseWithoutSender: false` in production.
-- Provide real email/SMS delivery callbacks for codes.
-- Keep private keys and MongoDB credentials outside source control.
-- Add application-level rate limits to login, registration, code-generation,
-  and password-change routes.
-- Configure CORS and cookie `sameSite` settings for your frontend topology.
-- Retain old public keys until tokens signed by them expire.
+- Keep database credentials and private keys outside source control.
+- Use HTTPS and `refreshCookie.secure: true`.
+- Set `codeDelivery.allowCodeInResponseWithoutSender: false`.
+- Provide real code-delivery callbacks for enabled verification features.
+- Add application-level rate limits to login, registration, code generation,
+  refresh, and password-change routes.
+- Configure CORS and `sameSite` for the frontend topology.
+- Retain old public keys until every token signed with them expires.
+- Define refresh-token revocation if logout, breach response, or session
+  invalidation requires it.
 
 ## Support and contributing
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nabhiraj/nab-auth",
-  "version": "0.1.1",
-  "description": "Configurable Express, MongoDB, JWT, registration verification, and 2FA authentication library",
+  "version": "1.0.0",
+  "description": "Configurable Express authentication library with pluggable database adapters, JWT, registration verification, and 2FA",
   "type": "module",
   "main": "./src/authenticationLogic/index.js",
   "exports": {

package/src/authenticationLogic/adapters/authStore.js

@@ -0,0 +1,28 @@
+export const authStoreMethods = [
+  "connect",
+  "close",
+  "findUserByEmail",
+  "findUserByUserId",
+  "createUser",
+  "upsertPotentialUser",
+  "findPotentialUserByEmail",
+  "deletePotentialUserByEmail",
+  "updateUserPassword",
+  "updateUserTwoFactorCode",
+  "consumeUserTwoFactorCode",
+  "addUserRoles",
+  "removeUserRole",
+  "replaceUserRoles"
+];
+
+export function assertAuthStore(store) {
+  if (!store || typeof store !== "object") {
+    throw new TypeError("database.adapter must be an auth store object");
+  }
+
+  for (const method of authStoreMethods) {
+    if (typeof store[method] !== "function") {
+      throw new TypeError(`database.adapter must provide a ${method} function`);
+    }
+  }
+}

package/src/authenticationLogic/{repositories/userRepository.js → adapters/mongoAuthStore.js}

@@ -1,8 +1,8 @@
 import { randomUUID } from "node:crypto";
-import argon2 from "argon2";
 import { MongoClient } from "mongodb";
+import { normalizeEmail } from "../utils/normalizeEmail.js";
 
-export function createUserRepository({ mongo, defaultAdmin, passwordHash }) {
+export function createMongoAuthStore(mongo) {
   let client;
   let usersCollection;
   let potentialUsersCollection;
@@ -29,57 +29,10 @@ export function createUserRepository({ mongo, defaultAdmin, passwordHash }) {
     return usersCollection.findOne({ user_id: userId });
   }
 
-  async function insertUser(email, passwordHashValue) {
-    requireUsersCollection();
-    const userId = randomUUID();
-
-    await usersCollection.insertOne({
-      user_id: userId,
-      email: normalizeEmail(email),
-      passwordHash: passwordHashValue,
-      nab_role: [],
-      createdAt: new Date()
-    });
-
-    return userId;
-  }
-
-  async function ensureDefaultAdminUser() {
-    if (!defaultAdmin.enabled) {
-      return;
-    }
-
-    const existingAdmin = await findUserByEmail(defaultAdmin.email);
-
-    if (existingAdmin) {
-      return;
-    }
-
-    const passwordHashValue = await argon2.hash(defaultAdmin.password, {
-      type: argon2.argon2id,
-      ...passwordHash
-    });
-
-    try {
-      const userId = randomUUID();
-      await usersCollection.insertOne({
-        user_id: userId,
-        email: normalizeEmail(defaultAdmin.email),
-        passwordHash: passwordHashValue,
-        nab_role: defaultAdmin.roles,
-        createdAt: new Date()
-      });
-    } catch (error) {
-      if (error.code !== 11000) {
-        throw error;
-      }
-    }
-  }
-
   return {
-    async connectToDatabase() {
+    async connect() {
       if (usersCollection) {
-        return usersCollection;
+        return;
       }
 
       if (typeof mongo.uri !== "string" || !mongo.uri) {
@@ -107,12 +60,9 @@ export function createUserRepository({ mongo, defaultAdmin, passwordHash }) {
         { expiresAt: 1 },
         { expireAfterSeconds: 0 }
       );
-      await ensureDefaultAdminUser();
-
-      return usersCollection;
     },
 
-    async closeDatabase() {
+    async close() {
       usersCollection = undefined;
       potentialUsersCollection = undefined;
 
@@ -124,7 +74,25 @@ export function createUserRepository({ mongo, defaultAdmin, passwordHash }) {
 
     findUserByEmail,
     findUserByUserId,
-    insertUser,
+
+    async createUser(user) {
+      requireUsersCollection();
+
+      try {
+        await usersCollection.insertOne({
+          ...user,
+          email: normalizeEmail(user.email),
+          nab_role: user.nab_role || [],
+          createdAt: user.createdAt || new Date()
+        });
+        return true;
+      } catch (error) {
+        if (error.code === 11000) {
+          return false;
+        }
+        throw error;
+      }
+    },
 
     async upsertPotentialUser(
       email,
@@ -275,7 +243,3 @@ async function updateUserRoles(usersCollection, userId, update) {
 
   return usersCollection.findOne({ user_id: userId });
 }
-
-export function normalizeEmail(email) {
-  return email.trim().toLowerCase();
-}

package/src/authenticationLogic/config/createAuthConfig.js

@@ -15,6 +15,13 @@ export function createAuthConfig(overrides = {}) {
   validateCodeConfig(config.twoFactor, "twoFactor", "required");
   validateString(config.authorization.adminRole, "authorization.adminRole");
 
+  if (
+    config.database.adapter !== undefined &&
+    typeof config.database.adapter !== "function"
+  ) {
+    throw new TypeError("database.adapter must be an adapter factory function");
+  }
+
   if (typeof config.codeDelivery.allowCodeInResponseWithoutSender !== "boolean") {
     throw new TypeError(
       "codeDelivery.allowCodeInResponseWithoutSender must be a boolean"

package/src/authenticationLogic/config/defaultAuthConfig.js

@@ -1,9 +1,7 @@
 export const defaultAuthConfig = {
-  mongo: {
-    uri: undefined,
-    databaseName: "jwt_auth_demo",
-    usersCollectionName: "users",
-    potentialUsersCollectionName: "potential_user"
+  database: {
+    adapter: undefined,
+    adapterConfig: undefined
   },
   jwt: {
     issuer: "jwt-express-demo",

package/src/authenticationLogic/controllers/authController.js

@@ -1,6 +1,7 @@
 import argon2 from "argon2";
+import { randomUUID } from "node:crypto";
 import { parseCookie } from "cookie";
-import { normalizeEmail } from "../repositories/userRepository.js";
+import { normalizeEmail } from "../utils/normalizeEmail.js";
 import {
   generateNumericVerificationCode,
   hashVerificationCode,
@@ -170,23 +171,24 @@ export function createAuthController({
         }
       }
 
-      try {
-        const userId = await repository.insertUser(
-          normalizedEmail,
-          await hashPassword(password, config.passwordHash)
-        );
+      const userId = randomUUID();
+      const userCreated = await repository.createUser({
+        user_id: userId,
+        email: normalizedEmail,
+        passwordHash: await hashPassword(password, config.passwordHash),
+        nab_role: [],
+        createdAt: new Date()
+      });
 
-        if (config.registration.verificationRequired) {
-          await repository.deletePotentialUserByEmail(normalizedEmail);
-        }
+      if (!userCreated) {
+        return res.status(409).json({ message: "User already exists" });
+      }
 
-        return res.status(201).json({ user_id: userId, email: normalizedEmail });
-      } catch (error) {
-        if (error.code === 11000) {
-          return res.status(409).json({ message: "User already exists" });
-        }
-        throw error;
+      if (config.registration.verificationRequired) {
+        await repository.deletePotentialUserByEmail(normalizedEmail);
       }
+
+      return res.status(201).json({ user_id: userId, email: normalizedEmail });
     } catch (error) {
       next(error);
     }

package/src/authenticationLogic/createAuthenticationLibrary.js

@@ -1,19 +1,33 @@
 import { createAuthConfig } from "./config/createAuthConfig.js";
 import { createAuthController } from "./controllers/authController.js";
 import { createJwtMiddleware } from "./middleware/jwtMiddleware.js";
-import { createUserRepository } from "./repositories/userRepository.js";
+import { assertAuthStore } from "./adapters/authStore.js";
 import { createAuthRouter } from "./routes/authRoutes.js";
+import { ensureDefaultAdminUser } from "./services/defaultAdminService.js";
 import { createJwtKeyProvider } from "./services/jwtKeyProvider.js";
 import { createTokenService } from "./services/tokenService.js";
 
 export function createAuthenticationLibrary(configOverrides = {}) {
   const config = createAuthConfig(configOverrides);
   const keyProvider = createJwtKeyProvider(config.jwt);
-  const repository = createUserRepository({
-    mongo: config.mongo,
-    defaultAdmin: config.defaultAdmin,
-    passwordHash: config.passwordHash
-  });
+  let repository;
+
+  function getRepository() {
+    if (repository) {
+      return repository;
+    }
+
+    if (typeof config.database.adapter !== "function") {
+      throw new Error(
+        "database.adapter must be configured before connecting to a database or creating an authentication router"
+      );
+    }
+
+    repository = config.database.adapter(config.database.adapterConfig);
+    assertAuthStore(repository);
+    return repository;
+  }
+
   const tokenService = createTokenService({ jwt: config.jwt, keyProvider });
   const middleware = createJwtMiddleware({
     jwt: config.jwt,
@@ -23,15 +37,27 @@ export function createAuthenticationLibrary(configOverrides = {}) {
 
   return {
     config,
-    connectToDatabase: repository.connectToDatabase,
-    closeDatabase: repository.closeDatabase,
+    async connectToDatabase() {
+      const store = getRepository();
+      await store.connect();
+      await ensureDefaultAdminUser({
+        store,
+        defaultAdmin: config.defaultAdmin,
+        passwordHash: config.passwordHash
+      });
+    },
+    async closeDatabase() {
+      if (repository) {
+        await repository.close();
+      }
+    },
     requireJwt: middleware.requireJwt,
     requireNabAdmin: middleware.requireNabAdmin,
     jwtErrorHandler: middleware.jwtErrorHandler,
     createAuthRouter(payloadFactory, options = {}) {
       const controller = createAuthController({
         config,
-        repository,
+        repository: getRepository(),
         tokenService,
         payloadFactory,
         options

package/src/authenticationLogic/index.js

@@ -1,3 +1,5 @@
 export { createAuthenticationLibrary } from "./createAuthenticationLibrary.js";
 export { defaultAuthConfig } from "./config/defaultAuthConfig.js";
 export { createFileJwtKeyProvider } from "./services/jwtKeyProvider.js";
+export { createMongoAuthStore } from "./adapters/mongoAuthStore.js";
+export { authStoreMethods, assertAuthStore } from "./adapters/authStore.js";

package/src/authenticationLogic/services/defaultAdminService.js

@@ -0,0 +1,27 @@
+import { randomUUID } from "node:crypto";
+import argon2 from "argon2";
+import { normalizeEmail } from "../utils/normalizeEmail.js";
+
+export async function ensureDefaultAdminUser({ store, defaultAdmin, passwordHash }) {
+  if (!defaultAdmin.enabled) {
+    return;
+  }
+
+  const email = normalizeEmail(defaultAdmin.email);
+  if (await store.findUserByEmail(email)) {
+    return;
+  }
+
+  const passwordHashValue = await argon2.hash(defaultAdmin.password, {
+    type: argon2.argon2id,
+    ...passwordHash
+  });
+
+  await store.createUser({
+    user_id: randomUUID(),
+    email,
+    passwordHash: passwordHashValue,
+    nab_role: defaultAdmin.roles,
+    createdAt: new Date()
+  });
+}

package/src/authenticationLogic/utils/normalizeEmail.js

@@ -0,0 +1,3 @@
+export function normalizeEmail(email) {
+  return email.trim().toLowerCase();
+}