@azlib/identity 0.2.0

package/dist/node.mjs

@@ -0,0 +1,890 @@
+import { a as IdentityError, c as UnauthenticatedError, i as IdentityConfigError, n as EmailAlreadyRegisteredError, o as InvalidCredentialsError, r as ForbiddenError, s as InvalidTokenError, t as AccountUnavailableError } from "./errors-CEmnZxIn.mjs";
+import { n as noopLogger, r as resolveLogger, t as consoleLogger } from "./logger-CcCHJVVe.mjs";
+import { a as hydratePrincipal, c as isAuthorized, i as createOAuthService, l as resolveIdentityConfig, n as OAuthProviderNotFoundError, o as issueSession, r as OAuthStateMismatchError, s as evaluateAuthorization, t as identitySchemaModel } from "./identity-Bz9RDOvT.mjs";
+import { createHash, createHmac, randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+import { SignJWT, jwtVerify } from "jose";
+//#region core/password-hasher.ts
+/**
+* Password hashing using Node's scrypt. Hashes are self-describing:
+* `scrypt$<N>$<saltHex>$<derivedKeyHex>` so parameters can evolve without breaking
+* existing records.
+*/
+const KEY_LENGTH = 64;
+const scryptAsync = (password, salt, cost) => new Promise((resolve, reject) => {
+	scrypt(password, salt, KEY_LENGTH, {
+		N: cost,
+		maxmem: 256 * cost * 8
+	}, (err, derived) => {
+		if (err) reject(err);
+		else resolve(derived);
+	});
+});
+/** Creates a scrypt-based {@link PasswordHasher}. */
+function createPasswordHasher(cost) {
+	return {
+		async hash(password) {
+			const salt = randomBytes(16);
+			const derived = await scryptAsync(password, salt, cost);
+			return `scrypt$${cost}$${salt.toString("hex")}$${derived.toString("hex")}`;
+		},
+		async verify(password, storedHash) {
+			const parts = storedHash.split("$");
+			if (parts.length !== 4 || parts[0] !== "scrypt") return false;
+			const cost = Number.parseInt(parts[1], 10);
+			const salt = Buffer.from(parts[2], "hex");
+			const expected = Buffer.from(parts[3], "hex");
+			if (!Number.isInteger(cost) || salt.length === 0 || expected.length === 0) return false;
+			const actual = await scryptAsync(password, salt, cost);
+			if (actual.length !== expected.length) return false;
+			return timingSafeEqual(actual, expected);
+		}
+	};
+}
+//#endregion
+//#region core/token-service.ts
+const hashToken = (token) => createHash("sha256").update(token).digest("hex");
+function createTokenService(config) {
+	const secret = new TextEncoder().encode(config.accessTokenSecret);
+	return {
+		async issueAccessToken(userId, authVersion) {
+			const issuedAt = Math.floor(config.now().getTime() / 1e3);
+			const expiresAtSeconds = issuedAt + config.accessTokenTtlSeconds;
+			const builder = new SignJWT({ authVersion }).setProtectedHeader({ alg: "HS256" }).setSubject(userId).setIssuedAt(issuedAt).setIssuer(config.issuer).setExpirationTime(expiresAtSeconds);
+			if (config.audience) builder.setAudience(config.audience);
+			return {
+				token: await builder.sign(secret),
+				expiresAt: /* @__PURE__ */ new Date(expiresAtSeconds * 1e3)
+			};
+		},
+		async verifyAccessToken(token) {
+			try {
+				const { payload } = await jwtVerify(token, secret, {
+					issuer: config.issuer,
+					audience: config.audience
+				});
+				if (typeof payload.sub !== "string" || typeof payload.authVersion !== "number") throw new InvalidTokenError();
+				return {
+					sub: payload.sub,
+					authVersion: payload.authVersion,
+					iat: payload.iat ?? 0,
+					exp: payload.exp ?? 0
+				};
+			} catch (error) {
+				if (error instanceof InvalidTokenError) throw error;
+				throw new InvalidTokenError();
+			}
+		},
+		createRefreshToken(sessionId) {
+			const token = `${sessionId}.${randomBytes(32).toString("base64url")}`;
+			return {
+				token,
+				hash: hashToken(token)
+			};
+		},
+		parseSessionId(token) {
+			const separator = token.indexOf(".");
+			if (separator <= 0) return null;
+			return token.slice(0, separator);
+		},
+		hashRefreshToken(token) {
+			return hashToken(token);
+		}
+	};
+}
+//#endregion
+//#region core/audit.ts
+function createAuditLogger(store, now, onEvent) {
+	return { async record(type, userId, metadata = {}) {
+		const event = {
+			type,
+			userId,
+			metadata,
+			occurredAt: now()
+		};
+		try {
+			await store.recordEvent?.(event);
+		} catch {}
+		try {
+			await onEvent?.(event);
+		} catch {}
+	} };
+}
+//#endregion
+//#region core/register.ts
+/** Raised when registration input fails validation. */
+var RegistrationValidationError = class extends IdentityError {
+	constructor(message) {
+		super("identity/registration-invalid", message, 400);
+	}
+};
+const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const MIN_PASSWORD_LENGTH$1 = 8;
+/** Normalizes an email for storage and lookup (trim + lowercase). */
+function normalizeEmail(email) {
+	return email.trim().toLowerCase();
+}
+/**
+* Registers a new user: validates input, enforces unique email, hashes the password,
+* persists the user and credential, and returns an authenticated session.
+*/
+async function registerUser(deps, input) {
+	const { config, store, hasher, audit } = deps;
+	const email = normalizeEmail(input.email);
+	if (!EMAIL_PATTERN.test(email)) throw new RegistrationValidationError("A valid email address is required.");
+	if (input.password.length < MIN_PASSWORD_LENGTH$1) throw new RegistrationValidationError(`Password must be at least ${MIN_PASSWORD_LENGTH$1} characters.`);
+	if (await store.findUserByEmail(email)) throw new EmailAlreadyRegisteredError();
+	const now = config.now();
+	const user = await store.createUser({
+		userId: config.generateId(),
+		email,
+		displayName: input.displayName ?? null,
+		status: "active",
+		authVersion: 0,
+		createdAt: now,
+		updatedAt: now
+	});
+	const passwordHash = await hasher.hash(input.password);
+	await store.upsertCredential({
+		userId: user.userId,
+		passwordHash,
+		updatedAt: now
+	});
+	await audit.record("user.registered", user.userId, { email });
+	return issueSession(deps, user);
+}
+//#endregion
+//#region core/lockout.ts
+/**
+* Checks whether the user account is currently locked. Throws {@link AccountUnavailableError}
+* when the lockout is active (i.e. `lockedUntil` is in the future).
+*
+* Note: if `lockedUntil` is in the past the lock has expired — the user may proceed and
+* the stale lock will be cleared on successful login.
+*/
+function checkLockout(user, config, now) {
+	if (config.maxFailedAttempts === 0) return;
+	if (user.lockedUntil !== null && user.lockedUntil > now()) throw new AccountUnavailableError();
+}
+/**
+* Records a failed login attempt. When the threshold is reached the account is locked
+* for `config.durationSeconds` seconds (or permanently when `durationSeconds` is 0).
+*/
+async function recordFailedAttempt(store, user, config, now) {
+	if (config.maxFailedAttempts === 0) return;
+	const attempts = user.failedLoginAttempts + 1;
+	const exceeded = attempts >= config.maxFailedAttempts;
+	const lockedUntil = exceeded ? config.durationSeconds > 0 ? new Date(now().getTime() + config.durationSeconds * 1e3) : /* @__PURE__ */ new Date(864e13) : null;
+	const patch = {
+		failedLoginAttempts: attempts,
+		...exceeded ? {
+			status: "locked",
+			lockedUntil
+		} : {}
+	};
+	await store.updateUser(user.userId, patch);
+}
+/**
+* Clears lockout state after a successful login. Resets the failure counter and any
+* active lockout so the account returns to `active` status.
+*/
+async function clearLockout(store, user) {
+	if (user.failedLoginAttempts === 0 && user.lockedUntil === null) return;
+	await store.updateUser(user.userId, {
+		failedLoginAttempts: 0,
+		lockedUntil: null,
+		...user.status === "locked" ? { status: "active" } : {}
+	});
+}
+//#endregion
+//#region core/totp.ts
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+/** Encodes a Buffer to a base32 string (no padding). */
+function base32Encode(buffer) {
+	let result = "";
+	let bits = 0;
+	let accumulator = 0;
+	for (const byte of buffer) {
+		accumulator = accumulator << 8 | byte;
+		bits += 8;
+		while (bits >= 5) {
+			bits -= 5;
+			result += BASE32_ALPHABET[accumulator >> bits & 31] ?? "";
+		}
+	}
+	if (bits > 0) result += BASE32_ALPHABET[accumulator << 5 - bits & 31] ?? "";
+	return result;
+}
+/** Decodes a base32 string (case-insensitive, padding stripped) to a Buffer. */
+function base32Decode(encoded) {
+	const str = encoded.toUpperCase().replace(/=+$/, "");
+	const bytes = [];
+	let bits = 0;
+	let accumulator = 0;
+	for (const char of str) {
+		const value = BASE32_ALPHABET.indexOf(char);
+		if (value === -1) continue;
+		accumulator = accumulator << 5 | value;
+		bits += 5;
+		if (bits >= 8) {
+			bits -= 8;
+			bytes.push(accumulator >> bits & 255);
+		}
+	}
+	return Buffer.from(bytes);
+}
+const TOTP_STEP_SECONDS = 30;
+const TOTP_DIGITS = 6;
+/**
+* Computes an HOTP value for the given base32 key and integer counter (RFC 4226).
+* Returns a zero-padded 6-digit string.
+*/
+function hotp(secretBase32, counter) {
+	const key = base32Decode(secretBase32);
+	const counterBuf = Buffer.alloc(8);
+	counterBuf.writeBigUInt64BE(counter);
+	const hmac = createHmac("sha1", key).update(counterBuf).digest();
+	const offset = hmac[19] & 15;
+	return (((hmac[offset] & 127) << 24 | (hmac[offset + 1] & 255) << 16 | (hmac[offset + 2] & 255) << 8 | hmac[offset + 3] & 255) % Math.pow(10, TOTP_DIGITS)).toString().padStart(TOTP_DIGITS, "0");
+}
+/**
+* Generates a 160-bit random TOTP secret and returns it base32-encoded.
+* 160 bits (20 bytes) aligns with the SHA-1 block size and is standard for TOTP.
+*/
+function generateTotpSecret() {
+	return base32Encode(randomBytes(20));
+}
+/**
+* Generates the current TOTP code for the given base32 secret (RFC 6238).
+*/
+function generateTotp(secretBase32, now = /* @__PURE__ */ new Date()) {
+	return hotp(secretBase32, BigInt(Math.floor(now.getTime() / 1e3 / TOTP_STEP_SECONDS)));
+}
+/**
+* Verifies a 6-digit TOTP code.
+* Accepts codes from the previous, current, or next time step (±1 window) to
+* tolerate clock skew between server and authenticator app.
+*/
+function verifyTotp(code, secretBase32, now = /* @__PURE__ */ new Date()) {
+	if (code.length !== TOTP_DIGITS) return false;
+	const counter = BigInt(Math.floor(now.getTime() / 1e3 / TOTP_STEP_SECONDS));
+	return [
+		-1n,
+		0n,
+		1n
+	].some((delta) => hotp(secretBase32, counter + delta) === code);
+}
+/**
+* Builds an `otpauth://totp/` URI suitable for QR code scanning in authenticator apps
+* (Google Authenticator, Authy, 1Password, etc.).
+*/
+function buildOtpAuthUri(params) {
+	const enc = encodeURIComponent;
+	return `otpauth://totp/${enc(params.issuer)}:${enc(params.accountName)}?secret=${params.secret}&issuer=${enc(params.issuer)}&algorithm=SHA1&digits=${TOTP_DIGITS}&period=${TOTP_STEP_SECONDS}`;
+}
+//#endregion
+//#region core/two-factor.ts
+/** Raised when a TOTP code is absent or incorrect. */
+var TwoFactorError = class extends IdentityError {
+	constructor(message = "Invalid two-factor authentication code.") {
+		super("identity/2fa-invalid", message, 401);
+	}
+};
+/**
+* Raised during login when the user has 2FA enabled and the TOTP challenge has not yet
+* been completed. HTTP 403 signals "authenticated but additional factor required".
+*/
+var TwoFactorRequiredError = class extends IdentityError {
+	constructor() {
+		super("identity/2fa-required", "Two-factor authentication is required to complete sign-in.", 403);
+	}
+};
+/**
+* Begins the 2FA setup flow. Generates a new TOTP secret (stored as pending, not yet
+* active) and returns the secret + QR URI for display in an authenticator app.
+*
+* The caller must then call {@link enable2FA} with a valid TOTP code to activate 2FA.
+*/
+async function setup2FA(deps, userId) {
+	const { config, store, audit } = deps;
+	const user = await store.findUserById(userId);
+	if (!user) throw new TwoFactorError("User not found.");
+	const secretBase32 = generateTotpSecret();
+	const now = config.now();
+	await store.upsertTotpSecret?.({
+		userId,
+		secretBase32,
+		enabledAt: null,
+		createdAt: now
+	});
+	await audit.record("user.2fa.setup.started", userId, {});
+	return {
+		secret: secretBase32,
+		otpAuthUri: buildOtpAuthUri({
+			secret: secretBase32,
+			accountName: user.email,
+			issuer: config.issuer
+		})
+	};
+}
+/**
+* Confirms and enables 2FA. A valid TOTP code from the authenticator app is required.
+* Idempotent when 2FA is already enabled for the user.
+*/
+async function enable2FA(deps, userId, totpCode) {
+	const { config, store, audit } = deps;
+	const record = await store.findTotpSecret?.(userId);
+	if (!record) throw new TwoFactorError("2FA setup has not been started. Call setup2FA first.");
+	if (record.enabledAt) return;
+	if (!verifyTotp(totpCode, record.secretBase32, config.now())) throw new TwoFactorError();
+	await store.upsertTotpSecret?.({
+		...record,
+		enabledAt: config.now()
+	});
+	await store.updateUser(userId, { twoFactorEnabled: true });
+	await audit.record("user.2fa.enabled", userId, {});
+}
+/**
+* Disables 2FA for the user. Requires a valid TOTP code as confirmation.
+* After disabling, login flows no longer issue MFA challenges for the account.
+*/
+async function disable2FA(deps, userId, totpCode) {
+	const { config, store, audit } = deps;
+	const record = await store.findTotpSecret?.(userId);
+	if (!record || !record.enabledAt) throw new TwoFactorError("2FA is not enabled for this account.");
+	if (!verifyTotp(totpCode, record.secretBase32, config.now())) throw new TwoFactorError();
+	await store.deleteTotpSecret?.(userId);
+	await store.updateUser(userId, { twoFactorEnabled: false });
+	await audit.record("user.2fa.disabled", userId, {});
+}
+const MFA_CHALLENGE_TTL_SECONDS = 300;
+const MFA_CHALLENGE_TYPE = "mfa_challenge";
+/**
+* Issues a short-lived signed JWT that encodes a pending MFA session.
+* The client must present this token together with a TOTP code to complete login.
+*/
+async function issueMfaChallengeToken(config, userId) {
+	const secret = new TextEncoder().encode(config.accessTokenSecret);
+	const now = Math.floor(config.now().getTime() / 1e3);
+	return new SignJWT({ type: MFA_CHALLENGE_TYPE }).setProtectedHeader({ alg: "HS256" }).setSubject(userId).setIssuedAt(now).setExpirationTime(now + MFA_CHALLENGE_TTL_SECONDS).sign(secret);
+}
+/**
+* Verifies an MFA challenge token and TOTP code, then issues a full auth session.
+*
+* Throws {@link InvalidTokenError} for an expired/invalid challenge token and
+* {@link TwoFactorError} for a wrong TOTP code.
+*/
+async function verifyMfaChallenge(deps, mfaToken, totpCode) {
+	const { config, store, audit } = deps;
+	const secret = new TextEncoder().encode(config.accessTokenSecret);
+	let userId;
+	try {
+		const { payload } = await jwtVerify(mfaToken, secret);
+		if (payload["type"] !== MFA_CHALLENGE_TYPE || typeof payload.sub !== "string") throw new InvalidTokenError("Invalid MFA challenge token.");
+		userId = payload.sub;
+	} catch {
+		throw new InvalidTokenError("MFA challenge token is invalid or expired.");
+	}
+	const record = await store.findTotpSecret?.(userId);
+	if (!record || !record.enabledAt) throw new TwoFactorError("2FA is not configured for this account.");
+	if (!verifyTotp(totpCode, record.secretBase32, config.now())) {
+		await audit.record("user.login.failed", userId, { reason: "invalid_totp" });
+		throw new TwoFactorError();
+	}
+	const user = await store.findUserById(userId);
+	if (!user) throw new InvalidTokenError();
+	await audit.record("user.login.succeeded", userId, { via: "mfa" });
+	return issueSession(deps, user);
+}
+//#endregion
+//#region core/login.ts
+/**
+* Authenticates a user with email + password. Uses a single generic failure for both
+* "unknown user" and "wrong password" to avoid account enumeration, and performs a hash
+* comparison even when the user is unknown to reduce timing side-channels.
+*
+* When account lockout is enabled (config.lockout.maxFailedAttempts > 0), consecutive
+* failures increment a counter and temporarily lock the account.
+*/
+async function loginUser(deps, input) {
+	const { config, store, hasher, audit } = deps;
+	const email = normalizeEmail(input.email);
+	const user = await store.findUserByEmail(email);
+	const credential = user ? await store.findCredential(user.userId) : null;
+	const storedHash = credential?.passwordHash ?? "scrypt$16384$00$00";
+	const passwordMatches = await hasher.verify(input.password, storedHash);
+	if (!user || !credential || !passwordMatches) {
+		if (user) {
+			await recordFailedAttempt(store, user, config.lockout, config.now);
+			if (user.failedLoginAttempts + 1 >= config.lockout.maxFailedAttempts && config.lockout.maxFailedAttempts > 0) await audit.record("user.account.locked", user.userId, {
+				email,
+				reason: "too_many_failures"
+			});
+		}
+		await audit.record("user.login.failed", user?.userId ?? null, { email });
+		throw new InvalidCredentialsError();
+	}
+	checkLockout(user, config.lockout, config.now);
+	if (user.status === "disabled" || user.status === "locked" && user.lockedUntil === null) {
+		await audit.record("user.login.failed", user.userId, {
+			email,
+			status: user.status
+		});
+		throw new AccountUnavailableError();
+	}
+	await clearLockout(store, user);
+	if (user.twoFactorEnabled) {
+		await audit.record("user.login.mfa.challenged", user.userId, { email });
+		return {
+			kind: "mfa_required",
+			mfaToken: await issueMfaChallengeToken(config, user.userId)
+		};
+	}
+	await audit.record("user.login.succeeded", user.userId, { email });
+	return issueSession(deps, user);
+}
+//#endregion
+//#region core/refresh-service.ts
+/**
+* Rotates a refresh session: validates the presented refresh token against the stored
+* hash, issues a new access token, and replaces the stored refresh-token hash.
+*
+* Detects refresh-token reuse (a token whose session exists but whose hash no longer
+* matches) and revokes the session as a precaution.
+*/
+async function refreshSession(deps, presentedToken) {
+	const { config, store, tokenService, audit } = deps;
+	const sessionId = tokenService.parseSessionId(presentedToken);
+	if (!sessionId) throw new InvalidTokenError();
+	const session = await store.findSessionById(sessionId);
+	const now = config.now();
+	if (!session || session.revokedAt || session.expiresAt.getTime() <= now.getTime()) throw new InvalidTokenError();
+	if (tokenService.hashRefreshToken(presentedToken) !== session.refreshTokenHash) {
+		await store.revokeSession(sessionId, now);
+		await audit.record("session.revoked", session.userId, { reason: "refresh-reuse" });
+		throw new InvalidTokenError();
+	}
+	const user = await store.findUserById(session.userId);
+	if (!user) throw new InvalidTokenError();
+	if (user.status !== "active") {
+		await store.revokeSession(sessionId, now);
+		throw new AccountUnavailableError();
+	}
+	const principal = await hydratePrincipal(store, user);
+	const access = await tokenService.issueAccessToken(user.userId, user.authVersion);
+	const refresh = tokenService.createRefreshToken(sessionId);
+	const refreshExpiresAt = new Date(now.getTime() + config.refreshTokenTtlSeconds * 1e3);
+	await store.rotateSession(sessionId, refresh.hash, refreshExpiresAt);
+	await audit.record("session.refreshed", user.userId, {});
+	return {
+		user: principal,
+		tokens: {
+			accessToken: access.token,
+			refreshToken: refresh.token,
+			accessTokenExpiresAt: access.expiresAt,
+			refreshTokenExpiresAt: refreshExpiresAt
+		}
+	};
+}
+/** Revokes a single session (logout). */
+async function revokeSession(deps, presentedToken) {
+	const { config, store, tokenService, audit } = deps;
+	const sessionId = tokenService.parseSessionId(presentedToken);
+	if (!sessionId) return;
+	const session = await store.findSessionById(sessionId);
+	if (!session || session.revokedAt) return;
+	await store.revokeSession(sessionId, config.now());
+	await audit.record("session.revoked", session.userId, { reason: "logout" });
+}
+//#endregion
+//#region core/verification-token.ts
+/**
+* Generates a cryptographically random opaque token and its SHA-256 hash.
+* Returns both: the raw token is sent to the user; only the hash is persisted.
+*/
+function generateVerificationToken() {
+	const token = randomBytes(32).toString("hex");
+	return {
+		token,
+		tokenHash: createHash("sha256").update(token).digest("hex")
+	};
+}
+/** Hashes a token presented by the user for secure lookup against stored hashes. */
+function hashVerificationToken(token) {
+	return createHash("sha256").update(token).digest("hex");
+}
+//#endregion
+//#region core/email-verification.ts
+/** Default token lifetime for email verification links. */
+const DEFAULT_TTL_SECONDS$1 = 1440 * 60;
+/** Raised when an email verification token is missing, expired, or already used. */
+var EmailVerificationError = class extends IdentityError {
+	constructor(message = "Email verification token is invalid or expired.") {
+		super("identity/email-verification-invalid", message, 400);
+	}
+};
+/**
+* Generates and persists a verification token, then calls the notification service.
+*
+* Safe to call after registration or when the user explicitly requests a resend.
+* Returns silently when the email is already verified.
+*/
+async function requestEmailVerification(deps, userId) {
+	const { config, store, audit } = deps;
+	const notifications = config.notifications;
+	const user = await store.findUserById(userId);
+	if (!user) throw new EmailVerificationError("User not found.");
+	if (user.emailVerifiedAt) return;
+	const { token, tokenHash } = generateVerificationToken();
+	const now = config.now();
+	const expiresAt = new Date(now.getTime() + DEFAULT_TTL_SECONDS$1 * 1e3);
+	await store.createVerificationToken?.({
+		tokenHash,
+		userId,
+		type: "email_verification",
+		expiresAt
+	});
+	await notifications?.sendEmailVerification?.({
+		email: user.email,
+		displayName: user.displayName,
+		token
+	});
+	await audit.record("user.email.verification.requested", userId, { email: user.email });
+}
+/**
+* Verifies the user's email address using the token from the verification link.
+*
+* Throws {@link EmailVerificationError} for unknown, expired, or already-used tokens.
+*/
+async function verifyEmail(deps, rawToken) {
+	const { config, store, audit } = deps;
+	const tokenHash = hashVerificationToken(rawToken);
+	const record = await store.findVerificationToken?.(tokenHash);
+	if (!record || record.type !== "email_verification") throw new EmailVerificationError();
+	if (record.usedAt) throw new EmailVerificationError("This verification link has already been used.");
+	const now = config.now();
+	if (record.expiresAt <= now) throw new EmailVerificationError("This verification link has expired.");
+	await store.markVerificationTokenUsed?.(tokenHash, now);
+	await store.updateUser(record.userId, { emailVerifiedAt: now });
+	await audit.record("user.email.verified", record.userId, {});
+}
+//#endregion
+//#region core/password-reset.ts
+/** Default token lifetime for password reset links. */
+const DEFAULT_TTL_SECONDS = 3600;
+const MIN_PASSWORD_LENGTH = 8;
+/** Raised when a password reset token is missing, expired, or already used. */
+var PasswordResetError = class extends IdentityError {
+	constructor(message = "Password reset token is invalid or expired.") {
+		super("identity/password-reset-invalid", message, 400);
+	}
+};
+/**
+* Generates a password reset token and dispatches the notification.
+*
+* Never reveals whether the email address exists in the system (returns silently for
+* unknown addresses) to prevent account enumeration.
+*/
+async function requestPasswordReset(deps, email) {
+	const { config, store, notifications, audit } = deps;
+	const normalized = normalizeEmail(email);
+	const user = await store.findUserByEmail(normalized);
+	if (!user) return;
+	const { token, tokenHash } = generateVerificationToken();
+	const now = config.now();
+	const expiresAt = new Date(now.getTime() + DEFAULT_TTL_SECONDS * 1e3);
+	await store.createVerificationToken?.({
+		tokenHash,
+		userId: user.userId,
+		type: "password_reset",
+		expiresAt
+	});
+	await (notifications ?? config.notifications)?.sendPasswordReset?.({
+		email: user.email,
+		displayName: user.displayName,
+		token
+	});
+	await audit.record("user.password.reset.requested", user.userId, { email: user.email });
+}
+/**
+* Validates the reset token and sets a new password.
+*
+* On success, bumps `authVersion` and revokes all existing sessions so outstanding
+* refresh tokens are immediately invalidated.
+*/
+async function resetPassword(deps, rawToken, newPassword) {
+	const { config, store, hasher, audit } = deps;
+	if (newPassword.length < MIN_PASSWORD_LENGTH) throw new PasswordResetError(`Password must be at least ${MIN_PASSWORD_LENGTH} characters.`);
+	const tokenHash = hashVerificationToken(rawToken);
+	const record = await store.findVerificationToken?.(tokenHash);
+	if (!record || record.type !== "password_reset") throw new PasswordResetError();
+	if (record.usedAt) throw new PasswordResetError("This reset link has already been used.");
+	const now = config.now();
+	if (record.expiresAt <= now) throw new PasswordResetError("This reset link has expired.");
+	await store.markVerificationTokenUsed?.(tokenHash, now);
+	const passwordHash = await hasher.hash(newPassword);
+	await store.upsertCredential({
+		userId: record.userId,
+		passwordHash,
+		updatedAt: now
+	});
+	const user = await store.findUserById(record.userId);
+	if (user) {
+		await store.updateUser(record.userId, { authVersion: user.authVersion + 1 });
+		await store.revokeAllSessions(record.userId, now);
+	}
+	await audit.record("user.password.reset.completed", record.userId, {});
+}
+//#endregion
+//#region core/account-admin.ts
+/** Raised when the target user does not exist. */
+var AccountAdminError = class extends IdentityError {
+	constructor(message) {
+		super("identity/account-not-found", message, 404);
+	}
+};
+/**
+* Locks a user account. Sets `status` to `"locked"` and immediately revokes all active
+* sessions so existing refresh tokens stop working.
+*
+* Typically called by an admin. The `AccountUnavailableError` is thrown during any
+* subsequent login or token verification attempt for the account.
+*/
+async function lockAccount(deps, userId) {
+	const { config, store, audit } = deps;
+	if (!await store.findUserById(userId)) throw new AccountAdminError(`User ${userId} not found.`);
+	const now = config.now();
+	await store.updateUser(userId, { status: "locked" });
+	await store.revokeAllSessions(userId, now);
+	await audit.record("user.account.locked", userId, { reason: "admin" });
+}
+/**
+* Unlocks a user account. Resets `status` to `"active"` and clears any stale lockout
+* counters so the user can log in immediately.
+*/
+async function unlockAccount(deps, userId) {
+	const { config, store, audit } = deps;
+	if (!await store.findUserById(userId)) throw new AccountAdminError(`User ${userId} not found.`);
+	await store.updateUser(userId, {
+		status: "active",
+		failedLoginAttempts: 0,
+		lockedUntil: null
+	});
+	await audit.record("user.account.unlocked", userId, {});
+}
+/**
+* Disables a user account. Sets `status` to `"disabled"` and revokes all sessions.
+* Unlike `lockAccount`, disabled accounts are not automatically unlockable by the
+* lockout timer — an explicit call to `unlockAccount` is required.
+*/
+async function disableAccount(deps, userId) {
+	const { config, store, audit } = deps;
+	if (!await store.findUserById(userId)) throw new AccountAdminError(`User ${userId} not found.`);
+	const now = config.now();
+	await store.updateUser(userId, { status: "disabled" });
+	await store.revokeAllSessions(userId, now);
+	await audit.record("user.account.locked", userId, { reason: "admin_disabled" });
+}
+//#endregion
+//#region core/identity-service.ts
+/**
+* Wires the framework-agnostic identity runtime with Node defaults (scrypt hashing,
+* `jose` HS256 tokens). Express and NestJS adapters build on top of this service.
+*/
+function createIdentityService(configInput, store) {
+	const config = resolveIdentityConfig(configInput);
+	const tokenService = createTokenService(config);
+	const hasher = createPasswordHasher(config.passwordScryptCost);
+	const audit = createAuditLogger(store, config.now, config.onEvent);
+	const deps = {
+		config,
+		store,
+		tokenService,
+		hasher,
+		audit
+	};
+	const mfaDeps = deps;
+	const emailDeps = {
+		config,
+		store,
+		audit
+	};
+	const oauthProviders = configInput.oauth?.providers;
+	return {
+		register: (input) => registerUser(deps, input),
+		login: (input) => loginUser(deps, input),
+		refresh: (refreshToken) => refreshSession(deps, refreshToken),
+		logout: (refreshToken) => revokeSession(deps, refreshToken),
+		async authenticate(accessToken) {
+			const claims = await tokenService.verifyAccessToken(accessToken);
+			const user = await store.findUserById(claims.sub);
+			if (!user || user.authVersion !== claims.authVersion) throw new InvalidTokenError();
+			if (user.status !== "active") throw new AccountUnavailableError();
+			return hydratePrincipal(store, user);
+		},
+		authorize: (requirement, context) => evaluateAuthorization(requirement, context),
+		requestEmailVerification: (userId) => requestEmailVerification(emailDeps, userId),
+		verifyEmail: (token) => verifyEmail(emailDeps, token),
+		requestPasswordReset: (email) => requestPasswordReset(deps, email),
+		resetPassword: (token, newPassword) => resetPassword(deps, token, newPassword),
+		setup2FA: (userId) => setup2FA(mfaDeps, userId),
+		enable2FA: (userId, code) => enable2FA(mfaDeps, userId, code),
+		disable2FA: (userId, code) => disable2FA(mfaDeps, userId, code),
+		verifyMfaChallenge: (mfaToken, code) => verifyMfaChallenge(mfaDeps, mfaToken, code),
+		lockAccount: (userId) => lockAccount(deps, userId),
+		unlockAccount: (userId) => unlockAccount(deps, userId),
+		disableAccount: (userId) => disableAccount(deps, userId),
+		oauth: oauthProviders && oauthProviders.length > 0 ? createOAuthService({
+			providers: oauthProviders,
+			config,
+			store,
+			sessionDeps: deps,
+			audit
+		}) : void 0
+	};
+}
+//#endregion
+//#region core/oauth/providers/google.ts
+const GOOGLE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+const GOOGLE_USERINFO_URL = "https://www.googleapis.com/oauth2/v3/userinfo";
+const DEFAULT_SCOPES$1 = [
+	"openid",
+	"email",
+	"profile"
+];
+/**
+* Creates an {@link OAuthProvider} configured for Google OAuth 2.0 / OpenID Connect.
+*
+* Security notes:
+* - The client secret is used only during server-side code exchange.
+* - The userinfo endpoint is called with the access token to fetch user data, providing
+*   a verified source of truth over the network (HTTPS).
+* - The `state` parameter is required and must be verified by the caller to prevent CSRF.
+*/
+function createGoogleOAuthProvider(config) {
+	const defaultScopes = config.scopes ?? DEFAULT_SCOPES$1;
+	return {
+		name: "google",
+		buildAuthorizationUrl({ redirectUri, state, scopes }) {
+			const url = new URL(GOOGLE_AUTH_URL);
+			url.searchParams.set("client_id", config.clientId);
+			url.searchParams.set("redirect_uri", redirectUri);
+			url.searchParams.set("response_type", "code");
+			url.searchParams.set("scope", (scopes ?? defaultScopes).join(" "));
+			url.searchParams.set("state", state);
+			url.searchParams.set("access_type", "offline");
+			return url.toString();
+		},
+		async exchangeCode({ code, redirectUri }) {
+			const body = new URLSearchParams({
+				code,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+				redirect_uri: redirectUri,
+				grant_type: "authorization_code"
+			});
+			const response = await fetch(GOOGLE_TOKEN_URL, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: body.toString()
+			});
+			const data = await response.json();
+			if (!response.ok || data.error) throw new Error(`Google token exchange failed: ${data.error_description ?? data.error ?? response.status}`);
+			return {
+				accessToken: data.access_token,
+				idToken: data.id_token,
+				tokenType: data.token_type,
+				expiresIn: data.expires_in,
+				refreshToken: data.refresh_token,
+				scope: data.scope
+			};
+		},
+		async fetchUserInfo(tokens) {
+			const response = await fetch(GOOGLE_USERINFO_URL, { headers: { authorization: `Bearer ${tokens.accessToken}` } });
+			const data = await response.json();
+			if (!response.ok) throw new Error(`Google userinfo request failed: ${data.error?.message ?? response.status}`);
+			return {
+				providerUserId: data.sub,
+				email: data.email ?? null,
+				emailVerified: data.email_verified === true,
+				displayName: data.name ?? null
+			};
+		}
+	};
+}
+//#endregion
+//#region core/oauth/providers/microsoft.ts
+const DEFAULT_SCOPES = [
+	"openid",
+	"email",
+	"profile",
+	"User.Read"
+];
+/**
+* Creates an {@link OAuthProvider} configured for Microsoft Entra ID OAuth 2.0 / OIDC.
+*
+* Security notes:
+* - The client secret is used only during server-side code exchange.
+* - User data is fetched from the Microsoft Graph API using the access token, providing
+*   a verified source of truth over HTTPS.
+* - The `state` parameter is required and must be verified by the caller to prevent CSRF.
+*/
+function createMicrosoftOAuthProvider(config) {
+	const tenantId = config.tenantId ?? "common";
+	const defaultScopes = config.scopes ?? DEFAULT_SCOPES;
+	const authBase = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0`;
+	return {
+		name: "microsoft",
+		buildAuthorizationUrl({ redirectUri, state, scopes }) {
+			const url = new URL(`${authBase}/authorize`);
+			url.searchParams.set("client_id", config.clientId);
+			url.searchParams.set("redirect_uri", redirectUri);
+			url.searchParams.set("response_type", "code");
+			url.searchParams.set("scope", (scopes ?? defaultScopes).join(" "));
+			url.searchParams.set("state", state);
+			url.searchParams.set("response_mode", "query");
+			return url.toString();
+		},
+		async exchangeCode({ code, redirectUri }) {
+			const body = new URLSearchParams({
+				code,
+				client_id: config.clientId,
+				client_secret: config.clientSecret,
+				redirect_uri: redirectUri,
+				grant_type: "authorization_code",
+				scope: defaultScopes.join(" ")
+			});
+			const response = await fetch(`${authBase}/token`, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: body.toString()
+			});
+			const data = await response.json();
+			if (!response.ok || data.error) throw new Error(`Microsoft token exchange failed: ${data.error_description ?? data.error ?? response.status}`);
+			return {
+				accessToken: data.access_token,
+				idToken: data.id_token,
+				tokenType: data.token_type,
+				expiresIn: data.expires_in,
+				refreshToken: data.refresh_token,
+				scope: data.scope
+			};
+		},
+		async fetchUserInfo(tokens) {
+			const response = await fetch("https://graph.microsoft.com/v1.0/me", { headers: { authorization: `Bearer ${tokens.accessToken}` } });
+			const data = await response.json();
+			if (!response.ok) throw new Error(`Microsoft Graph /me request failed: ${data.error?.message ?? response.status}`);
+			const email = data.mail ?? data.userPrincipalName ?? null;
+			return {
+				providerUserId: data.id,
+				email,
+				emailVerified: true,
+				displayName: data.displayName ?? null
+			};
+		}
+	};
+}
+//#endregion
+export { AccountAdminError, AccountUnavailableError, EmailAlreadyRegisteredError, EmailVerificationError, ForbiddenError, IdentityConfigError, IdentityError, InvalidCredentialsError, InvalidTokenError, OAuthProviderNotFoundError, OAuthStateMismatchError, PasswordResetError, RegistrationValidationError, TwoFactorError, TwoFactorRequiredError, UnauthenticatedError, base32Decode, base32Encode, buildOtpAuthUri, checkLockout, clearLockout, consoleLogger, createAuditLogger, createGoogleOAuthProvider, createIdentityService, createMicrosoftOAuthProvider, createOAuthService, createPasswordHasher, createTokenService, disable2FA, disableAccount, enable2FA, evaluateAuthorization, generateTotp, generateTotpSecret, generateVerificationToken, hashVerificationToken, identitySchemaModel, isAuthorized, issueMfaChallengeToken, lockAccount, loginUser, noopLogger, normalizeEmail, recordFailedAttempt, refreshSession, registerUser, requestEmailVerification, requestPasswordReset, resetPassword, resolveIdentityConfig, resolveLogger, revokeSession, setup2FA, unlockAccount, verifyEmail, verifyMfaChallenge, verifyTotp };
+
+//# sourceMappingURL=node.mjs.map