@technomoron/api-server-base 1.1.13 → 2.0.0-beta.2

package/dist/esm/auth-api/auth-module.js

@@ -0,0 +1,1030 @@
+import { createHash } from 'node:crypto';
+import { ApiError } from '../api-server-base.js';
+import { BaseAuthModule } from './module.js';
+function isAuthIdentifier(value) {
+    return typeof value === 'string' || typeof value === 'number';
+}
+function toStringOrNull(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    return null;
+}
+function toScopeArray(scope) {
+    if (typeof scope === 'string') {
+        return scope.split(/\s+/).filter((entry) => entry.length > 0);
+    }
+    if (Array.isArray(scope) && scope.every((entry) => typeof entry === 'string')) {
+        return scope.filter((entry) => entry.length > 0);
+    }
+    return undefined;
+}
+function base64UrlEncode(buffer) {
+    return buffer.toString('base64').replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function sha256Base64Url(value) {
+    const hash = createHash('sha256').update(value).digest();
+    return base64UrlEncode(hash);
+}
+class AuthModule extends BaseAuthModule {
+    constructor(options = {}) {
+        super({ namespace: options.namespace ?? AuthModule.defaultNamespace });
+        this.defaultDomain = options.defaultDomain;
+        this.canImpersonateHook = options.canImpersonate;
+    }
+    get storage() {
+        return this.server.getAuthStorage();
+    }
+    async canImpersonate(apiReq, realUser, targetUser) {
+        const realUserId = this.storage.getUserId(realUser);
+        const effectiveUserId = this.storage.getUserId(targetUser);
+        if (this.canImpersonateHook) {
+            const allowed = await this.canImpersonateHook({
+                apiReq,
+                realUser,
+                realUserId,
+                targetUser,
+                effectiveUserId
+            });
+            if (allowed) {
+                return true;
+            }
+        }
+        const storageWithHook = this.storage;
+        if (typeof storageWithHook.canImpersonate === 'function') {
+            const allowed = await storageWithHook.canImpersonate({ realUserId, effectiveUserId });
+            return !!allowed;
+        }
+        return realUserId === effectiveUserId;
+    }
+    async ensureImpersonationAllowed(apiReq, realUser, targetUser) {
+        const permitted = await this.canImpersonate(apiReq, realUser, targetUser);
+        if (!permitted) {
+            throw new ApiError({ code: 403, message: 'Impersonation is not permitted' });
+        }
+    }
+    buildTokenPayload(user, metadata = {}) {
+        return {
+            ...metadata,
+            uid: String(this.storage.getUserId(user))
+        };
+    }
+    buildTokenMetadata(metadata = {}) {
+        const scope = metadata.scope;
+        return {
+            domain: metadata.domain ?? this.defaultDomain ?? '',
+            fingerprint: metadata.fingerprint ?? metadata.clientId ?? '',
+            label: metadata.label ?? (Array.isArray(scope) ? scope.join(' ') : typeof scope === 'string' ? scope : ''),
+            clientId: metadata.clientId,
+            ruid: metadata.ruid,
+            scope: metadata.scope,
+            browser: metadata.browser ?? '',
+            device: metadata.device ?? '',
+            ip: metadata.ip ?? '',
+            os: metadata.os ?? '',
+            refreshTtlSeconds: this.normalizeRefreshTtlSeconds(metadata.refreshTtlSeconds),
+            sessionCookie: typeof metadata.sessionCookie === 'boolean' ? metadata.sessionCookie : undefined,
+            loginType: metadata.loginType
+        };
+    }
+    enrichTokenMetadata(apiReq, metadata = {}) {
+        const enriched = { ...metadata };
+        const clientInfo = apiReq.getClientInfo();
+        if (!enriched.ip && clientInfo.ip) {
+            enriched.ip = clientInfo.ip;
+        }
+        if (!enriched.browser && clientInfo.browser) {
+            enriched.browser = clientInfo.browser;
+        }
+        if (!enriched.os && clientInfo.os) {
+            enriched.os = clientInfo.os;
+        }
+        if (!enriched.device && clientInfo.device) {
+            enriched.device = clientInfo.device;
+        }
+        return enriched;
+    }
+    sessionRefreshTtlSeconds() {
+        return Math.max(1, this.server.config.sessionRefreshExpiry ?? 24 * 60 * 60);
+    }
+    normalizeRefreshTtlSeconds(value) {
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+            return Math.floor(value);
+        }
+        if (typeof value === 'string') {
+            const trimmed = value.trim();
+            if (!trimmed) {
+                return undefined;
+            }
+            const parsed = Number(trimmed);
+            if (Number.isFinite(parsed) && parsed > 0) {
+                return Math.floor(parsed);
+            }
+        }
+        return undefined;
+    }
+    resolveSessionPreferences(candidate) {
+        if (candidate === undefined || candidate === null) {
+            return {};
+        }
+        if (typeof candidate === 'boolean') {
+            return candidate ? {} : { sessionCookie: true, refreshTtlSeconds: this.sessionRefreshTtlSeconds() };
+        }
+        if (typeof candidate === 'number') {
+            const ttl = this.normalizeRefreshTtlSeconds(candidate);
+            return ttl ? { sessionCookie: false, refreshTtlSeconds: ttl } : {};
+        }
+        if (typeof candidate === 'string') {
+            const trimmed = candidate.trim();
+            if (!trimmed) {
+                return {};
+            }
+            if (/^(true|yes|1)$/i.test(trimmed)) {
+                return {};
+            }
+            if (/^(false|no|0)$/i.test(trimmed)) {
+                return { sessionCookie: true, refreshTtlSeconds: this.sessionRefreshTtlSeconds() };
+            }
+            const ttl = this.normalizeRefreshTtlSeconds(trimmed);
+            return ttl ? { sessionCookie: false, refreshTtlSeconds: ttl } : {};
+        }
+        return {};
+    }
+    mergeSessionPreferences(...prefs) {
+        const merged = {};
+        for (const pref of prefs) {
+            if (!pref) {
+                continue;
+            }
+            if (merged.sessionCookie === undefined && pref.sessionCookie !== undefined) {
+                merged.sessionCookie = pref.sessionCookie;
+            }
+            if (merged.refreshTtlSeconds === undefined && typeof pref.refreshTtlSeconds === 'number') {
+                merged.refreshTtlSeconds = pref.refreshTtlSeconds;
+            }
+        }
+        return merged;
+    }
+    sessionPrefsFromRecord(record) {
+        if (!record) {
+            return {};
+        }
+        const carrier = record;
+        const prefs = {};
+        if (typeof carrier.sessionCookie === 'boolean') {
+            prefs.sessionCookie = carrier.sessionCookie;
+        }
+        const ttl = this.normalizeRefreshTtlSeconds(carrier.refreshTtlSeconds);
+        if (ttl !== undefined) {
+            prefs.refreshTtlSeconds = ttl;
+        }
+        return prefs;
+    }
+    cookieOptions(apiReq) {
+        const conf = this.server.config;
+        const forwarded = apiReq.req.headers['x-forwarded-proto'];
+        const referer = apiReq.req.headers['origin'] ?? apiReq.req.headers['referer'];
+        const origin = typeof referer === 'string' ? referer : '';
+        const isHttps = forwarded === 'https' || apiReq.req.protocol === 'https';
+        const isLocalhost = origin.includes('localhost');
+        const options = {
+            httpOnly: true,
+            secure: true,
+            sameSite: 'strict',
+            domain: conf.cookieDomain || undefined,
+            path: '/',
+            maxAge: undefined
+        };
+        if (conf.devMode) {
+            options.secure = isHttps;
+            options.httpOnly = false;
+            options.sameSite = 'lax';
+            if (isLocalhost) {
+                options.domain = undefined;
+            }
+        }
+        return options;
+    }
+    setJwtCookies(apiReq, tokens, preferences = {}) {
+        const conf = this.server.config;
+        const options = this.cookieOptions(apiReq);
+        const sessionCookie = preferences.sessionCookie ?? false;
+        const accessMaxAge = Math.max(1, conf.accessExpiry) * 1000;
+        const refreshSeconds = Math.max(1, preferences.refreshTtlSeconds ?? conf.refreshExpiry);
+        const refreshMaxAge = refreshSeconds * 1000;
+        const accessOptions = sessionCookie ? options : { ...options, maxAge: accessMaxAge };
+        const refreshOptions = sessionCookie ? options : { ...options, maxAge: refreshMaxAge };
+        if (tokens.accessToken) {
+            apiReq.res.cookie(conf.accessCookie, tokens.accessToken, accessOptions);
+        }
+        else {
+            apiReq.res.clearCookie(conf.accessCookie, options);
+        }
+        if (tokens.refreshToken) {
+            apiReq.res.cookie(conf.refreshCookie, tokens.refreshToken, refreshOptions);
+        }
+        else {
+            apiReq.res.clearCookie(conf.refreshCookie, options);
+        }
+    }
+    async issueTokens(apiReq, user, metadata = {}) {
+        const conf = this.server.config;
+        const enrichedMetadata = this.enrichTokenMetadata(apiReq, metadata);
+        const payload = this.buildTokenPayload(user, enrichedMetadata);
+        const access = this.server.jwtSign(payload, conf.accessSecret, conf.accessExpiry);
+        if (!access.success || !access.token) {
+            throw new ApiError({ code: 500, message: access.error ?? 'Unable to sign access token' });
+        }
+        const refresh = this.server.jwtSign(payload, conf.refreshSecret, conf.refreshExpiry);
+        if (!refresh.success || !refresh.token) {
+            throw new ApiError({ code: 500, message: refresh.error ?? 'Unable to sign refresh token' });
+        }
+        const meta = this.buildTokenMetadata(enrichedMetadata);
+        const wantsSessionCookie = meta.sessionCookie === true;
+        const customRefreshTtl = typeof meta.refreshTtlSeconds === 'number' ? meta.refreshTtlSeconds : undefined;
+        const sessionRefreshTtl = this.sessionRefreshTtlSeconds();
+        const defaultRefreshTtl = Math.max(1, conf.refreshExpiry);
+        const refreshLifetimeSeconds = wantsSessionCookie
+            ? Math.max(1, customRefreshTtl ?? sessionRefreshTtl)
+            : Math.max(1, customRefreshTtl ?? defaultRefreshTtl);
+        const storedRefreshTtlSeconds = wantsSessionCookie
+            ? Math.max(1, customRefreshTtl ?? sessionRefreshTtl)
+            : customRefreshTtl;
+        meta.refreshTtlSeconds =
+            typeof storedRefreshTtlSeconds === 'number' && storedRefreshTtlSeconds > 0
+                ? storedRefreshTtlSeconds
+                : undefined;
+        meta.sessionCookie = wantsSessionCookie;
+        const expiresAt = metadata.expires ?? new Date(Date.now() + refreshLifetimeSeconds * 1000);
+        const issuedAt = new Date();
+        const lastSeenAt = issuedAt;
+        await this.storage.storeToken({
+            accessToken: access.token,
+            refreshToken: refresh.token,
+            userId: payload.uid,
+            ruid: meta.ruid,
+            domain: meta.domain,
+            fingerprint: meta.fingerprint,
+            label: meta.label,
+            browser: meta.browser,
+            device: meta.device,
+            ip: meta.ip,
+            os: meta.os,
+            clientId: meta.clientId,
+            scope: meta.scope,
+            loginType: meta.loginType,
+            refreshTtlSeconds: meta.refreshTtlSeconds,
+            expires: expiresAt,
+            issuedAt,
+            lastSeenAt
+        });
+        this.setJwtCookies(apiReq, {
+            accessToken: access.token,
+            refreshToken: refresh.token
+        }, {
+            sessionCookie: wantsSessionCookie,
+            refreshTtlSeconds: refreshLifetimeSeconds
+        });
+        return {
+            accessToken: access.token,
+            refreshToken: refresh.token
+        };
+    }
+    assertAuthReady() {
+        const conf = this.server.config;
+        if (!conf.accessSecret || !conf.refreshSecret) {
+            throw new ApiError({ code: 500, message: 'Auth secrets are not configured' });
+        }
+    }
+    parseLoginBody(apiReq) {
+        const body = (apiReq.req.body ?? {});
+        const login = toStringOrNull(body.login);
+        const password = toStringOrNull(body.password);
+        const sessionPrefs = this.resolveSessionPreferences(body.keepSession);
+        if (!login || !password) {
+            const errors = {};
+            if (!login) {
+                errors.login = 'Login is required';
+            }
+            if (!password) {
+                errors.password = 'Password is required';
+            }
+            throw new ApiError({ code: 400, message: 'Missing credentials', errors });
+        }
+        return {
+            login,
+            password,
+            domain: toStringOrNull(body.domain) ?? undefined,
+            fingerprint: toStringOrNull(body.fingerprint) ?? undefined,
+            label: toStringOrNull(body.label) ?? undefined,
+            browser: toStringOrNull(body.browser) ?? undefined,
+            device: toStringOrNull(body.device) ?? undefined,
+            ip: toStringOrNull(body.ip) ?? undefined,
+            os: toStringOrNull(body.os) ?? undefined,
+            loginType: 'credentials',
+            ...sessionPrefs
+        };
+    }
+    parseImpersonationRequest(apiReq) {
+        const body = (apiReq.req.body ?? {});
+        const targetIdentifier = this.resolveImpersonationIdentifier(body);
+        const metadata = this.buildImpersonationMetadata(body);
+        return { targetIdentifier, metadata };
+    }
+    resolveImpersonationIdentifier(body) {
+        if (isAuthIdentifier(body.userId)) {
+            return body.userId;
+        }
+        const login = toStringOrNull(body.login);
+        if (login) {
+            return login;
+        }
+        throw new ApiError({ code: 400, message: 'userId or login is required' });
+    }
+    buildImpersonationMetadata(body) {
+        const sessionPrefs = this.resolveSessionPreferences(body.keepSession);
+        return {
+            domain: toStringOrNull(body.domain) ?? undefined,
+            fingerprint: toStringOrNull(body.fingerprint) ?? undefined,
+            label: toStringOrNull(body.label) ?? undefined,
+            browser: toStringOrNull(body.browser) ?? undefined,
+            device: toStringOrNull(body.device) ?? undefined,
+            ip: toStringOrNull(body.ip) ?? undefined,
+            os: toStringOrNull(body.os) ?? undefined,
+            clientId: toStringOrNull(body.clientId) ?? undefined,
+            scope: toScopeArray(body.scope),
+            loginType: toStringOrNull(body.loginType) ?? undefined,
+            ...sessionPrefs
+        };
+    }
+    async getUserOrThrow(identifier, errorMessage) {
+        const user = await this.storage.getUser(identifier);
+        if (!user) {
+            throw new ApiError({ code: 403, message: errorMessage });
+        }
+        return user;
+    }
+    getRealUserIdentifier(apiReq) {
+        const candidate = typeof apiReq.getRealUid === 'function'
+            ? apiReq.getRealUid()
+            : (apiReq.realUid ?? null);
+        if (!isAuthIdentifier(candidate)) {
+            throw new ApiError({ code: 401, message: 'Authentication required' });
+        }
+        return candidate;
+    }
+    async resolveActorContext(apiReq) {
+        const realIdentifier = this.getRealUserIdentifier(apiReq);
+        const user = await this.getUserOrThrow(realIdentifier, 'Authenticated user not found');
+        return { user, userId: this.storage.getUserId(user) };
+    }
+    extractRefreshToken(apiReq, body) {
+        const conf = this.server.config;
+        if (typeof body.refreshToken === 'string') {
+            return body.refreshToken;
+        }
+        const logoutBody = body;
+        if (typeof logoutBody.token === 'string') {
+            return logoutBody.token;
+        }
+        const fromCookie = apiReq.req.cookies?.[conf.refreshCookie];
+        return typeof fromCookie === 'string' && fromCookie.length > 0 ? fromCookie : null;
+    }
+    normalizeScope(scope) {
+        if (typeof scope === 'string') {
+            return scope;
+        }
+        if (Array.isArray(scope) && scope.every((entry) => typeof entry === 'string')) {
+            return scope;
+        }
+        return undefined;
+    }
+    async postLogin(apiReq) {
+        this.assertAuthReady();
+        const { login, password, ...metadata } = this.parseLoginBody(apiReq);
+        const user = await this.storage.getUser(login);
+        if (!user) {
+            throw new ApiError({
+                code: 400,
+                message: 'Invalid credentials',
+                errors: { login: 'Unknown user' }
+            });
+        }
+        const hash = this.storage.getUserPasswordHash(user);
+        const verified = await this.storage.verifyPassword(password, hash);
+        if (!verified) {
+            throw new ApiError({
+                code: 400,
+                message: 'Invalid credentials',
+                errors: { password: 'Wrong password' }
+            });
+        }
+        const pair = await this.issueTokens(apiReq, user, metadata);
+        const publicUser = this.storage.filterUser(user);
+        return [200, { ...pair, user: publicUser }];
+    }
+    async postRefresh(apiReq) {
+        this.assertAuthReady();
+        const body = (apiReq.req.body ?? {});
+        const sessionPrefs = this.resolveSessionPreferences(body.keepSession);
+        const providedToken = this.extractRefreshToken(apiReq, body);
+        if (!providedToken) {
+            throw new ApiError({ code: 401, message: 'Missing refresh token' });
+        }
+        const stored = await this.storage.getToken({ refreshToken: providedToken });
+        if (!stored) {
+            throw new ApiError({ code: 401, message: 'Invalid refresh token' });
+        }
+        const verify = this.server.jwtVerify(providedToken, this.server.config.refreshSecret);
+        if (!verify.success || !verify.data) {
+            const expired = 'expired' in verify && verify.expired;
+            throw new ApiError({
+                code: expired ? 403 : 401,
+                message: verify.error ?? 'Unable to verify refresh token'
+            });
+        }
+        const user = await this.getUserOrThrow(stored.userId ?? verify.data.uid, 'User not found');
+        const metadata = {
+            domain: stored.domain,
+            fingerprint: stored.fingerprint,
+            label: stored.label,
+            clientId: stored.clientId,
+            scope: stored.scope,
+            browser: stored.browser,
+            device: stored.device,
+            ip: stored.ip,
+            os: stored.os,
+            loginType: stored.loginType,
+            refreshTtlSeconds: sessionPrefs.refreshTtlSeconds ?? stored.refreshTtlSeconds,
+            sessionCookie: sessionPrefs.sessionCookie ?? stored.sessionCookie
+        };
+        const pair = await this.issueTokens(apiReq, user, metadata);
+        const publicUser = this.storage.filterUser(user);
+        return [200, { ...pair, user: publicUser }];
+    }
+    async postLogout(apiReq) {
+        const body = (apiReq.req.body ?? {});
+        const refreshToken = this.extractRefreshToken(apiReq, body);
+        if (!refreshToken) {
+            throw new ApiError({ code: 401, message: 'Not logged in' });
+        }
+        this.setJwtCookies(apiReq, { accessToken: null, refreshToken: null });
+        const revoked = await this.storage.deleteToken({ refreshToken });
+        return [200, { revoked }];
+    }
+    async postWhoAmI(apiReq) {
+        const body = (apiReq.req.body ?? {});
+        const refreshToken = this.extractRefreshToken(apiReq, body);
+        if (!refreshToken) {
+            throw new ApiError({ code: 401, message: 'Missing refresh token' });
+        }
+        const stored = await this.storage.getToken({ refreshToken });
+        if (!stored) {
+            throw new ApiError({ code: 401, message: 'Invalid refresh token' });
+        }
+        const verify = this.server.jwtVerify(refreshToken, this.server.config.refreshSecret);
+        if (!verify.success || !verify.data) {
+            const expired = 'expired' in verify && verify.expired;
+            throw new ApiError({
+                code: expired ? 403 : 401,
+                message: verify.error ?? 'Unable to verify refresh token'
+            });
+        }
+        const user = await this.getUserOrThrow(stored.userId ?? verify.data.uid, 'User not found');
+        const conf = this.server.config;
+        const hasAccessToken = typeof apiReq.req.headers.authorization === 'string' ||
+            (typeof apiReq.req.cookies?.[conf.accessCookie] === 'string' &&
+                apiReq.req.cookies[conf.accessCookie].trim().length > 0);
+        const shouldRefresh = Boolean(body.refresh) || !hasAccessToken;
+        if (shouldRefresh) {
+            const access = this.server.jwtSign(this.buildTokenPayload(user, stored), conf.accessSecret, conf.accessExpiry);
+            if (!access.success || !access.token) {
+                throw new ApiError({ code: 500, message: access.error ?? 'Unable to sign access token' });
+            }
+            const cookiePrefs = this.mergeSessionPreferences({
+                sessionCookie: stored.sessionCookie,
+                refreshTtlSeconds: this.normalizeRefreshTtlSeconds(stored.refreshTtlSeconds)
+            });
+            const refreshTtlForCookie = cookiePrefs.sessionCookie
+                ? (cookiePrefs.refreshTtlSeconds ?? this.sessionRefreshTtlSeconds())
+                : cookiePrefs.refreshTtlSeconds;
+            this.setJwtCookies(apiReq, { accessToken: access.token, refreshToken }, { sessionCookie: cookiePrefs.sessionCookie ?? false, refreshTtlSeconds: refreshTtlForCookie });
+        }
+        return [200, this.storage.filterUser(user)];
+    }
+    async postPasskeyChallenge(apiReq) {
+        if (typeof this.storage.createPasskeyChallenge !== 'function') {
+            throw new ApiError({ code: 501, message: 'Passkey support is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        const action = toStringOrNull(body.action);
+        if (action !== 'register' && action !== 'authenticate') {
+            throw new ApiError({ code: 400, message: 'Passkey action must be "register" or "authenticate"' });
+        }
+        const params = {
+            action,
+            login: toStringOrNull(body.login) ?? undefined,
+            userId: isAuthIdentifier(body.userId) ? body.userId : undefined,
+            userAgent: toStringOrNull(body.userAgent) ?? undefined,
+            domain: toStringOrNull(body.domain) ?? undefined,
+            fingerprint: toStringOrNull(body.fingerprint) ?? undefined,
+            label: toStringOrNull(body.label) ?? undefined,
+            browser: toStringOrNull(body.browser) ?? undefined,
+            device: toStringOrNull(body.device) ?? undefined,
+            ip: toStringOrNull(body.ip) ?? undefined,
+            os: toStringOrNull(body.os) ?? undefined
+        };
+        const challenge = await this.storage.createPasskeyChallenge(params);
+        return [200, challenge];
+    }
+    async postPasskeyVerify(apiReq) {
+        if (typeof this.storage.verifyPasskeyResponse !== 'function') {
+            throw new ApiError({ code: 501, message: 'Passkey support is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        const sessionPrefs = this.resolveSessionPreferences(body.keepSession);
+        const expectedChallenge = toStringOrNull(body.expectedChallenge);
+        const response = body.response;
+        if (!expectedChallenge || typeof response !== 'object' || response === null) {
+            throw new ApiError({ code: 400, message: 'Malformed passkey verification payload' });
+        }
+        const params = {
+            expectedChallenge,
+            response: response,
+            login: toStringOrNull(body.login) ?? undefined,
+            userId: isAuthIdentifier(body.userId) ? body.userId : undefined,
+            domain: toStringOrNull(body.domain) ?? undefined,
+            fingerprint: toStringOrNull(body.fingerprint) ?? undefined,
+            label: toStringOrNull(body.label) ?? undefined,
+            browser: toStringOrNull(body.browser) ?? undefined,
+            device: toStringOrNull(body.device) ?? undefined,
+            ip: toStringOrNull(body.ip) ?? undefined,
+            os: toStringOrNull(body.os) ?? undefined,
+            ...sessionPrefs
+        };
+        const result = await this.storage.verifyPasskeyResponse(params);
+        if (!result.verified) {
+            throw new ApiError({ code: 401, message: 'Passkey verification failed' });
+        }
+        const user = await this.getUserFromPasskey(result, params);
+        if (result.tokens?.accessToken && result.tokens.refreshToken) {
+            const storagePrefs = this.sessionPrefsFromRecord(result);
+            const cookiePrefs = this.mergeSessionPreferences(sessionPrefs, storagePrefs);
+            const refreshTtlForCookie = cookiePrefs.sessionCookie
+                ? (cookiePrefs.refreshTtlSeconds ?? this.sessionRefreshTtlSeconds())
+                : cookiePrefs.refreshTtlSeconds;
+            this.setJwtCookies(apiReq, { accessToken: result.tokens.accessToken, refreshToken: result.tokens.refreshToken }, { sessionCookie: cookiePrefs.sessionCookie ?? false, refreshTtlSeconds: refreshTtlForCookie });
+            const publicUser = this.storage.filterUser(user);
+            return [200, { ...result.tokens, user: publicUser }];
+        }
+        const extras = result;
+        const extrasPrefs = this.sessionPrefsFromRecord(extras);
+        const metadataPrefs = this.mergeSessionPreferences(sessionPrefs, extrasPrefs);
+        const metadata = {
+            domain: toStringOrNull(extras.domain) ?? params.domain,
+            fingerprint: toStringOrNull(extras.fingerprint) ?? params.fingerprint,
+            label: toStringOrNull(extras.label) ?? params.label,
+            browser: toStringOrNull(extras.browser) ?? params.browser,
+            device: toStringOrNull(extras.device) ?? params.device,
+            ip: toStringOrNull(extras.ip) ?? params.ip,
+            os: toStringOrNull(extras.os) ?? params.os,
+            loginType: 'passkey',
+            ...metadataPrefs
+        };
+        const tokens = await this.issueTokens(apiReq, user, metadata);
+        const publicUser = this.storage.filterUser(user);
+        return [200, { ...tokens, user: publicUser }];
+    }
+    async postImpersonation(apiReq) {
+        this.assertAuthReady();
+        const { targetIdentifier, metadata } = this.parseImpersonationRequest(apiReq);
+        const actor = await this.resolveActorContext(apiReq);
+        const targetUser = await this.getUserOrThrow(targetIdentifier, 'Target user not found');
+        await this.ensureImpersonationAllowed(apiReq, actor.user, targetUser);
+        const impersonationMetadata = {
+            ...metadata,
+            ruid: String(actor.userId),
+            loginType: metadata.loginType ?? 'impersonation'
+        };
+        const tokens = await this.issueTokens(apiReq, targetUser, impersonationMetadata);
+        const publicUser = this.storage.filterUser(targetUser);
+        return [200, { ...tokens, user: publicUser }];
+    }
+    async deleteImpersonation(apiReq) {
+        this.assertAuthReady();
+        const actor = await this.resolveActorContext(apiReq);
+        const metadata = this.buildImpersonationMetadata((apiReq.req.body ?? {}));
+        metadata.loginType = metadata.loginType ?? 'impersonation-end';
+        const tokens = await this.issueTokens(apiReq, actor.user, metadata);
+        const publicUser = this.storage.filterUser(actor.user);
+        return [200, { ...tokens, user: publicUser }];
+    }
+    async getUserFromPasskey(result, params) {
+        if (result.userId !== undefined) {
+            return this.getUserOrThrow(result.userId, 'User not found for passkey verification');
+        }
+        if (result.login) {
+            return this.getUserOrThrow(result.login, 'User not found for passkey verification');
+        }
+        if (params.userId !== undefined) {
+            return this.getUserOrThrow(params.userId, 'User not found for passkey verification');
+        }
+        if (params.login) {
+            return this.getUserOrThrow(params.login, 'User not found for passkey verification');
+        }
+        throw new ApiError({ code: 500, message: 'Passkey response missing user reference' });
+    }
+    async postOAuthStart(apiReq) {
+        if (typeof this.server.initiateOAuth !== 'function') {
+            throw new ApiError({ code: 501, message: 'External OAuth support is not configured' });
+        }
+        const params = {
+            provider: apiReq.req.params?.provider,
+            redirectUri: toStringOrNull(apiReq.req.body?.redirectUri) ?? undefined,
+            scope: this.normalizeScope(apiReq.req.body?.scope),
+            state: toStringOrNull(apiReq.req.body?.state) ?? undefined,
+            extras: typeof apiReq.req.body?.extras === 'object'
+                ? apiReq.req.body.extras
+                : undefined
+        };
+        if (!params.provider) {
+            throw new ApiError({ code: 400, message: 'OAuth provider is required' });
+        }
+        const result = await this.server.initiateOAuth(params);
+        return [200, result];
+    }
+    async postOAuthCallback(apiReq) {
+        if (typeof this.server.completeOAuth !== 'function') {
+            throw new ApiError({ code: 501, message: 'External OAuth support is not configured' });
+        }
+        const params = {
+            provider: apiReq.req.params?.provider,
+            query: apiReq.req.query,
+            body: (apiReq.req.body ?? {})
+        };
+        if (!params.provider) {
+            throw new ApiError({ code: 400, message: 'OAuth provider is required' });
+        }
+        const result = await this.server.completeOAuth(params);
+        if (result.tokens?.accessToken && result.tokens.refreshToken) {
+            this.setJwtCookies(apiReq, {
+                accessToken: result.tokens.accessToken,
+                refreshToken: result.tokens.refreshToken
+            });
+        }
+        return [200, result];
+    }
+    async postOAuthAuthorize(apiReq) {
+        if (typeof this.storage.getClient !== 'function' || typeof this.storage.createAuthCode !== 'function') {
+            throw new ApiError({ code: 501, message: 'OAuth authorization storage is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        const clientId = toStringOrNull(body.clientId);
+        const redirectUri = toStringOrNull(body.redirectUri);
+        const scope = toScopeArray(body.scope) ?? [];
+        const state = toStringOrNull(body.state) ?? undefined;
+        const codeChallenge = toStringOrNull(body.codeChallenge) ?? undefined;
+        const codeChallengeMethod = toStringOrNull(body.codeChallengeMethod) ?? undefined;
+        if (!clientId) {
+            throw new ApiError({ code: 400, message: 'clientId is required' });
+        }
+        if (!redirectUri) {
+            throw new ApiError({ code: 400, message: 'redirectUri is required' });
+        }
+        const client = await this.storage.getClient(clientId);
+        if (!client) {
+            throw new ApiError({ code: 400, message: 'Unknown client_id' });
+        }
+        this.assertRedirectUriAllowed(client, redirectUri);
+        const resolvedScope = this.resolveScope(client, scope);
+        const user = await this.resolveUserForOAuth(apiReq, body);
+        const codeRecord = await this.storage.createAuthCode({
+            clientId,
+            userId: this.storage.getUserId(user),
+            redirectUri,
+            scope: resolvedScope,
+            codeChallenge,
+            codeChallengeMethod: codeChallengeMethod === 'S256' ? 'S256' : codeChallengeMethod === 'plain' ? 'plain' : undefined,
+            expiresInSeconds: 300
+        });
+        const redirect = new URL(redirectUri);
+        redirect.searchParams.set('code', codeRecord.code);
+        if (state) {
+            redirect.searchParams.set('state', state);
+        }
+        return [200, { code: codeRecord.code, redirectUri: redirect.toString(), state }];
+    }
+    async postOAuthToken(apiReq) {
+        if (typeof this.storage.getClient !== 'function' || typeof this.storage.consumeAuthCode !== 'function') {
+            throw new ApiError({ code: 501, message: 'OAuth token storage is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        const grantType = toStringOrNull(body.grant_type);
+        if (!grantType) {
+            throw new ApiError({ code: 400, message: 'grant_type is required' });
+        }
+        const { client, clientSecretProvided } = await this.resolveClientAuthentication(apiReq, body);
+        switch (grantType) {
+            case 'authorization_code':
+                return this.handleAuthorizationCodeGrant(apiReq, body, client, clientSecretProvided);
+            case 'refresh_token':
+                return this.handleRefreshTokenGrant(apiReq, body, client);
+            default:
+                throw new ApiError({ code: 400, message: `Unsupported grant_type: ${grantType}` });
+        }
+    }
+    async handleAuthorizationCodeGrant(apiReq, body, client, clientSecretProvided) {
+        const code = toStringOrNull(body.code);
+        const redirectUri = toStringOrNull(body.redirect_uri);
+        const codeVerifier = toStringOrNull(body.code_verifier);
+        const consumeAuthCode = this.storage.consumeAuthCode?.bind(this.storage);
+        if (!consumeAuthCode) {
+            throw new ApiError({ code: 501, message: 'OAuth token storage is not configured' });
+        }
+        if (!code) {
+            throw new ApiError({ code: 400, message: 'code is required for authorization_code grant' });
+        }
+        if (!redirectUri) {
+            throw new ApiError({ code: 400, message: 'redirect_uri is required for authorization_code grant' });
+        }
+        this.assertRedirectUriAllowed(client, redirectUri);
+        const record = await consumeAuthCode(code, client.clientId);
+        if (!record) {
+            throw new ApiError({ code: 400, message: 'Invalid or expired authorization code' });
+        }
+        if (record.expiresAt.getTime() < Date.now()) {
+            throw new ApiError({ code: 400, message: 'Authorization code expired' });
+        }
+        if (record.redirectUri !== redirectUri) {
+            throw new ApiError({ code: 400, message: 'redirect_uri mismatch' });
+        }
+        if (record.codeChallenge) {
+            if (!codeVerifier) {
+                throw new ApiError({ code: 400, message: 'code_verifier is required for this authorization code' });
+            }
+            if (record.codeChallengeMethod === 'S256') {
+                if (sha256Base64Url(codeVerifier) !== record.codeChallenge) {
+                    throw new ApiError({ code: 400, message: 'code_verifier does not match challenge' });
+                }
+            }
+            else if (record.codeChallengeMethod === 'plain') {
+                if (codeVerifier !== record.codeChallenge) {
+                    throw new ApiError({ code: 400, message: 'code_verifier does not match challenge' });
+                }
+            }
+        }
+        else if (!clientSecretProvided && client.clientSecret) {
+            throw new ApiError({ code: 400, message: 'Client authentication required when no PKCE challenge present' });
+        }
+        const user = await this.getUserOrThrow(record.userId, 'User not found');
+        const resolvedScope = Array.isArray(record.scope) ? record.scope : [];
+        const tokens = await this.issueTokens(apiReq, user, {
+            clientId: client.clientId,
+            scope: resolvedScope,
+            label: resolvedScope.join(' '),
+            loginType: 'oauth'
+        });
+        this.clearOAuthCookies(apiReq);
+        return [200, this.buildTokenResponse(tokens, client, resolvedScope)];
+    }
+    async handleRefreshTokenGrant(apiReq, body, client) {
+        const refreshToken = toStringOrNull(body.refresh_token);
+        if (!refreshToken) {
+            throw new ApiError({ code: 400, message: 'refresh_token is required for refresh_token grant' });
+        }
+        const stored = await this.storage.getToken({ refreshToken, clientId: client.clientId });
+        if (!stored) {
+            throw new ApiError({ code: 400, message: 'Invalid refresh_token' });
+        }
+        const verify = this.server.jwtVerify(refreshToken, this.server.config.refreshSecret);
+        if (!verify.success || !verify.data) {
+            const expired = 'expired' in verify && verify.expired;
+            throw new ApiError({
+                code: expired ? 403 : 401,
+                message: verify.error ?? 'Unable to verify refresh token'
+            });
+        }
+        if (stored.clientId && stored.clientId !== client.clientId) {
+            throw new ApiError({ code: 400, message: 'Refresh token issued to another client' });
+        }
+        const user = await this.getUserOrThrow(stored.userId ?? verify.data.uid, 'User not found');
+        const tokens = await this.issueTokens(apiReq, user, {
+            clientId: client.clientId,
+            scope: stored.scope,
+            label: Array.isArray(stored.scope) ? stored.scope.join(' ') : stored.label,
+            fingerprint: stored.fingerprint,
+            loginType: stored.loginType ?? 'oauth'
+        });
+        this.clearOAuthCookies(apiReq);
+        const scope = Array.isArray(stored.scope)
+            ? stored.scope
+            : typeof stored.scope === 'string'
+                ? stored.scope.split(/\s+/).filter((entry) => entry.length > 0)
+                : [];
+        return [200, this.buildTokenResponse(tokens, client, scope)];
+    }
+    clearOAuthCookies(apiReq) {
+        this.setJwtCookies(apiReq, { accessToken: null, refreshToken: null });
+    }
+    buildTokenResponse(tokens, client, scope) {
+        const conf = this.server.config;
+        return {
+            access_token: tokens.accessToken,
+            refresh_token: tokens.refreshToken,
+            token_type: 'Bearer',
+            expires_in: conf.accessExpiry,
+            scope: scope.join(' '),
+            client_id: client.clientId
+        };
+    }
+    resolveScope(client, requested) {
+        const allowed = Array.isArray(client.scope) ? client.scope : [];
+        if (allowed.length === 0) {
+            return requested.length > 0 ? requested : [];
+        }
+        if (requested.length === 0) {
+            return allowed;
+        }
+        const filtered = requested.filter((entry) => allowed.includes(entry));
+        if (filtered.length === 0) {
+            throw new ApiError({ code: 400, message: 'Requested scope is not permitted for this client' });
+        }
+        return filtered;
+    }
+    async resolveClientAuthentication(apiReq, body) {
+        if (typeof this.storage.getClient !== 'function') {
+            throw new ApiError({ code: 501, message: 'OAuth client storage is not configured' });
+        }
+        let clientId = null;
+        let clientSecret = null;
+        let secretProvided = false;
+        const header = apiReq.req.headers.authorization;
+        if (typeof header === 'string' && header.startsWith('Basic ')) {
+            const decoded = Buffer.from(header.slice(6), 'base64').toString('utf8');
+            const idx = decoded.indexOf(':');
+            if (idx === -1) {
+                throw new ApiError({ code: 400, message: 'Invalid basic authorization header' });
+            }
+            clientId = decoded.slice(0, idx);
+            clientSecret = decoded.slice(idx + 1);
+            secretProvided = true;
+        }
+        if (!clientId) {
+            clientId = toStringOrNull(body.client_id);
+        }
+        if (clientSecret === null && typeof body.client_secret === 'string') {
+            clientSecret = body.client_secret;
+            secretProvided = true;
+        }
+        if (!clientId) {
+            throw new ApiError({ code: 400, message: 'client_id is required' });
+        }
+        const client = await this.storage.getClient(clientId);
+        if (!client) {
+            throw new ApiError({ code: 400, message: 'Unknown client_id' });
+        }
+        const requiresSecret = !!client.clientSecret;
+        if (requiresSecret) {
+            if (!secretProvided) {
+                throw new ApiError({ code: 400, message: 'Client authentication is required' });
+            }
+            let valid = false;
+            if (this.storage.verifyClientSecret) {
+                const verifySecret = this.storage.verifyClientSecret.bind(this.storage);
+                valid = await verifySecret(client, clientSecret);
+            }
+            else {
+                valid = client.clientSecret === clientSecret;
+            }
+            if (!valid) {
+                throw new ApiError({ code: 401, message: 'Invalid client credentials' });
+            }
+        }
+        return { client, clientSecretProvided: secretProvided };
+    }
+    assertRedirectUriAllowed(client, redirectUri) {
+        if (client.redirectUris.length === 0) {
+            return;
+        }
+        if (!client.redirectUris.includes(redirectUri)) {
+            throw new ApiError({ code: 400, message: 'redirect_uri not registered for client' });
+        }
+    }
+    async resolveUserForOAuth(apiReq, body) {
+        const refreshToken = this.extractRefreshToken(apiReq, body);
+        if (refreshToken) {
+            const stored = await this.storage.getToken({ refreshToken });
+            if (stored) {
+                return this.getUserOrThrow(stored.userId, 'User not found for authorization');
+            }
+        }
+        const login = toStringOrNull(body.login);
+        const password = toStringOrNull(body.password);
+        if (login && password) {
+            const user = await this.storage.getUser(login);
+            if (!user) {
+                throw new ApiError({ code: 400, message: 'Invalid credentials', errors: { login: 'Unknown user' } });
+            }
+            const hash = this.storage.getUserPasswordHash(user);
+            const verified = await this.storage.verifyPassword(password, hash);
+            if (!verified) {
+                throw new ApiError({
+                    code: 400,
+                    message: 'Invalid credentials',
+                    errors: { password: 'Wrong password' }
+                });
+            }
+            return user;
+        }
+        throw new ApiError({ code: 401, message: 'Authorization requires user authentication' });
+    }
+    defineRoutes() {
+        const routes = [
+            {
+                method: 'post',
+                path: '/v1/login',
+                handler: (req) => this.postLogin(req),
+                auth: { type: 'none', req: 'any' }
+            },
+            {
+                method: 'post',
+                path: '/v1/refresh',
+                handler: (req) => this.postRefresh(req),
+                auth: { type: 'none', req: 'any' }
+            },
+            {
+                method: 'post',
+                path: '/v1/logout',
+                handler: (req) => this.postLogout(req),
+                auth: { type: 'maybe', req: 'any' }
+            },
+            {
+                method: 'post',
+                path: '/v1/whoami',
+                handler: (req) => this.postWhoAmI(req),
+                auth: { type: 'maybe', req: 'any' }
+            },
+            {
+                method: 'post',
+                path: '/v1/impersonations',
+                handler: (req) => this.postImpersonation(req),
+                auth: { type: 'strict', req: 'any' }
+            },
+            {
+                method: 'delete',
+                path: '/v1/impersonations',
+                handler: (req) => this.deleteImpersonation(req),
+                auth: { type: 'strict', req: 'any' }
+            }
+        ];
+        const storage = this.storage;
+        const passkeysSupported = typeof storage.createPasskeyChallenge === 'function' && typeof storage.verifyPasskeyResponse === 'function';
+        if (passkeysSupported) {
+            routes.push({
+                method: 'post',
+                path: '/v1/passkeys/challenge',
+                handler: (req) => this.postPasskeyChallenge(req),
+                auth: { type: 'none', req: 'any' }
+            }, {
+                method: 'post',
+                path: '/v1/passkeys/verify',
+                handler: (req) => this.postPasskeyVerify(req),
+                auth: { type: 'none', req: 'any' }
+            });
+        }
+        const externalOAuthSupported = typeof this.server.initiateOAuth === 'function' && typeof this.server.completeOAuth === 'function';
+        if (externalOAuthSupported) {
+            routes.push({
+                method: 'post',
+                path: '/v1/oauth2/:provider/start',
+                handler: (req) => this.postOAuthStart(req),
+                auth: { type: 'none', req: 'any' }
+            }, {
+                method: 'post',
+                path: '/v1/oauth2/:provider/callback',
+                handler: (req) => this.postOAuthCallback(req),
+                auth: { type: 'none', req: 'any' }
+            });
+        }
+        const oauthStorageSupported = typeof storage.getClient === 'function' &&
+            typeof storage.createAuthCode === 'function' &&
+            typeof storage.consumeAuthCode === 'function';
+        if (oauthStorageSupported) {
+            routes.push({
+                method: 'post',
+                path: '/v1/oauth2/authorize',
+                handler: (req) => this.postOAuthAuthorize(req),
+                auth: { type: 'maybe', req: 'any' }
+            }, {
+                method: 'post',
+                path: '/v1/oauth2/token',
+                handler: (req) => this.postOAuthToken(req),
+                auth: { type: 'none', req: 'any' }
+            });
+        }
+        return routes;
+    }
+}
+AuthModule.defaultNamespace = '/auth';
+export default AuthModule;