@restingowlorg/owlauth 1.0.1

package/README.md

@@ -0,0 +1,307 @@
+# owlauth
+
+<p align="center">
+  <img src="https://restingowl.com/owl-logo.png" alt="owlauth logo" width="120" />
+</p>
+
+---
+
+[![npm version](https://img.shields.io/npm/v/%40restingowlorg%2Fowlauth)](https://www.npmjs.com/package/@restingowlorg/owlauth) [![npm downloads](https://img.shields.io/npm/dm/%40restingowlorg%2Fowlauth)](https://www.npmjs.com/package/@restingowlorg/owlauth) [![Node.js](https://img.shields.io/node/v/%40restingowlorg%2Fowlauth)](https://www.npmjs.com/package/@restingowlorg/owlauth) [![License](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](LICENSE)
+
+Open-source OWASP-aligned authentication and account-security library for Node.js.
+
+owlauth, published as `@restingowlorg/owlauth`, gives your Node.js app the core pieces of authentication: credentials login, magic links, password checks, and security-focused audit logging. It works with PostgreSQL and MongoDB and stays out of your framework.
+
+- **Package:** `@restingowlorg/owlauth`
+- **Latest stable tag:** `latest`
+- **Prerelease tag:** `next`
+- **Install:** `npm install @restingowlorg/owlauth`
+- **Developer guide:** [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md)
+
+## What You Get
+
+- **Credentials authentication**: Sign up users, log them in, and rotate passwords through one library surface.
+- **Passwordless magic links**: Request, verify, and consume single-use login tokens.
+- **PostgreSQL and MongoDB adapters**: Use the same auth API across two common persistence stacks.
+- **Password hygiene controls**: Enforce minimum strength with `zxcvbn`, reject context-based weak passwords, and check candidate passwords against Have I Been Pwned using the k-anonymity API.
+- **Security-focused logging**: Audit events are logged with built-in masking for sensitive fields such as passwords, tokens, secrets, cookies, and authorization data.
+- **Request tracing support**: Pass a `correlationId` through auth operations to align library logs with your application logs.
+- **Pluggable cryptography**: Swap the default crypto adapter if your stack requires a different hashing or token strategy.
+- **Typed, predictable results**: Every auth method returns a consistent `AuthResult<T>` shape.
+
+## Support Matrix
+
+| Area          | Current Support         |
+| ------------- | ----------------------- |
+| Runtime       | Node.js 18+             |
+| Language      | TypeScript, JavaScript  |
+| Module output | CommonJS                |
+| Databases     | PostgreSQL, MongoDB     |
+| Auth flows    | Credentials, Magic Link |
+
+## Installation
+
+```bash
+npm install @restingowlorg/owlauth
+```
+
+## Quick Start
+
+```ts
+import { createAuthManager, PostgresAdapter } from "@restingowlorg/owlauth";
+
+const auth = await createAuthManager({
+  adapter: new PostgresAdapter({
+    postgresUrl: process.env.POSTGRES_URL!,
+    userTableName: "users",
+    magicLinkTableName: "magic_links"
+  }),
+  authTypes: ["credentials", "magicLink"],
+  blockedPasswords: ["company-name", "product-name"],
+  pwnedPasswordFailClosed: true,
+  customMaskingKeys: ["apiKey", "accessToken"]
+});
+
+const signup = await auth.credentials.signup(
+  "user@example.com",
+  "engineer01",
+  "CorrectHorseBatteryStaple!2026",
+  { correlationId: "req_123" }
+);
+
+if (signup.success) {
+  console.log(signup.data.user.email);
+}
+
+await auth.disconnectDB();
+```
+
+## Database Adapters
+
+### PostgreSQL
+
+```ts
+import { createAuthManager, PostgresAdapter } from "@restingowlorg/owlauth";
+
+const auth = await createAuthManager({
+  adapter: new PostgresAdapter({
+    postgresUrl: process.env.POSTGRES_URL!,
+    userTableName: "users",
+    userSchema: "public",
+    magicLinkTableName: "magic_links",
+    magicLinkSchema: "public"
+  }),
+  authTypes: ["credentials", "magicLink"]
+});
+```
+
+### MongoDB
+
+```ts
+import { createAuthManager, MongoAdapter } from "@restingowlorg/owlauth";
+
+const auth = await createAuthManager({
+  adapter: new MongoAdapter({
+    mongoUri: process.env.MONGO_URI!,
+    userCollectionName: "users",
+    magicLinkCollectionName: "magic_links"
+  }),
+  authTypes: ["credentials", "magicLink"]
+});
+```
+
+### Subpath Exports
+
+Need just the adapter layer? The package ships database-specific entry points too:
+
+```ts
+import {
+  MongoAdapter,
+  MongoUserRepo,
+  MongoMagicLinkRepo,
+  connectMongo
+} from "@restingowlorg/owlauth/mongo";
+import {
+  PostgresAdapter,
+  PostgresUserRepository,
+  PostgresMagicLinkRepository,
+  initPostgres
+} from "@restingowlorg/owlauth/postgres";
+```
+
+## Core Usage
+
+### Credentials Flow
+
+```ts
+import {
+  AuthResult,
+  SignupResult,
+  LoginResult,
+  ChangePasswordResult
+} from "@restingowlorg/owlauth";
+
+const signup: AuthResult<SignupResult> = await auth.credentials.signup(
+  "user@example.com",
+  "engineer01",
+  "CorrectHorseBatteryStaple!2026"
+);
+
+const login: AuthResult<LoginResult> = await auth.credentials.login(
+  "user@example.com",
+  "CorrectHorseBatteryStaple!2026",
+  {
+    correlationId: "req_login_001"
+  }
+);
+
+const passwordChange: AuthResult<ChangePasswordResult> = await auth.credentials.changePassword(
+  "user_id123456",
+  "current_strong_password",
+  "new_strong_password_example",
+  {
+    correlationId: "req_password_001"
+  }
+);
+```
+
+### Magic Link Flow
+
+```ts
+import {
+  AuthResult,
+  RequestMagicLinkResult,
+  VerifyMagicLinkResult,
+  ConsumeMagicLinkResult
+} from "@restingowlorg/owlauth";
+
+const requested: AuthResult<RequestMagicLinkResult> = await auth.magicLink.request(
+  "user@example.com",
+  { correlationId: "req_magic_001" }
+);
+
+if (requested.success) {
+  const token = requested.data;
+  const verified: AuthResult<VerifyMagicLinkResult> = await auth.magicLink.verify(token);
+  const consumed: AuthResult<ConsumeMagicLinkResult> = await auth.magicLink.consume(token);
+}
+```
+
+`request()` returns the raw token string. Putting it in a URL, sending the email, and handling delivery is your application's job. owlauth does not touch any of that.
+
+## Configuration Options
+
+### Shared Options
+
+| Option                    | Type                               | Purpose                                                                                 |
+| ------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------- |
+| `authTypes`               | `("credentials" \| "magicLink")[]` | Enables one or both supported auth flows. Defaults to credentials only.                 |
+| `blockedPasswords`        | `string[]`                         | Rejects passwords containing the user's email, username, or any supplied blocked terms. |
+| `cryptoAdapter`           | `ICryptoAdapter`                   | Replaces the default bcrypt-based crypto implementation.                                |
+| `customMaskingKeys`       | `string[]`                         | Adds case-insensitive keys to the audit logger masking list.                            |
+| `pwnedPasswordFailClosed` | `boolean`                          | Rejects signups and password changes when the breached-password API cannot be reached.  |
+
+### Method-Level Options
+
+- `signup()`: `blockedPasswords`, `pwnedPasswordFailClosed`, `correlationId`
+- `login()`: `correlationId`
+- `changePassword()`: `blockedPasswords`, `pwnedPasswordFailClosed`, `correlationId`
+- `magicLink.request()`: `correlationId`
+- `magicLink.verify()`: `correlationId`
+- `magicLink.consume()`: `correlationId`
+
+## Response Model
+
+Every public method returns the same envelope:
+
+```ts
+type AuthResult<T = unknown> =
+  | { success: true; data: T; httpCode: number; message: string }
+  | { success: false; data?: undefined; httpCode: number; message: string };
+```
+
+Result payloads are:
+
+- `SignupResult`: `{ user: { id, email, username } }`
+- `LoginResult`: `{ user: { id, email, username } }`
+- `ChangePasswordResult`: `{ user: { id, email, username } }`
+- `RequestMagicLinkResult`: `string`
+- `VerifyMagicLinkResult`: `{ isValid: true, userId: string, tokenId: string }`
+- `ConsumeMagicLinkResult`: `{ userId: string }`
+
+## OWASP Alignment
+
+Here's exactly what owlauth does, and where each decision comes from. Every control is traced back to the [OWASP Authentication Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html), [ASVS 5.0.0](https://owasp.org/www-project-application-security-verification-standard/), or [OWASP Top 10:2025](https://owasp.org/www-project-top-ten/).
+
+### Password Security
+
+| Control                   | What the library does                                                                                                                                                                                                                                  | OWASP reference                                                                                                                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Password strength scoring | Candidate passwords are scored with `@zxcvbn-ts/core` at signup and on every password change. Scores below 3 of 4 are rejected.                                                                                                                        | [Auth Cheat Sheet — Implement Proper Password Strength Controls](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#implement-proper-password-strength-controls) |
+| Breached password check   | The [Have I Been Pwned Pwned Passwords API](https://haveibeenpwned.com/API/v3#PwnedPasswords) is queried using the k-anonymity range method. Only the first 5 characters of the SHA-1 hash are transmitted; the raw password never leaves the process. | [Auth Cheat Sheet — Block previously breached passwords](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#implement-proper-password-strength-controls)         |
+| Context-aware blocking    | Passwords are rejected if they contain the user's email local part, username, or any caller-supplied blocked terms, preventing context-guessable passwords.                                                                                            | [NIST SP 800-63B § 5.1.1.2](https://pages.nist.gov/800-63-4/sp800-63b.html), context-specific word verification                                                                              |
+| Fail-closed breach check  | When `pwnedPasswordFailClosed: true`, a network error on the breach API causes the request to fail rather than silently pass.                                                                                                                          | Defense-in-depth, fail-safe defaults                                                                                                                                                         |
+
+### Credential Storage
+
+| Control                   | What the library does                                                                                                                                                 | OWASP reference                                                                                                                    |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Adaptive password hashing | Passwords are hashed with bcrypt at 10 salt rounds via the built-in `BcryptAdapter`.                                                                                  | [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html), use bcrypt |
+| Pluggable crypto adapter  | The `ICryptoAdapter` interface allows swapping the default bcrypt implementation for any alternative hashing or token strategy without changing the auth API surface. | ASVS 5.0, algorithm agility                                                                                                        |
+
+### Authentication Logic
+
+| Control                          | What the library does                                                                                                                                                 | OWASP reference                                                                                                                                                         |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Generic login error messages     | Login failure returns `"Invalid credentials."` regardless of whether the email is unknown or the password is wrong, preventing user enumeration.                      | [Auth Cheat Sheet, Authentication and Error Messages](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#authentication-and-error-messages) |
+| Current password re-verification | `changePassword()` requires the caller to supply and verify the current password before a new one is accepted, preventing silent takeover through a hijacked session. | [Auth Cheat Sheet, Change Password Feature](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#change-password-feature)                     |
+
+### Passwordless Authentication
+
+| Control                                   | What the library does                                                                                                           | OWASP reference                                                                                                                                            |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Cryptographically secure token generation | Magic link tokens are produced with `crypto.randomBytes(32)` from Node.js's built-in CSPRNG.                                    | [OWASP Forgot Password Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html), use a cryptographically random value |
+| Token hashing at rest                     | The raw token is never stored. Only the bcrypt hash of the token is persisted; the database contains no recoverable plaintext.  | [OWASP Forgot Password Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html), hash tokens before storage           |
+| Short expiry window                       | Tokens expire 15 minutes after issuance.                                                                                        | [OWASP Forgot Password Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html), use a short token lifetime           |
+| Single-use with prior invalidation        | Requesting a new magic link immediately invalidates all previous active tokens for that user. Consumed tokens cannot be reused. | [OWASP Forgot Password Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Forgot_Password_Cheat_Sheet.html), single-use tokens                    |
+
+### Security Logging and Audit Trail
+
+| Control                    | What the library does                                                                                                                                                                    | OWASP reference                                                                                                                                                                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Security event logging     | Every auth operation, signup, login, password change, and all magic link steps, emits a structured audit event with event type, email, outcome, and reason.                              | [Auth Cheat Sheet, Logging and Monitoring](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html#logging-and-monitoring); [A09:2025 Security Logging and Alerting Failures](https://owasp.org/www-project-top-ten/) |
+| Sensitive field masking    | The audit logger automatically redacts values at keys matching `password`, `token`, `secret`, `authorization`, `cookie`, and `apikey`. Callers can extend this with `customMaskingKeys`. | ASVS 5.0, do not log sensitive data; [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html)                                                                                                    |
+| Correlation ID propagation | Every auth method accepts an optional `correlationId`. When supplied, it is included in all log output for that operation, enabling trace correlation with application-level logs.       | [OWASP Logging Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html), include trace identifiers                                                                                                              |
+
+## Security Notes
+
+The table above covers what this library actually does. It's **not** an OWASP certification, and it won't make your app ASVS-compliant on its own. You still need to handle:
+
+- TLS and secure transport
+- secure email delivery for magic links
+- rate limiting, brute-force protection, and account lockout
+- session management
+- CSRF defenses where relevant
+- account verification and recovery workflows
+- MFA or passkeys if the risk model requires them
+- authorization and role enforcement
+
+## Roadmap
+
+owlauth is part of a wider RestingOwl effort focused on building secure-by-default tooling for various technology stacks, not limited to Node.js.
+
+Here's what's coming next:
+
+- **More application stacks**: First-party integrations for Express, Fastify, NestJS, Next.js, and serverless Node runtimes
+- **More data stores**: Additional adapters for MySQL, SQLite, DynamoDB, and other operationally common backends
+- **Stronger auth options**: WebAuthn, passkeys, TOTP-based MFA, and recovery-oriented flows
+- **Operational hardening**: Built-in rate limiting hooks, lockout strategies, and safer recovery patterns
+- **Broader RestingOwl package family**: Adjacent packages for rate limiting, input sanitization, audit logging, secrets management, and CSRF protection
+
+## Community
+
+[![Website](https://img.shields.io/badge/restingowl.com-111827?style=flat-square&logo=googlechrome&logoColor=white)](https://restingowl.com/) [![LinkedIn](https://img.shields.io/badge/LinkedIn-0A66C2?style=flat-square&logo=linkedin&logoColor=white)](https://www.linkedin.com/showcase/restingowl/) [![GitHub](https://img.shields.io/badge/Source-181717?style=flat-square&logo=github&logoColor=white)](https://github.com/restingowlorg/OwlAuth) [![Issues](https://img.shields.io/github/issues/restingowlorg/OwlAuth?style=flat-square&logo=github&logoColor=white&label=Issues&color=181717)](https://github.com/restingowlorg/OwlAuth/issues) [![Security Policy](https://img.shields.io/badge/Security_Policy-B91C1C?style=flat-square&logo=owasp&logoColor=white)](SECURITY.md) [![Contributing](https://img.shields.io/badge/Contributing-15803D?style=flat-square&logo=git&logoColor=white)](CONTRIBUTING.md)
+
+## License
+
+[Mozilla Public License 2.0](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export declare const SECURITY_CONFIG: {
+    readonly LOGGER_PREFIX: "OWL-AUTH";
+    readonly SENSITIVE_KEYS: readonly ["password", "token", "secret", "authorization", "cookie", "apikey"];
+    /**
+     * Have I Been Pwned API URL for range-based hash checking
+     * @see https://haveibeenpwned.com/API/v3#PwnedPasswords
+     */
+    readonly PWNED_API_URL: "https://api.pwnedpasswords.com/range";
+    /**
+     * Bcrypt salt rounds
+     */
+    readonly SALT_ROUNDS: 10;
+};

package/dist/config.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_CONFIG = void 0;
+exports.SECURITY_CONFIG = {
+    LOGGER_PREFIX: "OWL-AUTH",
+    SENSITIVE_KEYS: ["password", "token", "secret", "authorization", "cookie", "apikey"],
+    /**
+     * Have I Been Pwned API URL for range-based hash checking
+     * @see https://haveibeenpwned.com/API/v3#PwnedPasswords
+     */
+    PWNED_API_URL: "https://api.pwnedpasswords.com/range",
+    /**
+     * Bcrypt salt rounds
+     */
+    SALT_ROUNDS: 10
+};

package/dist/core/auth.manager.d.ts

@@ -0,0 +1,6 @@
+import { AuthOptions, IAuthManager, AuthType } from "../types/index";
+/**
+ * Creates and initializes an instance of the AuthManager.
+ * Returns the IAuthManager interface to consumers.
+ */
+export declare function createAuthManager<T extends AuthType = "credentials">(options: AuthOptions<T>): Promise<IAuthManager<T>>;

package/dist/core/auth.manager.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAuthManager = createAuthManager;
+const auth_service_init_1 = require("./auth.service.init");
+/**
+ * Creates and initializes an instance of the AuthManager.
+ * Returns the IAuthManager interface to consumers.
+ */
+async function createAuthManager(options) {
+    // Database
+    if (!options.adapter) {
+        throw new Error("[Auth:createAuthManager] Database adapter is required in AuthOptions");
+    }
+    const db = await options.adapter.connect(options);
+    // Auth Services
+    const services = (0, auth_service_init_1.initAuthServices)(db, options);
+    return Object.freeze({
+        ...services,
+        disconnectDB: db.close
+    });
+}

package/dist/core/auth.service.init.d.ts

@@ -0,0 +1,2 @@
+import { AuthDB, AuthOptions, AuthType, IAuthMethods } from "../types/index";
+export declare function initAuthServices(db: AuthDB, options: AuthOptions<AuthType>): Partial<IAuthMethods>;

package/dist/core/auth.service.init.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initAuthServices = initAuthServices;
+const security_audit_logger_1 = require("../infra/security/security-audit-logger");
+const CredentialsStrategy_1 = require("../strategies/CredentialsStrategy");
+const MagicLinkStrategy_1 = require("../strategies/MagicLinkStrategy");
+const authStrategies = {
+    credentials: new CredentialsStrategy_1.CredentialsAuthStrategy(),
+    magicLink: new MagicLinkStrategy_1.MagicLinkAuthStrategy()
+};
+function initAuthServices(db, options) {
+    var _a;
+    const result = {};
+    const authTypes = (_a = options.authTypes) !== null && _a !== void 0 ? _a : ["credentials"];
+    if (options.customMaskingKeys) {
+        security_audit_logger_1.auditLogger.setCustomMaskingKeys(options.customMaskingKeys);
+    }
+    security_audit_logger_1.auditLogger.info(`Initializing auth services for types: ${authTypes.join(", ")}`);
+    for (const type of authTypes) {
+        const strategy = authStrategies[type];
+        if (strategy) {
+            strategy.register(result, db, options);
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createAuthManager } from "./core/auth.manager";
+export { AuthType, AuthLogLevel, UserId, IAuthManager, IDatabaseAdapter, ICryptoAdapter, AuthDB, AuthOptions, BaseAuthOptions, InitPostgresOptions, InitMongoOptions, SignupInput, LoginInput, CreateMagicLinkInput, CreateUserInput, AuthResult, LoginResult, SignupResult, ChangePasswordResult, RequestMagicLinkResult, VerifyMagicLinkResult, ConsumeMagicLinkResult } from "./types/index";
+export { BcryptAdapter } from "./infra/security/bcrypt.adapter";
+export { MongoAdapter } from "./infra/databases/mongo/adapter";
+export { PostgresAdapter } from "./infra/databases/postgresql/adapter";

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = exports.MongoAdapter = exports.BcryptAdapter = exports.createAuthManager = void 0;
+var auth_manager_1 = require("./core/auth.manager");
+Object.defineProperty(exports, "createAuthManager", { enumerable: true, get: function () { return auth_manager_1.createAuthManager; } });
+var bcrypt_adapter_1 = require("./infra/security/bcrypt.adapter");
+Object.defineProperty(exports, "BcryptAdapter", { enumerable: true, get: function () { return bcrypt_adapter_1.BcryptAdapter; } });
+var adapter_1 = require("./infra/databases/mongo/adapter");
+Object.defineProperty(exports, "MongoAdapter", { enumerable: true, get: function () { return adapter_1.MongoAdapter; } });
+var adapter_2 = require("./infra/databases/postgresql/adapter");
+Object.defineProperty(exports, "PostgresAdapter", { enumerable: true, get: function () { return adapter_2.PostgresAdapter; } });

package/dist/infra/databases/mongo/adapter.d.ts

@@ -0,0 +1,6 @@
+import { AuthDB, BaseAuthOptions, IDatabaseAdapter, InitMongoOptions } from "../../../types/index";
+export declare class MongoAdapter implements IDatabaseAdapter {
+    private readonly config;
+    constructor(config: InitMongoOptions);
+    connect(options: BaseAuthOptions): Promise<AuthDB>;
+}

package/dist/infra/databases/mongo/adapter.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoAdapter = void 0;
+const db_1 = require("./db");
+class MongoAdapter {
+    constructor(config) {
+        this.config = config;
+    }
+    async connect(options) {
+        const { mongoUri, userCollectionName, magicLinkCollectionName } = this.config;
+        const { authTypes } = options;
+        if (!mongoUri)
+            throw new Error("[Auth:MongoAdapter] mongoUri is required for MongoAdapter");
+        if (!userCollectionName)
+            throw new Error("[Auth:MongoAdapter] userCollectionName is required for MongoAdapter");
+        return await (0, db_1.connectMongo)({
+            mongoUri,
+            userCollectionName,
+            magicLinkCollectionName,
+            authTypes
+        });
+    }
+}
+exports.MongoAdapter = MongoAdapter;

package/dist/infra/databases/mongo/db.d.ts

@@ -0,0 +1,5 @@
+import { InitMongoOptions, BaseAuthOptions, AuthDB } from "../../../types/index";
+/**
+ * Connect to MongoDB and initialize repositories
+ */
+export declare function connectMongo(options: InitMongoOptions & BaseAuthOptions): Promise<AuthDB>;

package/dist/infra/databases/mongo/db.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connectMongo = connectMongo;
+const mongodb_1 = require("mongodb");
+const magicLink_repo_1 = require("../../../repositories/mongo/magicLink.repo");
+const user_repo_1 = require("../../../repositories/mongo/user.repo");
+const security_audit_logger_1 = require("../../security/security-audit-logger");
+/**
+ * Connect to MongoDB and initialize repositories
+ */
+async function connectMongo(options) {
+    const { mongoUri, userCollectionName, magicLinkCollectionName, authTypes } = options;
+    if (!mongoUri)
+        throw new Error("[Auth:connectMongo] mongoUri is required");
+    if (!userCollectionName)
+        throw new Error("[Auth:connectMongo] userCollectionName is required");
+    // Connect to MongoDB
+    const client = new mongodb_1.MongoClient(mongoUri);
+    await client.connect();
+    const db = client.db();
+    if (!db) {
+        security_audit_logger_1.auditLogger.error("Failed to connect to MongoDB - no database instance found", new Error("No DB instance"));
+        throw new Error("[Auth:connectMongo] Failed to connect to MongoDB");
+    }
+    // Use generic to type collection correctly
+    const userColl = db.collection(userCollectionName);
+    // Magic link collection
+    let magicColl;
+    if (authTypes === null || authTypes === void 0 ? void 0 : authTypes.includes("magicLink")) {
+        if (!magicLinkCollectionName) {
+            throw new Error(`[Auth:connectMongo] Magic link auth requested but 'magicLinkCollectionName' is not provided`);
+        }
+        magicColl = db.collection(magicLinkCollectionName);
+    }
+    // Initialize repositories
+    return {
+        userRepo: new user_repo_1.MongoUserRepo(userColl),
+        magicLinkRepo: magicColl ? new magicLink_repo_1.MongoMagicLinkRepo(magicColl) : undefined,
+        close: async () => {
+            await client.close();
+        }
+    };
+}

package/dist/infra/databases/mongo/mongo.d.ts

@@ -0,0 +1,5 @@
+export { MongoAdapter } from "./adapter";
+export { connectMongo } from "./db";
+export { MongoUserRepo } from "../../../repositories/mongo/user.repo";
+export { MongoMagicLinkRepo } from "../../../repositories/mongo/magicLink.repo";
+export { IMongoUserDoc, IMongoMagicLinkDoc } from "../../../types/index";

package/dist/infra/databases/mongo/mongo.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MongoMagicLinkRepo = exports.MongoUserRepo = exports.connectMongo = exports.MongoAdapter = void 0;
+var adapter_1 = require("./adapter");
+Object.defineProperty(exports, "MongoAdapter", { enumerable: true, get: function () { return adapter_1.MongoAdapter; } });
+var db_1 = require("./db");
+Object.defineProperty(exports, "connectMongo", { enumerable: true, get: function () { return db_1.connectMongo; } });
+var user_repo_1 = require("../../../repositories/mongo/user.repo");
+Object.defineProperty(exports, "MongoUserRepo", { enumerable: true, get: function () { return user_repo_1.MongoUserRepo; } });
+var magicLink_repo_1 = require("../../../repositories/mongo/magicLink.repo");
+Object.defineProperty(exports, "MongoMagicLinkRepo", { enumerable: true, get: function () { return magicLink_repo_1.MongoMagicLinkRepo; } });

package/dist/infra/databases/postgresql/adapter.d.ts

@@ -0,0 +1,6 @@
+import { AuthDB, BaseAuthOptions, IDatabaseAdapter, InitPostgresOptions } from "../../../types/index";
+export declare class PostgresAdapter implements IDatabaseAdapter {
+    private readonly config;
+    constructor(config: InitPostgresOptions);
+    connect(options: BaseAuthOptions): Promise<AuthDB>;
+}

package/dist/infra/databases/postgresql/adapter.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostgresAdapter = void 0;
+const db_1 = require("./db");
+class PostgresAdapter {
+    constructor(config) {
+        this.config = config;
+    }
+    async connect(options) {
+        const { postgresUrl, userTableName, userSchema, magicLinkTableName, magicLinkSchema } = this.config;
+        const { authTypes } = options;
+        if (!postgresUrl)
+            throw new Error("[Auth:PostgresAdapter] postgresUrl is required for PostgresAdapter");
+        if (!userTableName)
+            throw new Error("[Auth:PostgresAdapter] userTableName is required for PostgresAdapter");
+        return await (0, db_1.initPostgres)({
+            postgresUrl,
+            userTableName,
+            userSchema,
+            magicLinkTableName,
+            magicLinkSchema,
+            authTypes
+        });
+    }
+}
+exports.PostgresAdapter = PostgresAdapter;

package/dist/infra/databases/postgresql/db.d.ts

@@ -0,0 +1,5 @@
+import { InitPostgresOptions, BaseAuthOptions, AuthDB } from "../../../types/index";
+/**
+ * Initialize PostgreSQL connection and repositories
+ */
+export declare function initPostgres(options: InitPostgresOptions & BaseAuthOptions): Promise<AuthDB>;

package/dist/infra/databases/postgresql/db.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initPostgres = initPostgres;
+const pg_1 = require("pg");
+const user_repo_1 = require("../../../repositories/postgresql/user.repo");
+const magic_link_repo_1 = require("../../../repositories/postgresql/magic.link.repo");
+const schema_1 = require("./schema");
+const helpers_1 = require("./helpers");
+/**
+ * Initialize PostgreSQL connection and repositories
+ */
+async function initPostgres(options) {
+    const { postgresUrl, userTableName, userSchema = "public", magicLinkTableName, magicLinkSchema = "public", authTypes } = options;
+    if (!postgresUrl)
+        throw new Error("[Auth:initPostgres] postgresUrl is required");
+    if (!userTableName)
+        throw new Error("[Auth:initPostgres] userTableName is required");
+    const pool = new pg_1.Pool({ connectionString: postgresUrl });
+    const isConnected = await pool.query("SELECT 1"); // Test connection
+    if (!isConnected)
+        throw new Error("[Auth:initPostgres] Failed to connect to PostgreSQL");
+    const qualifiedUserTable = `${userSchema}.${userTableName}`;
+    // Core User table validations
+    await Promise.all([
+        (0, helpers_1.validateSchema)(pool, userSchema),
+        (0, helpers_1.validateTable)(pool, qualifiedUserTable),
+        (0, helpers_1.validateColumns)(pool, userSchema, userTableName, schema_1.PostgresUserSchema.requiredColumns)
+    ]);
+    // Magic link table validations (if enabled)
+    let magicRepo;
+    if (authTypes === null || authTypes === void 0 ? void 0 : authTypes.includes("magicLink")) {
+        const magicTable = magicLinkTableName !== null && magicLinkTableName !== void 0 ? magicLinkTableName : "magic_links";
+        const qualifiedMagicTable = `${magicLinkSchema}.${magicTable}`;
+        await Promise.all([
+            (0, helpers_1.validateSchema)(pool, magicLinkSchema),
+            (0, helpers_1.validateTable)(pool, qualifiedMagicTable),
+            (0, helpers_1.validateColumns)(pool, magicLinkSchema, magicTable, schema_1.PostgresMagicLinkSchema.requiredColumns),
+            (0, helpers_1.validateForeignKey)(pool, magicLinkSchema, magicTable, userSchema, userTableName, "user_id", "id")
+        ]);
+        magicRepo = new magic_link_repo_1.PostgresMagicLinkRepository(qualifiedMagicTable, pool);
+    }
+    // Return repositories
+    return {
+        userRepo: new user_repo_1.PostgresUserRepository(qualifiedUserTable, pool),
+        magicLinkRepo: magicRepo,
+        close: async () => {
+            await pool.end();
+        }
+    };
+}

package/dist/infra/databases/postgresql/helpers.d.ts

@@ -0,0 +1,8 @@
+import { Pool } from "pg";
+/**
+ * Validation Helpers for PostgreSQL
+ */
+export declare function validateSchema(pool: Pool, schema: string): Promise<void>;
+export declare function validateTable(pool: Pool, qualifiedTable: string): Promise<void>;
+export declare function validateColumns(pool: Pool, schema: string, table: string, requiredColumns: readonly string[]): Promise<void>;
+export declare function validateForeignKey(pool: Pool, schema: string, table: string, refSchema: string, refTable: string, col: string, refCol: string): Promise<void>;