@technomoron/api-server-base 2.0.0-beta.21 → 2.0.0-beta.23

package/dist/{cjs → esm/server/src}/auth-cookie-options.d.ts

@@ -1,5 +1,4 @@
-import type { Request } from 'express';
-import type { CookieOptions } from 'express-serve-static-core';
+import type { ApiCookieOptions } from './api-server-base.js';
 export interface AuthCookieConfig {
     cookieSecure?: boolean | 'auto';
     cookieSameSite?: 'lax' | 'strict' | 'none';
@@ -8,4 +7,7 @@ export interface AuthCookieConfig {
     cookiePath?: string;
     devMode?: boolean;
 }
-export declare function buildAuthCookieOptions(config: AuthCookieConfig, req: Pick<Request, 'headers' | 'protocol'>): CookieOptions;
+export declare function buildAuthCookieOptions(config: AuthCookieConfig, req: {
+    headers: Record<string, string | string[] | undefined>;
+    protocol?: string;
+}): ApiCookieOptions;

package/dist/esm/server/src/base/client-info.d.ts

@@ -0,0 +1,27 @@
+interface ClientInfoRequest {
+    headers: Record<string, string | string[] | undefined>;
+    ips?: string[];
+    ip?: string;
+    socket?: {
+        remoteAddress?: string;
+    };
+    connection?: {
+        remoteAddress?: string;
+    };
+}
+export interface ClientAgentProfile {
+    ua: string;
+    browser: string;
+    os: string;
+    device: string;
+}
+export interface ClientInfo extends ClientAgentProfile {
+    ip: string | null;
+    ipchain: string[];
+}
+interface ApiRequestWithClientInfo {
+    req: ClientInfoRequest;
+    clientInfo?: ClientInfo;
+}
+export declare function ensureClientInfo(apiReq: ApiRequestWithClientInfo, trustProxy?: boolean | number): ClientInfo;
+export {};

package/dist/esm/server/src/base/client-info.js

@@ -0,0 +1,282 @@
+function normalizeIpAddress(candidate) {
+    let value = candidate.trim();
+    if (!value) {
+        return null;
+    }
+    value = value.replace(/^"+|"+$/g, '').replace(/^'+|'+$/g, '');
+    if (value.startsWith('::ffff:')) {
+        value = value.slice(7);
+    }
+    if (value.startsWith('[') && value.endsWith(']')) {
+        value = value.slice(1, -1);
+    }
+    const firstColon = value.indexOf(':');
+    const lastColon = value.lastIndexOf(':');
+    if (firstColon !== -1 && firstColon === lastColon) {
+        const maybePort = value.slice(lastColon + 1);
+        if (/^\d+$/.test(maybePort)) {
+            value = value.slice(0, lastColon);
+        }
+    }
+    value = value.trim();
+    return value || null;
+}
+function extractForwardedFor(header) {
+    if (!header) {
+        return [];
+    }
+    const values = Array.isArray(header) ? header : [header];
+    const ips = [];
+    for (const entry of values) {
+        for (const part of entry.split(',')) {
+            const normalized = normalizeIpAddress(part);
+            if (normalized) {
+                ips.push(normalized);
+            }
+        }
+    }
+    return ips;
+}
+function extractForwardedHeader(header) {
+    if (!header) {
+        return [];
+    }
+    const values = Array.isArray(header) ? header : [header];
+    const ips = [];
+    for (const entry of values) {
+        for (const part of entry.split(',')) {
+            const match = part.match(/for=([^;]+)/i);
+            if (match) {
+                const normalized = normalizeIpAddress(match[1]);
+                if (normalized) {
+                    ips.push(normalized);
+                }
+            }
+        }
+    }
+    return ips;
+}
+function detectBrowser(userAgent) {
+    const browserMatchers = [
+        { label: 'Edge', pattern: /(Edg|Edge|EdgiOS|EdgA)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Chrome', pattern: /(Chrome|CriOS)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Firefox', pattern: /(Firefox|FxiOS)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Safari', pattern: /Version\/([\d.]+).*Safari/i, versionGroup: 1 },
+        { label: 'Opera', pattern: /(OPR|Opera)\/([\d.]+)/i, versionGroup: 2 },
+        { label: 'Brave', pattern: /Brave\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Vivaldi', pattern: /Vivaldi\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Electron', pattern: /Electron\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'Node', pattern: /Node\.js\/([\d.]+)/i, versionGroup: 1 },
+        { label: 'IE', pattern: /MSIE ([\d.]+)/i, versionGroup: 1 },
+        { label: 'IE', pattern: /Trident\/.*rv:([\d.]+)/i, versionGroup: 1 }
+    ];
+    for (const matcher of browserMatchers) {
+        const m = userAgent.match(matcher.pattern);
+        if (m) {
+            const version = matcher.versionGroup ? m[matcher.versionGroup] : '';
+            return version ? `${matcher.label} ${version}` : matcher.label;
+        }
+    }
+    return '';
+}
+function detectOs(userAgent) {
+    const osMatchers = [
+        {
+            label: 'Windows',
+            pattern: /Windows NT ([\d.]+)/i,
+            transform: (match) => `Windows ${match[1]}`
+        },
+        {
+            label: 'iOS',
+            pattern: /iPhone OS ([\d_]+)/i,
+            transform: (match) => `iOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'iPadOS',
+            pattern: /iPad; CPU OS ([\d_]+)/i,
+            transform: (match) => `iPadOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'macOS',
+            pattern: /Mac OS X ([\d_]+)/i,
+            transform: (match) => `macOS ${match[1].replace(/_/g, '.')}`
+        },
+        {
+            label: 'Android',
+            pattern: /Android ([\d.]+)/i,
+            transform: (match) => `Android ${match[1]}`
+        },
+        {
+            label: 'ChromeOS',
+            pattern: /CrOS [^ ]+ ([\d.]+)/i,
+            transform: (match) => `ChromeOS ${match[1]}`
+        },
+        { label: 'Linux', pattern: /Linux/i },
+        { label: 'Unix', pattern: /X11/i }
+    ];
+    for (const matcher of osMatchers) {
+        const m = userAgent.match(matcher.pattern);
+        if (m) {
+            return matcher.transform ? matcher.transform(m) : matcher.label;
+        }
+    }
+    return '';
+}
+function detectDevice(userAgent, osLabel) {
+    if (/iPhone/i.test(userAgent)) {
+        return 'iPhone';
+    }
+    if (/iPad/i.test(userAgent)) {
+        return 'iPad';
+    }
+    if (/iPod/i.test(userAgent)) {
+        return 'iPod';
+    }
+    if (/Android/i.test(userAgent)) {
+        const match = userAgent.match(/;\s*([^;]+)\s+Build/i);
+        if (match) {
+            return match[1];
+        }
+        return 'Android Device';
+    }
+    if (/Macintosh/i.test(userAgent)) {
+        return 'Mac';
+    }
+    if (/Windows/i.test(userAgent)) {
+        return 'PC';
+    }
+    if (/CrOS/i.test(userAgent)) {
+        return 'Chromebook';
+    }
+    return osLabel;
+}
+function parseClientAgent(userAgentHeader) {
+    const raw = Array.isArray(userAgentHeader) ? userAgentHeader[0] : userAgentHeader;
+    const ua = typeof raw === 'string' ? raw.trim() : '';
+    if (!ua) {
+        return { ua: '', browser: '', os: '', device: '' };
+    }
+    const os = detectOs(ua);
+    const browser = detectBrowser(ua);
+    const device = detectDevice(ua, os);
+    return { ua, browser, os, device };
+}
+function isLoopbackAddress(ip) {
+    if (ip === '::1' || ip === '0:0:0:0:0:0:0:1') {
+        return true;
+    }
+    if (ip === '0.0.0.0' || ip === '127.0.0.1') {
+        return true;
+    }
+    if (ip.startsWith('127.')) {
+        return true;
+    }
+    return false;
+}
+function collectSocketAddresses(req) {
+    const seen = new Set();
+    const result = [];
+    const pushNormalized = (ip) => {
+        if (!ip || seen.has(ip))
+            return;
+        seen.add(ip);
+        result.push(ip);
+    };
+    if (Array.isArray(req.ips)) {
+        for (const ip of req.ips) {
+            pushNormalized(normalizeIpAddress(ip));
+        }
+    }
+    if (typeof req.ip === 'string') {
+        pushNormalized(normalizeIpAddress(req.ip));
+    }
+    const socketAddress = req.socket?.remoteAddress;
+    if (typeof socketAddress === 'string') {
+        pushNormalized(normalizeIpAddress(socketAddress));
+    }
+    const connectionAddress = req.connection?.remoteAddress;
+    if (typeof connectionAddress === 'string') {
+        pushNormalized(normalizeIpAddress(connectionAddress));
+    }
+    return result;
+}
+function collectForwardedIps(req) {
+    const seen = new Set();
+    const result = [];
+    const pushNormalized = (ip) => {
+        if (!ip || seen.has(ip))
+            return;
+        seen.add(ip);
+        result.push(ip);
+    };
+    for (const ip of extractForwardedFor(req.headers['x-forwarded-for'])) {
+        pushNormalized(ip);
+    }
+    for (const ip of extractForwardedHeader(req.headers['forwarded'])) {
+        pushNormalized(ip);
+    }
+    const realIp = req.headers['x-real-ip'];
+    if (Array.isArray(realIp)) {
+        for (const value of realIp) {
+            pushNormalized(normalizeIpAddress(value));
+        }
+    }
+    else if (typeof realIp === 'string') {
+        pushNormalized(normalizeIpAddress(realIp));
+    }
+    return result;
+}
+function collectClientIpChain(req, trustProxy) {
+    const socketIps = collectSocketAddresses(req);
+    // trustProxy=false: ignore forwarded headers entirely
+    if (trustProxy === false) {
+        return socketIps;
+    }
+    const forwardedIps = collectForwardedIps(req);
+    // trustProxy=number: only trust that many rightmost forwarded entries
+    if (typeof trustProxy === 'number' && trustProxy >= 0) {
+        const trusted = trustProxy > 0 ? forwardedIps.slice(-trustProxy) : [];
+        const seen = new Set(trusted);
+        for (const ip of socketIps) {
+            if (!seen.has(ip)) {
+                seen.add(ip);
+                trusted.push(ip);
+            }
+        }
+        return trusted;
+    }
+    // trustProxy=true or undefined: trust all (backwards-compatible default)
+    const seen = new Set(forwardedIps);
+    const result = [...forwardedIps];
+    for (const ip of socketIps) {
+        if (!seen.has(ip)) {
+            seen.add(ip);
+            result.push(ip);
+        }
+    }
+    return result;
+}
+function selectClientIp(chain) {
+    for (const ip of chain) {
+        if (!isLoopbackAddress(ip)) {
+            return ip;
+        }
+    }
+    return chain[0] ?? null;
+}
+function buildClientInfo(req, trustProxy) {
+    const agent = parseClientAgent(req.headers['user-agent']);
+    const ipchain = collectClientIpChain(req, trustProxy);
+    const ip = selectClientIp(ipchain);
+    return {
+        ...agent,
+        ip,
+        ipchain
+    };
+}
+export function ensureClientInfo(apiReq, trustProxy) {
+    if (!apiReq.clientInfo) {
+        apiReq.clientInfo = buildClientInfo(apiReq.req, trustProxy);
+    }
+    return apiReq.clientInfo;
+}

package/dist/esm/server/src/base/error-utils.d.ts

@@ -0,0 +1,16 @@
+import type { ApiErrorParams } from '../api-server-base.js';
+export interface ApiErrorLike {
+    code: number;
+    message: string;
+    data?: unknown;
+    errors?: unknown;
+}
+export declare function guessExceptionText(error: unknown, defMsg?: string): string;
+export declare function normalizeApiErrorParams({ code, message, data, errors }: ApiErrorParams): {
+    code: number;
+    message: string;
+    data: unknown;
+    errors: Record<string, string>;
+};
+export declare function isApiErrorLike(candidate: unknown): candidate is ApiErrorLike;
+export declare function asHttpStatus(error: unknown): number | null;

package/dist/esm/server/src/base/error-utils.js

@@ -0,0 +1,44 @@
+export function guessExceptionText(error, defMsg = 'Unknown Error') {
+    const msg = [];
+    if (typeof error === 'string' && error.trim() !== '') {
+        msg.push(error);
+    }
+    else if (error && typeof error === 'object') {
+        const errorDetails = error;
+        if (typeof errorDetails.message === 'string' && errorDetails.message.trim() !== '') {
+            msg.push(errorDetails.message);
+        }
+        if (errorDetails.parent &&
+            typeof errorDetails.parent.message === 'string' &&
+            errorDetails.parent.message.trim() !== '') {
+            msg.push(errorDetails.parent.message);
+        }
+    }
+    return msg.length > 0 ? msg.join(' / ') : defMsg;
+}
+export function normalizeApiErrorParams({ code, message, data, errors }) {
+    return {
+        code: typeof code === 'number' ? code : 500,
+        message: guessExceptionText(message, '[Unknown error (null/undefined)]'),
+        data: data !== undefined ? data : null,
+        errors: errors !== undefined ? errors : {}
+    };
+}
+export function isApiErrorLike(candidate) {
+    if (!candidate || typeof candidate !== 'object') {
+        return false;
+    }
+    const maybeError = candidate;
+    return typeof maybeError.code === 'number' && typeof maybeError.message === 'string';
+}
+export function asHttpStatus(error) {
+    if (!error || typeof error !== 'object') {
+        return null;
+    }
+    const maybe = error;
+    const status = typeof maybe.status === 'number' ? maybe.status : maybe.statusCode;
+    if (typeof status === 'number' && status >= 400 && status <= 599) {
+        return status;
+    }
+    return null;
+}

package/dist/esm/server/src/base/request-utils.d.ts

@@ -0,0 +1,8 @@
+interface HydratableRequest {
+    method?: string;
+    query?: unknown;
+    body?: unknown;
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function hydrateGetBody(req: HydratableRequest): void;
+export {};

package/dist/esm/server/src/base/request-utils.js

@@ -0,0 +1,23 @@
+export function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function hydrateGetBody(req) {
+    if ((req.method ?? '').toUpperCase() !== 'GET') {
+        return;
+    }
+    const query = isPlainObject(req.query) ? req.query : null;
+    if (!query || Object.keys(query).length === 0) {
+        return;
+    }
+    const body = isPlainObject(req.body) ? req.body : null;
+    if (!body || Object.keys(body).length === 0) {
+        req.body = { ...query };
+        return;
+    }
+    // Keep explicit body fields authoritative when both query and body provide the same key.
+    req.body = { ...query, ...body };
+}

package/dist/{cjs → esm/server/src}/index.d.ts

@@ -25,3 +25,10 @@ export { MemoryPasskeyStore } from './passkey/memory.js';
 export type { PasskeyServiceConfig, PasskeyChallengeRecord, PasskeyUserDescriptor, StoredPasskeyCredential, PasskeyChallenge, PasskeyChallengeParams, PasskeyVerificationParams, PasskeyVerificationResult } from './passkey/types.js';
 export { OAuthStore } from './oauth/base.js';
 export { MemoryOAuthStore } from './oauth/memory.js';
+export { FixedWindowRateLimiter } from './limiter/fixed-window.js';
+export type { RateLimitDecision } from './limiter/fixed-window.js';
+export { createAuthRateLimitHook } from './limiter/auth-rate-limiter.js';
+export type { AuthRateLimitConfig } from './limiter/auth-rate-limiter.js';
+export { TusUploadModule } from './upload/tus-module.js';
+export { MemoryTusUploadStore, TusUploadOffsetError } from './upload/memory.js';
+export type { TusMetadata, TusUploadRecord, TusCreateUploadInput, TusAppendInput, TusUploadStore } from './upload/types.js';

package/dist/esm/{index.js → server/src/index.js}

@@ -15,3 +15,7 @@ export { PasskeyStore } from './passkey/base.js';
 export { MemoryPasskeyStore } from './passkey/memory.js';
 export { OAuthStore } from './oauth/base.js';
 export { MemoryOAuthStore } from './oauth/memory.js';
+export { FixedWindowRateLimiter } from './limiter/fixed-window.js';
+export { createAuthRateLimitHook } from './limiter/auth-rate-limiter.js';
+export { TusUploadModule } from './upload/tus-module.js';
+export { MemoryTusUploadStore, TusUploadOffsetError } from './upload/memory.js';

package/dist/esm/server/src/limiter/auth-rate-limiter.d.ts

@@ -0,0 +1,12 @@
+import { type ApiRequest } from '../api-server-base.js';
+import { FixedWindowRateLimiter } from './fixed-window.js';
+type AuthRateLimitEndpoint = 'login' | 'passkey-challenge' | 'oauth-token' | 'oauth-authorize';
+export interface AuthRateLimitConfig {
+    windowSec?: number;
+    max?: number;
+}
+export declare function createAuthRateLimitHook(config: Partial<Record<AuthRateLimitEndpoint, AuthRateLimitConfig>>, limiter?: FixedWindowRateLimiter): (ctx: {
+    apiReq: ApiRequest;
+    endpoint: string;
+}) => void;
+export {};

package/dist/esm/server/src/limiter/auth-rate-limiter.js

@@ -0,0 +1,32 @@
+import { ApiError } from '../api-server-base.js';
+import { FixedWindowRateLimiter } from './fixed-window.js';
+export function createAuthRateLimitHook(config, limiter) {
+    if (!config || Object.keys(config).length === 0) {
+        return () => { };
+    }
+    const instance = limiter ?? new FixedWindowRateLimiter();
+    return (ctx) => {
+        const endpointConfig = config[ctx.endpoint];
+        if (!endpointConfig) {
+            return;
+        }
+        const windowSec = endpointConfig.windowSec ?? 0;
+        const max = endpointConfig.max ?? 0;
+        if (windowSec <= 0 || max <= 0) {
+            return;
+        }
+        const clientIp = ctx.apiReq.getClientIp() ?? '';
+        if (!clientIp) {
+            return;
+        }
+        const key = `${ctx.endpoint}:${clientIp}`;
+        const decision = instance.check(key, max, windowSec * 1000);
+        if (!decision.allowed) {
+            throw new ApiError({
+                code: 429,
+                message: 'Too many requests; try again later',
+                data: { retryAfterSec: decision.retryAfterSec }
+            });
+        }
+    };
+}

package/dist/esm/server/src/limiter/fixed-window.d.ts

@@ -0,0 +1,11 @@
+export type RateLimitDecision = {
+    allowed: boolean;
+    retryAfterSec: number;
+};
+export declare class FixedWindowRateLimiter {
+    private readonly maxKeys;
+    private readonly buckets;
+    constructor(maxKeys?: number);
+    check(key: string, max: number, windowMs: number): RateLimitDecision;
+    private prune;
+}

package/dist/esm/server/src/limiter/fixed-window.js

@@ -0,0 +1,37 @@
+export class FixedWindowRateLimiter {
+    constructor(maxKeys = 10000) {
+        this.maxKeys = maxKeys;
+        this.buckets = new Map();
+    }
+    check(key, max, windowMs) {
+        if (!key || max <= 0 || windowMs <= 0) {
+            return { allowed: true, retryAfterSec: 0 };
+        }
+        const now = Date.now();
+        const bucket = this.buckets.get(key);
+        if (!bucket || now - bucket.windowStartMs >= windowMs) {
+            this.buckets.delete(key);
+            this.buckets.set(key, { windowStartMs: now, count: 1 });
+            this.prune();
+            return { allowed: true, retryAfterSec: 0 };
+        }
+        bucket.count += 1;
+        // Refresh insertion order to keep active entries at the end for pruning.
+        this.buckets.delete(key);
+        this.buckets.set(key, bucket);
+        if (bucket.count <= max) {
+            return { allowed: true, retryAfterSec: 0 };
+        }
+        const retryAfterSec = Math.max(1, Math.ceil((bucket.windowStartMs + windowMs - now) / 1000));
+        return { allowed: false, retryAfterSec };
+    }
+    prune() {
+        while (this.buckets.size > this.maxKeys) {
+            const oldest = this.buckets.keys().next().value;
+            if (!oldest) {
+                break;
+            }
+            this.buckets.delete(oldest);
+        }
+    }
+}

package/dist/esm/{oauth → server/src/oauth}/base.d.ts

@@ -1,10 +1,17 @@
 import type { AuthCode, OAuthClient } from './types.js';
+/** Base contract for OAuth client/auth-code persistence backends. */
 export declare abstract class OAuthStore {
+    /** Fetch an OAuth client by id. */
     abstract getClient(clientId: string): Promise<OAuthClient | null>;
+    /** Create an OAuth client. */
     abstract createClient(input: OAuthClient): Promise<OAuthClient>;
+    /** Verify an OAuth client secret. */
     abstract verifyClientSecret(clientId: string, secret: string | null): Promise<boolean>;
+    /** Persist an authorization code. */
     abstract createAuthCode(code: AuthCode): Promise<void>;
-    abstract consumeAuthCode(code: string): Promise<AuthCode | null>;
+    /** Consume an authorization code once. When clientId is provided, only consume if it matches. */
+    abstract consumeAuthCode(code: string, clientId?: string): Promise<AuthCode | null>;
+    /** Close underlying resources. */
     abstract close(): Promise<void>;
 }
 export type { OAuthClient, AuthCode } from './types.js';

package/dist/esm/server/src/oauth/base.js

@@ -0,0 +1,3 @@
+/** Base contract for OAuth client/auth-code persistence backends. */
+export class OAuthStore {
+}

package/dist/{cjs → esm/server/src}/oauth/memory.d.ts

@@ -15,7 +15,7 @@ export declare class MemoryOAuthStore extends OAuthStore {
     createClient(input: OAuthClient): Promise<OAuthClient>;
     verifyClientSecret(clientId: string, secret: string | null): Promise<boolean>;
     createAuthCode(code: AuthCode): Promise<void>;
-    consumeAuthCode(code: string): Promise<AuthCode | null>;
+    consumeAuthCode(code: string, clientId?: string): Promise<AuthCode | null>;
     close(): Promise<void>;
     private enforceClientCapacity;
     private enforceCodeCapacity;

package/dist/esm/{oauth → server/src/oauth}/memory.js

@@ -11,7 +11,7 @@ function cloneClient(client) {
         name: client.name,
         redirectUris: [...client.redirectUris],
         scope: client.scope ? [...client.scope] : undefined,
-        metadata: client.metadata ? { ...client.metadata } : undefined,
+        metadata: client.metadata ? JSON.parse(JSON.stringify(client.metadata)) : undefined,
         firstParty: client.firstParty
     };
 }
@@ -83,11 +83,14 @@ export class MemoryOAuthStore extends OAuthStore {
         this.codes.set(record.code, record);
         this.enforceCodeCapacity();
     }
-    async consumeAuthCode(code) {
+    async consumeAuthCode(code, clientId) {
         const record = this.codes.get(code);
         if (!record) {
             return null;
         }
+        if (clientId && record.clientId !== clientId) {
+            return null;
+        }
         if (record.expiresAt.getTime() <= Date.now()) {
             this.codes.delete(code);
             return null;

package/dist/{cjs → esm/server/src}/oauth/sequelize.d.ts

@@ -23,7 +23,7 @@ export declare class SequelizeOAuthStore extends OAuthStore {
     createClient(input: OAuthClient): Promise<OAuthClient>;
     verifyClientSecret(clientId: string, clientSecret: string | null): Promise<boolean>;
     createAuthCode(code: AuthCode): Promise<void>;
-    consumeAuthCode(code: string): Promise<AuthCode | null>;
+    consumeAuthCode(code: string, clientId?: string): Promise<AuthCode | null>;
     close(): Promise<void>;
     private toOAuthClient;
     private toAuthCode;

package/dist/esm/{oauth → server/src/oauth}/sequelize.js

@@ -97,13 +97,17 @@ export class SequelizeOAuthStore extends OAuthStore {
             metadata: serializeMetadata(code.metadata)
         });
     }
-    async consumeAuthCode(code) {
+    async consumeAuthCode(code, clientId) {
         const sequelize = this.codes.sequelize;
         if (!sequelize) {
             throw new Error('Code model is not bound to a Sequelize instance');
         }
         return sequelize.transaction({ isolationLevel: Transaction.ISOLATION_LEVELS.READ_COMMITTED }, async (transaction) => {
-            const model = await this.codes.findByPk(code, { transaction, lock: true });
+            const where = { code };
+            if (clientId) {
+                where.client_id = clientId;
+            }
+            const model = await this.codes.findOne({ where, transaction, lock: true });
             if (!model) {
                 return null;
             }

package/dist/{cjs → esm/server/src}/passkey/base.d.ts

@@ -1,17 +1,28 @@
 import type { PasskeyChallengeRecord, PasskeyStorageAdapter, PasskeyUserDescriptor, StoredPasskeyCredential } from './types.js';
 import type { AuthIdentifier } from '../auth-api/types.js';
+/** Base contract for passkey credential/challenge persistence backends. */
 export declare abstract class PasskeyStore implements PasskeyStorageAdapter {
+    /** Resolve a passkey user descriptor by id/login. */
     abstract resolveUser(params: {
         userId?: AuthIdentifier;
         login?: string;
     }): Promise<PasskeyUserDescriptor | null>;
+    /** List passkey credentials for a user. */
     abstract listUserCredentials(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
+    /** Delete a credential by binary/base64url id. */
     abstract deleteCredential(credentialId: Buffer | string): Promise<boolean>;
+    /** Find a credential by binary id. */
     abstract findCredentialById(credentialId: Buffer): Promise<StoredPasskeyCredential | null>;
+    /** Save a credential record. */
     abstract saveCredential(record: StoredPasskeyCredential): Promise<void>;
+    /** Update signature counter for a credential. */
     abstract updateCredentialCounter(credentialId: Buffer, counter: number): Promise<void>;
+    /** Save a challenge record. */
     abstract saveChallenge(record: PasskeyChallengeRecord): Promise<void>;
+    /** Read a challenge without consuming it. */
     abstract getChallenge(challenge: string): Promise<PasskeyChallengeRecord | null>;
+    /** Consume and return a challenge. */
     abstract consumeChallenge(challenge: string): Promise<PasskeyChallengeRecord | null>;
+    /** Cleanup expired challenges. */
     abstract cleanupChallenges(now: Date): Promise<void>;
 }

package/dist/esm/server/src/passkey/base.js

@@ -0,0 +1,3 @@
+/** Base contract for passkey credential/challenge persistence backends. */
+export class PasskeyStore {
+}