@technomoron/apicore-server 1.0.0-beta.1

package/dist/cjs/auth-api/auth-module.cjs

@@ -0,0 +1,1248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_crypto_1 = require("node:crypto");
+const helpers_1 = require("@simplewebauthn/server/helpers");
+const apicore_server_js_1 = require("../apicore-server.cjs");
+const auth_cookie_options_js_1 = require("../auth-cookie-options.cjs");
+const module_js_1 = require("./module.cjs");
+const schemas_js_1 = require("./schemas.cjs");
+const storage_js_1 = require("./storage.cjs");
+function isAuthIdentifier(value) {
+    if (typeof value === 'string')
+        return value.length > 0;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    return false;
+}
+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 = (0, node_crypto_1.createHash)('sha256').update(value).digest();
+    return base64UrlEncode(hash);
+}
+class AuthModule extends module_js_1.BaseAuthModule {
+    get server() {
+        return super.server;
+    }
+    set server(value) {
+        super.server = value;
+    }
+    constructor(options = {}) {
+        super({ namespace: options.namespace ?? AuthModule.defaultNamespace });
+        this.defaultDomain = options.defaultDomain;
+        this.canImpersonateHook = options.canImpersonate;
+        this.rateLimitHook = options.rateLimit;
+        this.allowInsecurePkcePlain = options.allowInsecurePkcePlain ?? false;
+    }
+    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 === true)
+                return true;
+            if (allowed === false)
+                return false;
+        }
+        const storageWithHook = this.storage;
+        if (typeof storageWithHook.canImpersonate === 'function') {
+            const allowed = await storageWithHook.canImpersonate({ realUserId, effectiveUserId });
+            return !!allowed;
+        }
+        return String(realUserId) === String(effectiveUserId);
+    }
+    async ensureImpersonationAllowed(apiReq, realUser, targetUser) {
+        const permitted = await this.canImpersonate(apiReq, realUser, targetUser);
+        if (!permitted) {
+            throw new apicore_server_js_1.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;
+        const domain = metadata.domain ?? this.defaultDomain ?? '';
+        let fingerprint = metadata.fingerprint ?? metadata.clientId ?? '';
+        if (typeof fingerprint === 'string') {
+            fingerprint = fingerprint.trim();
+        }
+        else {
+            fingerprint = '';
+        }
+        // Avoid every client sharing the empty-string fingerprint which collapses sessions into one bucket.
+        if (!fingerprint) {
+            fingerprint = `srv-${(0, node_crypto_1.randomUUID)()}`;
+        }
+        return {
+            domain,
+            fingerprint,
+            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') {
+            if (candidate === 0) {
+                return { sessionCookie: true, refreshTtlSeconds: this.sessionRefreshTtlSeconds() };
+            }
+            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;
+    }
+    validateCredentialId(apiReq) {
+        const paramId = toStringOrNull(apiReq.req.params?.credentialId);
+        const bodyId = toStringOrNull(apiReq.req.body?.credentialId);
+        const credentialId = paramId ?? bodyId;
+        if (!credentialId) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'credentialId is required' });
+        }
+        try {
+            helpers_1.isoBase64URL.toBuffer(credentialId);
+        }
+        catch {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'Invalid credentialId' });
+        }
+        return credentialId;
+    }
+    normalizeCredentialId(value) {
+        if (Buffer.isBuffer(value)) {
+            return value;
+        }
+        try {
+            return Buffer.from(helpers_1.isoBase64URL.toBuffer(value));
+        }
+        catch {
+            try {
+                return Buffer.from(value, 'base64');
+            }
+            catch {
+                return Buffer.from(value);
+            }
+        }
+    }
+    toIsoDate(value) {
+        if (!value) {
+            return undefined;
+        }
+        const date = value instanceof Date ? value : new Date(value);
+        return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+    }
+    cookieOptions(apiReq) {
+        return (0, auth_cookie_options_js_1.buildAuthCookieOptions)(this.server.config, apiReq.req);
+    }
+    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;
+        // When sessionCookie is true we omit maxAge so the browser deletes the
+        // cookie on close.  The server-side JWT still has its own expiry, which
+        // limits exposure if the browser crashes without running its cleanup.
+        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),
+            jti: (0, node_crypto_1.randomUUID)()
+        };
+        const access = this.server.jwtSign(payload, conf.accessSecret, conf.accessExpiry);
+        if (!access.success || !access.token) {
+            throw new apicore_server_js_1.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 apicore_server_js_1.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 apicore_server_js_1.ApiError({ code: 500, message: 'Auth secrets are not configured' });
+        }
+    }
+    parseLoginBody(apiReq) {
+        const body = (apiReq.req.body ?? {});
+        // login and password are guaranteed present and non-empty by JSON Schema
+        const login = body.login;
+        const password = body.password;
+        const sessionPrefs = this.resolveSessionPreferences(body.keepSession);
+        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 apicore_server_js_1.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 apicore_server_js_1.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 apicore_server_js_1.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) {
+        await this.applyRateLimit(apiReq, 'login');
+        this.assertAuthReady();
+        const { login, password, ...metadata } = this.parseLoginBody(apiReq);
+        const user = await this.storage.getUser(login);
+        const hash = user ? this.storage.getUserPasswordHash(user) : '';
+        // Reject users with no password hash (e.g. OAuth/passkey-only accounts) before
+        // calling verifyPassword, since bcrypt behaviour on an empty hash is undefined.
+        const verified = user && hash ? await this.storage.verifyPassword(password, hash) : false;
+        if (!user || !verified) {
+            throw new apicore_server_js_1.ApiError({
+                code: 400,
+                message: 'Invalid credentials'
+            });
+        }
+        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 apicore_server_js_1.ApiError({ code: 401, message: 'Missing refresh token' });
+        }
+        const stored = await this.storage.getToken({ refreshToken: providedToken });
+        if (!stored) {
+            throw new apicore_server_js_1.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 apicore_server_js_1.ApiError({
+                code: expired ? 403 : 401,
+                message: verify.error ?? 'Unable to verify refresh token'
+            });
+        }
+        // Delete the token immediately after verification to narrow the TOCTOU window.
+        // This must happen before the slower getUserOrThrow call.
+        const deleted = await this.storage.deleteToken({ refreshToken: providedToken });
+        if (deleted === 0) {
+            // Another concurrent request already consumed this refresh token.
+            throw new apicore_server_js_1.ApiError({ code: 401, message: 'Invalid 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 apicore_server_js_1.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 apicore_server_js_1.ApiError({ code: 401, message: 'Missing refresh token' });
+        }
+        const stored = await this.storage.getToken({ refreshToken });
+        if (!stored) {
+            throw new apicore_server_js_1.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 apicore_server_js_1.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) {
+            if (typeof this.storage.updateToken !== 'function' || !this.storageImplements('updateToken')) {
+                throw new apicore_server_js_1.ApiError({ code: 501, message: 'Token update storage is not configured' });
+            }
+            // Sign a new access token without embedding stored token secrets into the JWT payload.
+            const metadata = {
+                ruid: stored.ruid,
+                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: this.normalizeRefreshTtlSeconds(stored.refreshTtlSeconds),
+                sessionCookie: stored.sessionCookie
+            };
+            const enrichedMetadata = this.enrichTokenMetadata(apiReq, metadata);
+            const access = this.server.jwtSign(this.buildTokenPayload(user, enrichedMetadata), conf.accessSecret, conf.accessExpiry);
+            if (!access.success || !access.token) {
+                throw new apicore_server_js_1.ApiError({ code: 500, message: access.error ?? 'Unable to sign access token' });
+            }
+            const updated = await this.storage.updateToken({
+                refreshToken,
+                accessToken: access.token,
+                lastSeenAt: new Date()
+            });
+            if (!updated) {
+                throw new apicore_server_js_1.ApiError({ code: 500, message: 'Unable to persist refreshed 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 });
+        }
+        const tokenClaims = verify.data;
+        const effectiveUserId = this.storage.getUserId(user);
+        const effectiveId = String(effectiveUserId);
+        const rawRealId = stored.ruid ?? tokenClaims.ruid;
+        const normalizedRealId = rawRealId === undefined || rawRealId === null ? null : String(rawRealId).trim() || null;
+        const isImpersonating = normalizedRealId !== null && normalizedRealId !== effectiveId;
+        let realUser;
+        let realUserId;
+        if (isImpersonating && normalizedRealId !== null) {
+            const realUserEntity = await this.getUserOrThrow(normalizedRealId, 'Real user not found');
+            realUser = this.storage.filterUser(realUserEntity);
+            realUserId = this.storage.getUserId(realUserEntity);
+        }
+        return [
+            200,
+            {
+                user: this.storage.filterUser(user),
+                isImpersonating,
+                realUser,
+                realUserId
+            }
+        ];
+    }
+    async postPasskeyChallenge(apiReq) {
+        await this.applyRateLimit(apiReq, 'passkey-challenge');
+        if (typeof this.storage.createPasskeyChallenge !== 'function') {
+            throw new apicore_server_js_1.ApiError({ code: 501, message: 'Passkey support is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        // action is guaranteed to be 'register' | 'authenticate' by JSON Schema
+        const action = body.action;
+        const params = {
+            action: action,
+            login: toStringOrNull(body.login) ?? undefined,
+            userId: isAuthIdentifier(body.userId) ? body.userId : undefined
+        };
+        const challenge = await this.storage.createPasskeyChallenge(params);
+        return [200, challenge];
+    }
+    async postPasskeyVerify(apiReq) {
+        if (typeof this.storage.verifyPasskeyResponse !== 'function') {
+            throw new apicore_server_js_1.ApiError({ code: 501, message: 'Passkey support is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        const sessionPrefs = this.resolveSessionPreferences(body.keepSession);
+        // expectedChallenge (string) and response (object) are guaranteed by JSON Schema
+        const expectedChallenge = body.expectedChallenge;
+        const response = body.response;
+        const rawMetadata = {
+            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 clientInfo = apiReq.getClientInfo();
+        const userAgent = toStringOrNull(body.userAgent) ?? (clientInfo.ua ? clientInfo.ua : null);
+        const requestMetadata = this.enrichTokenMetadata(apiReq, rawMetadata);
+        const params = {
+            expectedChallenge,
+            response: response,
+            login: toStringOrNull(body.login) ?? undefined,
+            userId: isAuthIdentifier(body.userId) ? body.userId : undefined,
+            userAgent: userAgent ?? undefined,
+            ...requestMetadata,
+            ...sessionPrefs
+        };
+        const result = await this.storage.verifyPasskeyResponse(params);
+        if (!result.verified) {
+            throw new apicore_server_js_1.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 getPasskeys(apiReq) {
+        if (typeof this.storage.listUserCredentials !== 'function') {
+            throw new apicore_server_js_1.ApiError({ code: 501, message: 'Passkey credential listing is not configured' });
+        }
+        const { userId } = await this.resolveActorContext(apiReq);
+        const credentials = await this.storage.listUserCredentials(userId);
+        const safeCredentials = credentials.map((credential) => {
+            const bufferId = this.normalizeCredentialId(credential.credentialId);
+            return {
+                id: helpers_1.isoBase64URL.fromBuffer(new Uint8Array(bufferId)),
+                transports: credential.transports,
+                backedUp: credential.backedUp,
+                deviceType: credential.deviceType,
+                createdAt: this.toIsoDate(credential.createdAt),
+                updatedAt: this.toIsoDate(credential.updatedAt)
+            };
+        });
+        return [200, { credentials: safeCredentials }];
+    }
+    async deletePasskey(apiReq) {
+        if (typeof this.storage.listUserCredentials !== 'function' ||
+            typeof this.storage.deletePasskeyCredential !== 'function') {
+            throw new apicore_server_js_1.ApiError({ code: 501, message: 'Passkey credential management is not configured' });
+        }
+        const { userId } = await this.resolveActorContext(apiReq);
+        const credentialId = this.validateCredentialId(apiReq);
+        const bufferId = Buffer.from(helpers_1.isoBase64URL.toBuffer(credentialId));
+        const credentials = await this.storage.listUserCredentials(userId);
+        const owns = credentials.some((credential) => {
+            const candidateId = this.normalizeCredentialId(credential.credentialId);
+            return helpers_1.isoBase64URL.fromBuffer(new Uint8Array(candidateId)) === credentialId;
+        });
+        if (!owns) {
+            throw new apicore_server_js_1.ApiError({ code: 404, message: 'Passkey not found' });
+        }
+        const deleted = await this.storage.deletePasskeyCredential(bufferId);
+        return [200, { deleted }];
+    }
+    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();
+        if (!apiReq.isImpersonating()) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'Not currently impersonating' });
+        }
+        // Revoke the active impersonation refresh token before issuing new real-user tokens
+        // so that a captured impersonation token cannot be reused after impersonation ends.
+        const impersonationRefreshToken = this.extractRefreshToken(apiReq, {});
+        if (impersonationRefreshToken) {
+            await this.storage.deleteToken({ refreshToken: impersonationRefreshToken });
+        }
+        const actor = await this.resolveActorContext(apiReq);
+        const query = (apiReq.req.query ?? {});
+        const metadata = this.buildImpersonationMetadata(query);
+        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 apicore_server_js_1.ApiError({ code: 500, message: 'Passkey response missing user reference' });
+    }
+    async postOAuthStart(apiReq) {
+        if (typeof this.server.initiateOAuth !== 'function') {
+            throw new apicore_server_js_1.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
+        };
+        // provider is guaranteed present and non-empty by params schema
+        const result = await this.server.initiateOAuth(params);
+        return [200, result];
+    }
+    async postOAuthCallback(apiReq) {
+        if (typeof this.server.completeOAuth !== 'function') {
+            throw new apicore_server_js_1.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 ?? {})
+        };
+        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 apicore_server_js_1.ApiError({ code: 501, message: 'OAuth authorization storage is not configured' });
+        }
+        await this.applyRateLimit(apiReq, 'oauth-authorize');
+        const body = (apiReq.req.body ?? {});
+        // clientId and redirectUri are guaranteed present and non-empty by JSON Schema
+        const clientId = body.clientId;
+        const redirectUri = 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;
+        const resolvedCodeChallengeMethod = this.resolvePkceChallengeMethod(codeChallengeMethod);
+        const client = await this.storage.getClient(clientId);
+        if (!client) {
+            throw new apicore_server_js_1.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: resolvedCodeChallengeMethod,
+            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) {
+        await this.applyRateLimit(apiReq, 'oauth-token');
+        if (typeof this.storage.getClient !== 'function' || typeof this.storage.consumeAuthCode !== 'function') {
+            throw new apicore_server_js_1.ApiError({ code: 501, message: 'OAuth token storage is not configured' });
+        }
+        const body = (apiReq.req.body ?? {});
+        // grant_type is guaranteed to be 'authorization_code' | 'refresh_token' by JSON Schema
+        const grantType = body.grant_type;
+        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 apicore_server_js_1.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 apicore_server_js_1.ApiError({ code: 501, message: 'OAuth token storage is not configured' });
+        }
+        if (!code) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'code is required for authorization_code grant' });
+        }
+        if (!redirectUri) {
+            throw new apicore_server_js_1.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 apicore_server_js_1.ApiError({ code: 400, message: 'Invalid or expired authorization code' });
+        }
+        if (record.expiresAt.getTime() < Date.now()) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'Authorization code expired' });
+        }
+        if (record.redirectUri !== redirectUri) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'redirect_uri mismatch' });
+        }
+        if (record.codeChallenge) {
+            if (!codeVerifier) {
+                throw new apicore_server_js_1.ApiError({ code: 400, message: 'code_verifier is required for this authorization code' });
+            }
+            if (record.codeChallengeMethod === 'S256') {
+                if (sha256Base64Url(codeVerifier) !== record.codeChallenge) {
+                    throw new apicore_server_js_1.ApiError({ code: 400, message: 'code_verifier does not match challenge' });
+                }
+            }
+            else if (record.codeChallengeMethod === 'plain') {
+                if (!this.allowInsecurePkcePlain) {
+                    throw new apicore_server_js_1.ApiError({ code: 400, message: 'PKCE plain is not permitted' });
+                }
+                if (codeVerifier !== record.codeChallenge) {
+                    throw new apicore_server_js_1.ApiError({ code: 400, message: 'code_verifier does not match challenge' });
+                }
+            }
+        }
+        else if (!clientSecretProvided && (client.hasSecret ?? false)) {
+            throw new apicore_server_js_1.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 apicore_server_js_1.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 apicore_server_js_1.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 apicore_server_js_1.ApiError({
+                code: expired ? 403 : 401,
+                message: verify.error ?? 'Unable to verify refresh token'
+            });
+        }
+        if (stored.clientId && stored.clientId !== client.clientId) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'Refresh token issued to another client' });
+        }
+        // Delete the token immediately after verification to narrow the TOCTOU window.
+        const deleted = await this.storage.deleteToken({ refreshToken });
+        if (deleted === 0) {
+            throw new apicore_server_js_1.ApiError({ code: 401, message: 'Invalid refresh token' });
+        }
+        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 : [];
+        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 apicore_server_js_1.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 apicore_server_js_1.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 apicore_server_js_1.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 apicore_server_js_1.ApiError({ code: 400, message: 'client_id is required' });
+        }
+        const client = await this.storage.getClient(clientId);
+        if (!client) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'Unknown client_id' });
+        }
+        const requiresSecret = client.hasSecret ?? false;
+        if (requiresSecret) {
+            if (!secretProvided) {
+                throw new apicore_server_js_1.ApiError({ code: 400, message: 'Client authentication is required' });
+            }
+            const verifySecret = this.storage.verifyClientSecret;
+            if (typeof verifySecret !== 'function' || !this.storageImplements('verifyClientSecret')) {
+                throw new apicore_server_js_1.ApiError({ code: 501, message: 'OAuth client secret verification is not configured' });
+            }
+            const valid = await verifySecret.call(this.storage, client, clientSecret);
+            if (!valid) {
+                throw new apicore_server_js_1.ApiError({ code: 401, message: 'Invalid client credentials' });
+            }
+        }
+        return { client, clientSecretProvided: secretProvided };
+    }
+    assertRedirectUriAllowed(client, redirectUri) {
+        if (client.redirectUris.length === 0) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'Client has no registered redirect URIs' });
+        }
+        if (!client.redirectUris.includes(redirectUri)) {
+            throw new apicore_server_js_1.ApiError({ code: 400, message: 'redirect_uri not registered for client' });
+        }
+    }
+    async resolveUserForOAuth(apiReq, body) {
+        const refreshToken = this.extractRefreshToken(apiReq, body);
+        if (refreshToken) {
+            const verify = this.server.jwtVerify(refreshToken, this.server.config.refreshSecret);
+            if (!verify.success || !verify.data) {
+                throw new apicore_server_js_1.ApiError({ code: 401, message: 'Invalid or expired refresh token' });
+            }
+            const stored = await this.storage.getToken({ refreshToken });
+            if (stored) {
+                return this.getUserOrThrow(stored.userId ?? verify.data.uid, '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);
+            const hash = user ? this.storage.getUserPasswordHash(user) : '';
+            const verified = user && hash ? await this.storage.verifyPassword(password, hash) : false;
+            if (!user || !verified) {
+                throw new apicore_server_js_1.ApiError({ code: 400, message: 'Invalid credentials' });
+            }
+            return user;
+        }
+        throw new apicore_server_js_1.ApiError({ code: 401, message: 'Authorization requires user authentication' });
+    }
+    hasPasskeyService() {
+        const storageHints = this.storage;
+        if (storageHints.passkeyService || storageHints.passkeyStore) {
+            return true;
+        }
+        if (storageHints.adapter?.passkeyService || storageHints.adapter?.passkeyStore) {
+            return true;
+        }
+        return false;
+    }
+    hasOAuthStore() {
+        const storageHints = this.storage;
+        if (storageHints.oauthStore) {
+            return true;
+        }
+        if (storageHints.adapter?.oauthStore) {
+            return true;
+        }
+        return false;
+    }
+    storageImplements(key) {
+        const candidate = this.storage[key];
+        if (typeof candidate !== 'function') {
+            return false;
+        }
+        const baseImpl = storage_js_1.BaseAuthAdapter.prototype[key];
+        return candidate !== baseImpl;
+    }
+    storageImplementsAll(keys) {
+        return keys.every((key) => this.storageImplements(key));
+    }
+    async applyRateLimit(apiReq, endpoint) {
+        if (!this.rateLimitHook) {
+            return;
+        }
+        await this.rateLimitHook({ apiReq, endpoint });
+    }
+    resolvePkceChallengeMethod(value) {
+        if (value === 'S256') {
+            return 'S256';
+        }
+        if (value === 'plain') {
+            if (!this.allowInsecurePkcePlain) {
+                throw new apicore_server_js_1.ApiError({ code: 400, message: 'PKCE plain is not permitted' });
+            }
+            return 'plain';
+        }
+        return undefined;
+    }
+    defineRoutes() {
+        const routes = [];
+        const coreAuthSupported = this.storageImplementsAll([
+            'getUser',
+            'getUserPasswordHash',
+            'getUserId',
+            'verifyPassword',
+            'filterUser',
+            'storeToken',
+            'getToken',
+            'deleteToken'
+        ]);
+        if (!coreAuthSupported) {
+            return routes;
+        }
+        routes.push({
+            method: 'post',
+            path: '/v1/login',
+            handler: (req) => this.postLogin(req),
+            auth: { type: 'none', req: 'any' },
+            schema: { body: schemas_js_1.loginBodySchema }
+        }, {
+            method: 'post',
+            path: '/v1/refresh',
+            handler: (req) => this.postRefresh(req),
+            auth: { type: 'none', req: 'any' },
+            schema: { body: schemas_js_1.refreshBodySchema }
+        }, {
+            method: 'post',
+            path: '/v1/logout',
+            handler: (req) => this.postLogout(req),
+            auth: { type: 'maybe', req: 'any' },
+            schema: { body: schemas_js_1.logoutBodySchema }
+        }, {
+            method: 'post',
+            path: '/v1/whoami',
+            handler: (req) => this.postWhoAmI(req),
+            auth: { type: 'maybe', req: 'any' },
+            schema: { body: schemas_js_1.whoamiBodySchema }
+        }, {
+            method: 'post',
+            path: '/v1/impersonations',
+            handler: (req) => this.postImpersonation(req),
+            auth: { type: 'strict', req: 'any' },
+            schema: { body: schemas_js_1.impersonateBodySchema }
+        }, {
+            method: 'delete',
+            path: '/v1/impersonations',
+            handler: (req) => this.deleteImpersonation(req),
+            auth: { type: 'strict', req: 'any' },
+            schema: { querystring: schemas_js_1.deleteImpersonationQuerySchema }
+        });
+        const passkeysSupported = this.hasPasskeyService() &&
+            this.storageImplements('createPasskeyChallenge') &&
+            this.storageImplements('verifyPasskeyResponse');
+        const passkeyCredentialsSupported = passkeysSupported &&
+            this.storageImplements('listUserCredentials') &&
+            this.storageImplements('deletePasskeyCredential');
+        if (passkeysSupported) {
+            routes.push({
+                method: 'post',
+                path: '/v1/passkeys/challenge',
+                handler: (req) => this.postPasskeyChallenge(req),
+                auth: { type: 'none', req: 'any' },
+                schema: { body: schemas_js_1.passkeyChallengeBodySchema }
+            }, {
+                method: 'post',
+                path: '/v1/passkeys/verify',
+                handler: (req) => this.postPasskeyVerify(req),
+                auth: { type: 'none', req: 'any' },
+                schema: { body: schemas_js_1.passkeyVerifyBodySchema }
+            });
+            if (passkeyCredentialsSupported) {
+                routes.push({
+                    method: 'get',
+                    path: '/v1/passkeys',
+                    handler: (req) => this.getPasskeys(req),
+                    auth: { type: 'strict', req: 'any' }
+                }, {
+                    method: 'delete',
+                    path: '/v1/passkeys/:credentialId',
+                    handler: (req) => this.deletePasskey(req),
+                    auth: { type: 'strict', req: 'any' },
+                    schema: { params: schemas_js_1.passkeyCredentialParamsSchema }
+                });
+            }
+        }
+        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' },
+                schema: { body: schemas_js_1.oauthStartBodySchema, params: schemas_js_1.oauthProviderParamsSchema }
+            }, {
+                method: 'post',
+                path: '/v1/oauth2/:provider/callback',
+                handler: (req) => this.postOAuthCallback(req),
+                auth: { type: 'none', req: 'any' },
+                schema: { params: schemas_js_1.oauthProviderParamsSchema }
+            });
+        }
+        const oauthStorageSupported = this.hasOAuthStore() &&
+            this.storageImplements('getClient') &&
+            this.storageImplements('createAuthCode') &&
+            this.storageImplements('consumeAuthCode');
+        if (oauthStorageSupported) {
+            routes.push({
+                method: 'post',
+                path: '/v1/oauth2/authorize',
+                handler: (req) => this.postOAuthAuthorize(req),
+                auth: { type: 'maybe', req: 'any' },
+                schema: { body: schemas_js_1.oauthAuthorizeBodySchema }
+            }, {
+                method: 'post',
+                path: '/v1/oauth2/token',
+                handler: (req) => this.postOAuthToken(req),
+                auth: { type: 'none', req: 'any' },
+                schema: { body: schemas_js_1.oauthTokenBodySchema }
+            });
+        }
+        return routes;
+    }
+}
+AuthModule.defaultNamespace = '/auth';
+exports.default = AuthModule;