@technomoron/apicore-server 1.0.0-beta.1

package/dist/esm/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/base/error-utils.d.ts

@@ -0,0 +1,16 @@
+import type { ApiErrorParams } from '../apicore-server.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/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/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/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/esm/index.d.ts

@@ -0,0 +1,34 @@
+export { default as ApiServer } from './apicore-server.js';
+export { ApiError } from './apicore-server.js';
+export { ApiModule } from './api-module.js';
+export type { ApiErrorParams, ApiHandler, ApiKey, ApiServerConf, ApiRequest, ApiRoute, ApiAuthType, ApiAuthClass, ApiTokenData, ExtendedReq, ExpressApiRequest, ExpressApiLocals } from './apicore-server.js';
+export type { AuthIdentifier } from './auth-api/types.js';
+export type { Token, TokenPair, TokenStatus } from './token/types.js';
+export type { JwtSignResult, JwtVerifyResult, JwtDecodeResult } from './token/base.js';
+export type { OAuthClient, AuthCodeData, AuthCodeRequest } from './oauth/types.js';
+export type { AuthProviderModule } from './auth-api/module.js';
+export { nullAuthAdapter, BaseAuthAdapter } from './auth-api/storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-api/module.js';
+export { CompositeAuthAdapter } from './auth-api/compat-auth-storage.js';
+export { MemAuthStore } from './auth-api/mem-auth-store.js';
+export { default as AuthModule } from './auth-api/auth-module.js';
+export type { OAuthStartParams, OAuthStartResult, OAuthCallbackParams, OAuthCallbackResult } from './oauth/types.js';
+export type { BcryptHasherOptions, CreateUserInput, UpdateUserInput, PublicUserMapper } from './user/types.js';
+export { UserStore } from './user/base.js';
+export { MemoryUserStore } from './user/memory.js';
+export type { MemoryUserAttributes, MemoryUserStoreOptions } from './user/memory.js';
+export { TokenStore } from './token/base.js';
+export { MemoryTokenStore } from './token/memory.js';
+export { PasskeyService } from './passkey/service.js';
+export { PasskeyStore } from './passkey/base.js';
+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

@@ -0,0 +1,21 @@
+export { default as ApiServer } from './apicore-server.js';
+export { ApiError } from './apicore-server.js';
+export { ApiModule } from './api-module.js';
+export { nullAuthAdapter, BaseAuthAdapter } from './auth-api/storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-api/module.js';
+export { CompositeAuthAdapter } from './auth-api/compat-auth-storage.js';
+export { MemAuthStore } from './auth-api/mem-auth-store.js';
+export { default as AuthModule } from './auth-api/auth-module.js';
+export { UserStore } from './user/base.js';
+export { MemoryUserStore } from './user/memory.js';
+export { TokenStore } from './token/base.js';
+export { MemoryTokenStore } from './token/memory.js';
+export { PasskeyService } from './passkey/service.js';
+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/limiter/auth-rate-limiter.d.ts

@@ -0,0 +1,12 @@
+import { type ApiRequest } from '../apicore-server.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/limiter/auth-rate-limiter.js

@@ -0,0 +1,32 @@
+import { ApiError } from '../apicore-server.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/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/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/base.d.ts

@@ -0,0 +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>;
+    /** 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/oauth/base.js

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

package/dist/esm/oauth/memory.d.ts

@@ -0,0 +1,22 @@
+import { OAuthStore, type AuthCode, type OAuthClient } from './base.js';
+export interface MemoryOAuthStoreOptions {
+    bcryptRounds?: number;
+    maxClients?: number;
+    maxAuthCodes?: number;
+}
+export declare class MemoryOAuthStore extends OAuthStore {
+    private readonly clients;
+    private readonly codes;
+    private readonly bcryptRounds;
+    private readonly maxClients?;
+    private readonly maxAuthCodes?;
+    constructor(options?: MemoryOAuthStoreOptions);
+    getClient(clientId: string): Promise<OAuthClient | null>;
+    createClient(input: OAuthClient): Promise<OAuthClient>;
+    verifyClientSecret(clientId: string, secret: string | null): Promise<boolean>;
+    createAuthCode(code: AuthCode): Promise<void>;
+    consumeAuthCode(code: string, clientId?: string): Promise<AuthCode | null>;
+    close(): Promise<void>;
+    private enforceClientCapacity;
+    private enforceCodeCapacity;
+}