@db3.ai/app 0.1.0-beta.1

package/dist/auth/Auth.js

@@ -0,0 +1,927 @@
+import { ActiveRecord } from '../db/index.js';
+import { isPromiseLike } from '@db3.ai/pure';
+import { AuthProvider, PASSWORD_AUTH_PROVIDER } from './AuthProvider.js';
+import { AuthToken } from './AuthToken.js';
+import { PasswordResetToken } from './PasswordResetToken.js';
+import { defaultPasswordHash } from './passwordHash.js';
+import { UserIdentity } from './UserIdentity.js';
+import { PasswordAuthProvider, resolveAuthProviders } from './providers/index.js';
+/**
+ * Error thrown when registration would duplicate an existing identity.
+ */
+export class AuthIdentityExistsError extends Error {
+    field;
+    value;
+    /**
+     * Creates an identity duplication error.
+     *
+     * @param field - Logical identity field that collided.
+     * @param value - Submitted identity value.
+     */
+    constructor(field, value) {
+        super(`An identity already exists for ${field}.`);
+        this.field = field;
+        this.value = value;
+        this.name = 'AuthIdentityExistsError';
+    }
+}
+/**
+ * Error thrown when code attempts to use a disabled auth provider.
+ */
+export class AuthProviderNotConfiguredError extends Error {
+    provider;
+    /**
+     * Creates a provider configuration error.
+     *
+     * @param provider - Provider name that is not enabled.
+     */
+    constructor(provider) {
+        super(`Auth provider "${provider}" is not configured.`);
+        this.provider = provider;
+        this.name = 'AuthProviderNotConfiguredError';
+    }
+}
+/**
+ * Error thrown when unlinking a provider would leave a user unable to log in.
+ */
+export class AuthLastProviderError extends Error {
+    /**
+     * Creates a last-provider removal error.
+     */
+    constructor() {
+        super('Cannot remove the last authentication provider from a user.');
+        this.name = 'AuthLastProviderError';
+    }
+}
+export const AUTH_USER_CONTEXT_KEY = 'auth.user';
+const AUTH_TOKEN_CONTEXT_KEY_PREFIX = 'auth.token';
+const AUTH_TOKEN_RECORD_CONTEXT_KEY = 'auth.token.record';
+/**
+ * Authentication service for the current app/request scope.
+ */
+export class Auth {
+    fallbackAuthenticatedUser = null;
+    fallbackAuthenticatedToken = null;
+    db;
+    IdentityModel;
+    ProviderModel;
+    TokenModel;
+    PasswordResetTokenModel;
+    providerRegistry;
+    passwordHash;
+    tokenLifetimeMs;
+    passwordResetTokenLifetimeMs;
+    requestContext;
+    /**
+     * Creates an auth service bound to a database and provider registry.
+     *
+     * @param options - Auth runtime options.
+     */
+    constructor(options) {
+        this.db = options.db;
+        this.IdentityModel = options.identityModel
+            ?? UserIdentity;
+        this.ProviderModel = options.providerModel ?? AuthProvider;
+        this.TokenModel = options.tokenModel ?? AuthToken;
+        this.PasswordResetTokenModel = options.passwordResetTokenModel ?? PasswordResetToken;
+        this.passwordHash = options.passwordHash ?? defaultPasswordHash;
+        this.providerRegistry = resolveAuthProviders(options.providers ?? options.config?.get('auth.providers') ?? {
+            [PASSWORD_AUTH_PROVIDER]: true,
+        }, {
+            identityModel: this.IdentityModel,
+            providerModel: this.ProviderModel,
+            passwordHash: this.passwordHash,
+        });
+        this.tokenLifetimeMs = options.tokenLifetimeMs ?? 30 * 24 * 60 * 60 * 1000;
+        this.passwordResetTokenLifetimeMs = options.passwordResetTokenLifetimeMs ?? 60 * 60 * 1000;
+        this.requestContext = options.requestContext;
+    }
+    /**
+     * Hashes a plaintext password using the configured auth password service.
+     *
+     * @param plainText - Plaintext password to hash.
+     * @returns Stored password hash.
+     */
+    hashPassword(plainText) {
+        return this.passwordHash.hash(plainText);
+    }
+    /**
+     * Verifies a plaintext password against a stored password hash.
+     *
+     * @param plainText - Plaintext password supplied by the user.
+     * @param hash - Stored password hash.
+     * @returns True when the password matches.
+     */
+    verifyPassword(plainText, hash) {
+        return this.passwordHash.verify(plainText, hash);
+    }
+    /**
+     * Returns configured authentication provider names.
+     *
+     * @returns Enabled provider names.
+     */
+    configuredProviders() {
+        return Object.keys(this.providerRegistry);
+    }
+    /**
+     * True when a user is currently authenticated.
+     */
+    get check() {
+        return this.user !== null;
+    }
+    /**
+     * The currently authenticated user, or null when no user is authenticated.
+     */
+    get user() {
+        if (this.requestContext?.active) {
+            return this.requestContext.get(AUTH_USER_CONTEXT_KEY) ?? null;
+        }
+        return this.fallbackAuthenticatedUser;
+    }
+    /**
+     * Returns the bearer-token record authenticated for the current request.
+     */
+    get token() {
+        if (this.requestContext?.active) {
+            return this.requestContext.get(AUTH_TOKEN_RECORD_CONTEXT_KEY) ?? null;
+        }
+        return this.fallbackAuthenticatedToken;
+    }
+    /**
+     * Runs work inside an isolated auth scope.
+     *
+     * HTTP routes should use this so `auth.user` cannot bleed between concurrent
+     * requests on the shared app singleton.
+     *
+     * @param user - User to expose as authenticated inside the callback.
+     * @param callback - Work to run inside the auth scope.
+     * @returns The callback result.
+     */
+    runWithUser(user, callback) {
+        if (this.requestContext) {
+            return this.requestContext.run(callback, {
+                [AUTH_USER_CONTEXT_KEY]: user,
+            });
+        }
+        return this.runWithFallbackUser(user, callback);
+    }
+    /**
+     * Attempts to authenticate password credentials and stores the user on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @returns True when credentials authenticated successfully.
+     */
+    async attempt(credentials) {
+        return await this.authenticatePassword(credentials) !== null;
+    }
+    /**
+     * Authenticates password credentials and returns the user on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @returns Authenticated user, or null when credentials fail.
+     */
+    async authenticate(credentials) {
+        return this.authenticatePassword(credentials);
+    }
+    /**
+     * Authenticates password credentials and returns the user on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @returns Authenticated user, or null when credentials fail.
+     */
+    async authenticatePassword(credentials) {
+        return this.authenticateProvider(PASSWORD_AUTH_PROVIDER, credentials);
+    }
+    /**
+     * Authenticates credentials and creates a bearer token on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @param options - Token creation options.
+     * @returns Issued token, or null when credentials fail.
+     */
+    async issueToken(credentials, options = {}) {
+        return this.issueTokenForPassword(credentials, options);
+    }
+    /**
+     * Authenticates password credentials and creates a bearer token on success.
+     *
+     * @param credentials - Password provider credentials.
+     * @param options - Token creation options.
+     * @returns Issued token, or null when credentials fail.
+     */
+    async issueTokenForPassword(credentials, options = {}) {
+        const user = await this.authenticatePassword(credentials);
+        if (!user) {
+            return null;
+        }
+        return this.createToken(user, options);
+    }
+    /**
+     * Authenticates through a configured provider and creates a bearer token.
+     *
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @param options - Token creation options.
+     * @returns Issued token, or null when provider verification fails.
+     */
+    async issueTokenForProvider(provider, input, options = {}) {
+        const user = await this.authenticateProvider(provider, input);
+        if (!user) {
+            return null;
+        }
+        return this.createToken(user, options);
+    }
+    /**
+     * Creates a new password-backed identity and returns its first bearer token.
+     *
+     * @param input - User fields and password provider credential.
+     * @param options - Token creation options.
+     * @returns Issued token for the new user.
+     */
+    async register(input, options = {}) {
+        return this.registerWithPassword(input, options);
+    }
+    /**
+     * Creates a new user and links the built-in password provider.
+     *
+     * @param input - User fields and password provider credential.
+     * @param options - Token creation options.
+     * @returns Issued token for the new user.
+     */
+    async registerWithPassword(input, options = {}) {
+        this.requireProvider(PASSWORD_AUTH_PROVIDER);
+        const identity = this.normalizedIdentity(input);
+        if (identity) {
+            const existing = await this.findIdentity(input);
+            if (existing) {
+                throw new AuthIdentityExistsError(this.IdentityModel.identityField, identity);
+            }
+        }
+        const { password: _password, ...userInput } = input;
+        const user = new this.IdentityModel(userInput, {
+            db: this.db.knex,
+        });
+        await user.save();
+        await this.setPasswordProvider(user, input.password);
+        await this.login(user);
+        return this.createToken(user, options);
+    }
+    /**
+     * Returns the authentication providers linked to a user.
+     *
+     * @param user - User whose providers should be loaded.
+     * @returns Provider rows linked to the user.
+     */
+    async providersFor(user) {
+        const userId = this.userPrimaryKey(user);
+        if (!userId)
+            return [];
+        return this.ProviderModel
+            .query(this.db.knex)
+            .where('userId', userId)
+            .orderBy('createdAt', 'asc')
+            .all();
+    }
+    /**
+     * Links a configured provider to an existing user.
+     *
+     * @param user - User receiving the new provider link.
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @returns Linked provider row, or null when verification fails.
+     */
+    async linkProvider(user, provider, input) {
+        const driver = this.requireProvider(provider);
+        if (hasProviderLink(driver)) {
+            return ActiveRecord.withDb(this.db.knex, () => driver.link(user, input));
+        }
+        const profile = await this.verifyProvider(provider, input, user);
+        if (!profile)
+            return null;
+        return this.saveLinkedProvider(user, profile);
+    }
+    /**
+     * Removes one provider from a user while preserving at least one login path.
+     *
+     * @param user - User whose provider should be removed.
+     * @param providerIdOrName - Provider row id or provider name to remove.
+     * @returns True when a provider row was deleted.
+     */
+    async unlinkProvider(user, providerIdOrName) {
+        const providers = await this.providersFor(user);
+        if (providers.length <= 1) {
+            throw new AuthLastProviderError();
+        }
+        const provider = providers.find(candidate => {
+            return candidate.id === providerIdOrName || candidate.provider === providerIdOrName;
+        });
+        if (!provider)
+            return false;
+        await provider.delete(this.db.knex);
+        return true;
+    }
+    /**
+     * Creates or replaces the built-in password provider for a user.
+     *
+     * @param user - User who owns the password provider.
+     * @param password - New plaintext password to hash and store.
+     * @returns Saved password provider row.
+     */
+    async setPasswordProvider(user, password) {
+        return ActiveRecord.withDb(this.db.knex, () => {
+            return this.passwordProvider().setPassword(user, password);
+        });
+    }
+    /**
+     * Changes a user's password provider after verifying the current password.
+     *
+     * @param user - User whose password should change.
+     * @param currentPassword - Current plaintext password for verification.
+     * @param nextPassword - Replacement plaintext password.
+     * @returns True when the password was changed.
+     */
+    async changePasswordProvider(user, currentPassword, nextPassword) {
+        return ActiveRecord.withDb(this.db.knex, () => {
+            return this.passwordProvider().changePassword(user, currentPassword, nextPassword);
+        });
+    }
+    /**
+     * Authenticates through a non-password provider and stores the user on success.
+     *
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @returns Authenticated user, or null when verification fails.
+     */
+    async authenticateProvider(provider, input) {
+        const profile = await this.verifyProvider(provider, input, null);
+        if (!profile) {
+            this.logout();
+            return null;
+        }
+        const providerRecord = await this.findProvider(profile.provider, profile.providerUserId);
+        const user = providerRecord
+            ? await this.userForProvider(providerRecord)
+            : await this.createIdentityForProvider(profile);
+        if (!user) {
+            this.logout();
+            return null;
+        }
+        this.applyProviderProfileDefaults(user, profile);
+        const linkedProvider = providerRecord ?? new this.ProviderModel({}, {
+            db: this.db.knex,
+        });
+        linkedProvider.userId = this.userPrimaryKey(user);
+        linkedProvider.applyProfile(profile);
+        linkedProvider.markUsed();
+        await linkedProvider.save();
+        await this.login(user);
+        return user;
+    }
+    /**
+     * Creates a single-use password reset token for an already-loaded identity.
+     *
+     * Callers should find the identity at the request boundary and pass the
+     * loaded model here so token creation only owns token persistence.
+     *
+     * @param user - Identity receiving the reset token.
+     * @param options - Reset token creation options.
+     * @returns Issued password reset token.
+     */
+    async createPasswordResetToken(user, options = {}) {
+        this.requireProvider(PASSWORD_AUTH_PROVIDER);
+        const userId = this.userPrimaryKey(user);
+        const email = this.userIdentityValue(user);
+        if (!userId) {
+            throw new Error('Cannot create a password reset token for a user without an ID.');
+        }
+        if (!email) {
+            throw new Error('Cannot create a password reset token for a user without an email.');
+        }
+        const token = this.PasswordResetTokenModel.generatePlainTextToken();
+        const expiresAt = options.expiresAt ?? this.defaultPasswordResetTokenExpiry(options.expiresInMs);
+        const tokenRecord = new this.PasswordResetTokenModel({
+            userId,
+            email,
+            tokenHash: this.PasswordResetTokenModel.hashToken(token),
+            expiresAt,
+        }, {
+            db: this.db.knex,
+        });
+        await tokenRecord.save();
+        return {
+            type: 'password_reset',
+            token,
+            expiresAt,
+            user,
+        };
+    }
+    /**
+     * Resets the password provider using a valid password reset token.
+     *
+     * @param input - Reset token, new password, and optional identity value.
+     * @returns Identity whose password changed, or null when redemption fails.
+     */
+    async resetPassword(input) {
+        this.requireProvider(PASSWORD_AUTH_PROVIDER);
+        if (!input.token || !input.password) {
+            return null;
+        }
+        const tokenRecord = await this.PasswordResetTokenModel
+            .query(this.db.knex)
+            .where('tokenHash', this.PasswordResetTokenModel.hashToken(input.token))
+            .first();
+        if (!tokenRecord || !tokenRecord.isUsable()) {
+            return null;
+        }
+        const user = await this.IdentityModel.findByPk(tokenRecord.userId, this.db.knex);
+        if (!user) {
+            return null;
+        }
+        if (!await this.passwordResetIdentityMatches(input, user)) {
+            return null;
+        }
+        await this.setPasswordProvider(user, input.password);
+        tokenRecord.markUsed();
+        await tokenRecord.save();
+        return user;
+    }
+    /**
+     * Creates a bearer token for an already-authenticated identity.
+     *
+     * @param user - Identity receiving the bearer token.
+     * @param options - Token creation options.
+     * @returns Issued bearer token.
+     */
+    async createToken(user, options = {}) {
+        const userId = this.userPrimaryKey(user);
+        if (!userId) {
+            throw new Error('Cannot create an auth token for a user without an ID.');
+        }
+        const token = this.TokenModel.generatePlainTextToken();
+        const expiresAt = options.expiresAt === undefined
+            ? this.defaultTokenExpiry(options.expiresInMs)
+            : options.expiresAt;
+        const tokenRecord = new this.TokenModel({
+            userId,
+            tokenHash: this.TokenModel.hashToken(token),
+            name: options.name,
+            ipAddress: options.ipAddress,
+            userAgent: options.userAgent,
+            browser: options.browser,
+            operatingSystem: options.operatingSystem,
+            device: options.device,
+            expiresAt,
+        }, {
+            db: this.db.knex,
+        });
+        await tokenRecord.save();
+        return {
+            type: 'Bearer',
+            token,
+            expiresAt,
+            user,
+        };
+    }
+    /**
+     * Authenticates a bearer token and stores the matching identity on success.
+     *
+     * @param token - Plaintext bearer token.
+     * @param usage - Request metadata observed while authenticating the token.
+     * @returns Authenticated identity, or null when the token is invalid.
+     */
+    async authenticateToken(token, usage = {}) {
+        const tokenHash = this.TokenModel.hashToken(token);
+        if (this.requestContext?.active) {
+            const user = await this.requestContext.remember(this.tokenContextKey(tokenHash), () => this.authenticateTokenHash(tokenHash, usage));
+            if (user) {
+                this.setAuthenticatedUser(user);
+            }
+            else {
+                this.logout();
+            }
+            return user;
+        }
+        return this.authenticateTokenHash(tokenHash, usage);
+    }
+    /**
+     * Returns active bearer sessions belonging to a user.
+     *
+     * @param user - Account whose sessions should be listed.
+     * @returns Active, non-expired sessions ordered newest first.
+     */
+    async tokensFor(user) {
+        const userId = this.userPrimaryKey(user);
+        if (!userId)
+            return [];
+        const tokens = await this.TokenModel
+            .query(this.db.knex)
+            .where('userId', userId)
+            .whereNull('revokedAt')
+            .orderBy('createdAt', 'desc')
+            .all();
+        return tokens.filter(token => token.isActive());
+    }
+    /**
+     * Revokes one bearer session owned by a user.
+     *
+     * @param user - Account that owns the session.
+     * @param tokenId - Auth token primary key.
+     * @returns True when an active session was revoked.
+     */
+    async revokeToken(user, tokenId) {
+        const userId = this.userPrimaryKey(user);
+        if (!userId || !tokenId)
+            return false;
+        const token = await this.TokenModel
+            .query(this.db.knex)
+            .where('id', tokenId)
+            .where('userId', userId)
+            .first();
+        if (!token || !token.isActive())
+            return false;
+        token.revoke();
+        await token.save();
+        return true;
+    }
+    /**
+     * Revokes the bearer session authenticated for the current request.
+     *
+     * @returns True when the current session was revoked.
+     */
+    async revokeCurrentToken() {
+        const token = this.token;
+        if (!token || !token.isActive())
+            return false;
+        token.revoke();
+        await token.save();
+        this.logout();
+        return true;
+    }
+    /**
+     * Builds the request-context key used to memoize bearer-token authentication.
+     *
+     * @param tokenHash - Hashed bearer token.
+     * @returns Request-context cache key.
+     */
+    tokenContextKey(tokenHash) {
+        return `${AUTH_TOKEN_CONTEXT_KEY_PREFIX}.${this.TokenModel.table}.${tokenHash}`;
+    }
+    /**
+     * Authenticates a pre-hashed bearer token against persistent auth records.
+     *
+     * @param tokenHash - Hashed bearer token.
+     * @returns Authenticated identity, or null when the token is invalid.
+     */
+    async authenticateTokenHash(tokenHash, usage) {
+        const tokenRecord = await this.TokenModel
+            .query(this.db.knex)
+            .where('tokenHash', tokenHash)
+            .first();
+        if (!tokenRecord || !tokenRecord.isActive()) {
+            this.logout();
+            return null;
+        }
+        const user = await this.IdentityModel.findByPk(tokenRecord.userId, this.db.knex);
+        if (!user) {
+            this.logout();
+            return null;
+        }
+        tokenRecord.markUsed(new Date(), usage);
+        await tokenRecord.save();
+        this.setAuthenticatedToken(tokenRecord);
+        await this.login(user);
+        return user;
+    }
+    /**
+     * Marks a user model as authenticated.
+     *
+     * @param user - User to mark as authenticated.
+     * @returns The saved authenticated user.
+     */
+    async login(user) {
+        this.setAuthenticatedUser(user);
+        user.setDb(this.db.knex);
+        user.lastLoginAt = new Date();
+        await user.save();
+        return user;
+    }
+    /**
+     * Clears the authenticated user.
+     */
+    logout() {
+        this.setAuthenticatedUser(null);
+        this.setAuthenticatedToken(null);
+    }
+    /**
+     * Returns the authenticated user or throws when auth is missing.
+     *
+     * @returns The current authenticated user.
+     */
+    requireUser() {
+        const user = this.user;
+        if (!user) {
+            throw new Error('No authenticated user.');
+        }
+        return user;
+    }
+    /**
+     * Verifies provider-specific input and normalizes the returned profile.
+     *
+     * @param provider - Configured provider name.
+     * @param input - Provider-specific credential payload.
+     * @param user - Current user when linking a provider.
+     * @returns Normalized provider profile, or null when verification fails.
+     */
+    async verifyProvider(provider, input, user) {
+        const driver = this.requireProvider(provider);
+        const profile = await ActiveRecord.withDb(this.db.knex, () => {
+            return driver.verify(input);
+        });
+        if (!profile)
+            return null;
+        return {
+            ...profile,
+            provider,
+        };
+    }
+    /**
+     * Resolves a configured provider or throws a configuration error.
+     *
+     * @param provider - Provider name to resolve.
+     * @returns Provider configuration.
+     */
+    requireProvider(provider) {
+        if (!Object.prototype.hasOwnProperty.call(this.providerRegistry, provider)) {
+            throw new AuthProviderNotConfiguredError(provider);
+        }
+        return this.providerRegistry[provider];
+    }
+    /**
+     * Resolves the configured password provider.
+     *
+     * @returns Password provider driver with password mutation helpers.
+     */
+    passwordProvider() {
+        const provider = this.requireProvider(PASSWORD_AUTH_PROVIDER);
+        if (!(provider instanceof PasswordAuthProvider)) {
+            throw new AuthProviderNotConfiguredError(PASSWORD_AUTH_PROVIDER);
+        }
+        return provider;
+    }
+    /**
+     * Saves a verified provider profile onto a user account.
+     *
+     * @param user - User receiving the provider link.
+     * @param profile - Verified provider profile.
+     * @returns Saved provider row.
+     */
+    async saveLinkedProvider(user, profile) {
+        const existing = await this.findProvider(profile.provider, profile.providerUserId);
+        const userId = this.userPrimaryKey(user);
+        if (!userId) {
+            throw new Error('Cannot link an auth provider to a user without an ID.');
+        }
+        if (existing && existing.userId !== userId) {
+            throw new AuthIdentityExistsError('provider', `${profile.provider}:${profile.providerUserId}`);
+        }
+        const providerRecord = existing ?? new this.ProviderModel({}, {
+            db: this.db.knex,
+        });
+        providerRecord.userId = userId;
+        providerRecord.applyProfile(profile);
+        await providerRecord.save();
+        return providerRecord;
+    }
+    /**
+     * Finds a provider row by provider-owned identity.
+     *
+     * @param provider - Provider name.
+     * @param providerUserId - Provider-owned account id.
+     * @returns Matching provider row, or null.
+     */
+    async findProvider(provider, providerUserId) {
+        return this.ProviderModel
+            .query(this.db.knex)
+            .where('provider', provider)
+            .where('providerUserId', providerUserId)
+            .first();
+    }
+    /**
+     * Loads the user attached to a provider row.
+     *
+     * @param provider - Persisted provider row.
+     * @returns Linked identity, or null when missing.
+     */
+    async userForProvider(provider) {
+        if (!provider.userId)
+            return null;
+        return this.IdentityModel.findByPk(provider.userId, this.db.knex);
+    }
+    /**
+     * Creates a user account from a verified external provider profile.
+     *
+     * @param profile - Verified provider profile.
+     * @returns Created identity, or null when no email is available.
+     */
+    async createIdentityForProvider(profile) {
+        const email = profile.email ? normalizeIdentity(profile.email) : null;
+        if (!email)
+            return null;
+        const existing = await this.findIdentity({
+            [this.IdentityModel.identityField]: email,
+        });
+        if (existing) {
+            throw new AuthIdentityExistsError(this.IdentityModel.identityField, email);
+        }
+        const user = new this.IdentityModel({
+            name: profile.name || defaultNameForEmail(email),
+            email,
+            emailVerifiedAt: profile.emailVerifiedAt ?? null,
+            avatarUrl: profile.avatarUrl ?? null,
+        }, {
+            db: this.db.knex,
+        });
+        await user.save();
+        return user;
+    }
+    /**
+     * Backfills account-owned profile fields from a verified provider profile.
+     *
+     * Provider values are defaults only. Existing account values are preserved
+     * so a later user-selected avatar is not overwritten during provider login.
+     * The normal login save persists any backfilled values.
+     *
+     * @param user - Authenticated account receiving missing defaults.
+     * @param profile - Verified provider profile.
+     */
+    applyProviderProfileDefaults(user, profile) {
+        if (!user.avatarUrl && profile.avatarUrl) {
+            user.avatarUrl = profile.avatarUrl;
+        }
+    }
+    /**
+     * Stores the current authenticated user in request or fallback scope.
+     *
+     * @param user - User to expose as authenticated.
+     */
+    setAuthenticatedUser(user) {
+        if (this.requestContext?.active) {
+            this.requestContext.set(AUTH_USER_CONTEXT_KEY, user);
+            return;
+        }
+        this.fallbackAuthenticatedUser = user;
+    }
+    /**
+     * Stores the authenticated token in request or fallback scope.
+     *
+     * @param token - Token record to expose for session management.
+     */
+    setAuthenticatedToken(token) {
+        if (this.requestContext?.active) {
+            this.requestContext.set(AUTH_TOKEN_RECORD_CONTEXT_KEY, token);
+            return;
+        }
+        this.fallbackAuthenticatedToken = token;
+    }
+    /**
+     * Runs a callback with a temporary fallback user outside request scope.
+     *
+     * @param user - User to expose during the callback.
+     * @param callback - Work to run with the temporary user.
+     * @returns The callback result.
+     */
+    runWithFallbackUser(user, callback) {
+        const previousUser = this.fallbackAuthenticatedUser;
+        this.fallbackAuthenticatedUser = user;
+        try {
+            const result = callback();
+            if (isPromiseLike(result)) {
+                return Promise.resolve(result).finally(() => {
+                    this.fallbackAuthenticatedUser = previousUser;
+                });
+            }
+            this.fallbackAuthenticatedUser = previousUser;
+            return result;
+        }
+        catch (error) {
+            this.fallbackAuthenticatedUser = previousUser;
+            throw error;
+        }
+    }
+    /**
+     * Finds an identity by the configured identity field.
+     *
+     * @param input - Payload containing the configured identity value.
+     * @returns Matching identity, or null.
+     */
+    async findIdentity(input) {
+        const identityField = this.IdentityModel.identityField;
+        const identityValue = input[identityField];
+        if (identityValue === undefined || identityValue === null) {
+            return null;
+        }
+        return await this.IdentityModel
+            .query(this.db.knex)
+            .where(identityField, '=', identityValue)
+            .first();
+    }
+    /**
+     * Checks whether password reset input belongs to the loaded user.
+     *
+     * @param input - Reset password payload.
+     * @param user - User loaded from the reset token.
+     * @returns True when the submitted identity is absent or matches the token user.
+     */
+    async passwordResetIdentityMatches(input, user) {
+        const identityField = this.IdentityModel.identityField;
+        const inputIdentity = input[identityField];
+        if (inputIdentity === undefined || inputIdentity === null || inputIdentity === '') {
+            return true;
+        }
+        const inputUser = await this.findIdentity(input);
+        return inputUser?.get(this.IdentityModel.primaryKey) === user.get(this.IdentityModel.primaryKey);
+    }
+    /**
+     * Reads a user primary key as a non-empty string.
+     *
+     * @param user - User model to inspect.
+     * @returns Primary key string, or null when missing.
+     */
+    userPrimaryKey(user) {
+        const value = user.get(this.IdentityModel.primaryKey);
+        return value === null || value === undefined || value === ''
+            ? null
+            : String(value);
+    }
+    /**
+     * Reads the configured identity value from a user.
+     *
+     * @param user - User model to inspect.
+     * @returns Normalized identity value, or null when missing.
+     */
+    userIdentityValue(user) {
+        return normalizeIdentity(user.get(this.IdentityModel.identityField));
+    }
+    /**
+     * Reads the configured identity value from a payload.
+     *
+     * @param input - Payload to inspect.
+     * @returns Normalized identity value, or null when missing.
+     */
+    normalizedIdentity(input) {
+        return normalizeIdentity(input[this.IdentityModel.identityField]);
+    }
+    /**
+     * Calculates the default bearer token expiry.
+     *
+     * @param expiresInMs - Optional token lifetime override.
+     * @returns Absolute expiry time, or null for a non-expiring token.
+     */
+    defaultTokenExpiry(expiresInMs) {
+        const lifetime = expiresInMs === undefined
+            ? this.tokenLifetimeMs
+            : expiresInMs;
+        return lifetime === null
+            ? null
+            : new Date(Date.now() + lifetime);
+    }
+    /**
+     * Calculates the default password reset token expiry.
+     *
+     * @param expiresInMs - Optional reset token lifetime override.
+     * @returns Absolute expiry time.
+     */
+    defaultPasswordResetTokenExpiry(expiresInMs) {
+        return new Date(Date.now() + (expiresInMs ?? this.passwordResetTokenLifetimeMs));
+    }
+}
+/**
+ * Normalizes an auth identity value for provider matching.
+ *
+ * @param value - Unknown identity value.
+ * @returns Lowercase trimmed identity string, or null.
+ */
+function normalizeIdentity(value) {
+    if (typeof value !== 'string')
+        return null;
+    const normalized = value.trim().toLowerCase();
+    return normalized || null;
+}
+/**
+ * Builds a fallback display name from an email address.
+ *
+ * @param email - Normalized email address.
+ * @returns Human-readable display name.
+ */
+function defaultNameForEmail(email) {
+    return email.replace(/@.+$/, '') || 'User';
+}
+/**
+ * Checks whether a driver owns custom provider-link behavior.
+ *
+ * @param driver - Provider driver to inspect.
+ * @returns True when a custom link method is available.
+ */
+function hasProviderLink(driver) {
+    return typeof driver.link === 'function';
+}