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

package/dist/esm/passkey/service.js

@@ -0,0 +1,217 @@
+import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from '@simplewebauthn/server';
+import { isoBase64URL } from '@simplewebauthn/server/helpers';
+const ALLOWED_TRANSPORTS = [
+    'ble',
+    'cable',
+    'hybrid',
+    'internal',
+    'nfc',
+    'smart-card',
+    'usb'
+];
+function sanitizeTransports(input) {
+    if (!Array.isArray(input)) {
+        return undefined;
+    }
+    const filtered = input
+        .map((value) => String(value))
+        .filter((value) => ALLOWED_TRANSPORTS.includes(value));
+    return filtered.length > 0 ? filtered : undefined;
+}
+function toBase64Url(buffer) {
+    return isoBase64URL.fromBuffer(new Uint8Array(buffer));
+}
+function fromBase64Url(value) {
+    return Buffer.from(isoBase64URL.toBuffer(value));
+}
+function toBuffer(value) {
+    if (Buffer.isBuffer(value)) {
+        return value;
+    }
+    const view = value instanceof Uint8Array ? value : new Uint8Array(value);
+    return Buffer.from(view);
+}
+export class PasskeyService {
+    constructor(config, adapter, logger = console) {
+        this.config = config;
+        this.adapter = adapter;
+        this.logger = logger;
+    }
+    async createChallenge(params) {
+        await this.adapter.cleanupChallenges?.(new Date());
+        const metadata = {
+            domain: typeof params.domain === 'string' ? params.domain : undefined,
+            fingerprint: typeof params.fingerprint === 'string' ? params.fingerprint : undefined,
+            label: typeof params.label === 'string' ? params.label : undefined,
+            userAgent: typeof params.userAgent === 'string' ? params.userAgent : undefined
+        };
+        if (params.action === 'register') {
+            return this.createRegistrationChallenge(params, metadata);
+        }
+        if (params.action === 'authenticate') {
+            return this.createAuthenticationChallenge(params, metadata);
+        }
+        throw new Error(`Unsupported passkey action: ${String(params.action)}`);
+    }
+    async verifyResponse(params) {
+        await this.adapter.cleanupChallenges?.(new Date());
+        const record = await this.adapter.consumeChallenge(params.expectedChallenge);
+        if (!record) {
+            return { verified: false };
+        }
+        if (record.expiresAt.getTime() <= Date.now()) {
+            return { verified: false };
+        }
+        try {
+            if (record.action === 'register') {
+                return this.verifyRegistration(params, record);
+            }
+            if (record.action === 'authenticate') {
+                return this.verifyAuthentication(params, record);
+            }
+        }
+        catch (error) {
+            this.logger.error?.('Passkey verification failed', error);
+        }
+        return { verified: false };
+    }
+    async createRegistrationChallenge(params, metadata) {
+        const user = await this.requireUser({ userId: params.userId, login: params.login });
+        const existing = await this.adapter.listUserCredentials(user.id);
+        const excludeCredentials = existing.map((credential) => {
+            const transports = credential.transports;
+            return transports && transports.length > 0
+                ? { id: toBase64Url(credential.credentialId), transports }
+                : { id: toBase64Url(credential.credentialId) };
+        });
+        const options = await generateRegistrationOptions({
+            rpName: this.config.rpName,
+            rpID: this.config.rpId,
+            userID: Buffer.from(String(user.id)),
+            userName: user.login,
+            userDisplayName: user.displayName,
+            excludeCredentials
+        });
+        const expiresAt = this.createExpiry();
+        await this.adapter.saveChallenge({
+            challenge: options.challenge,
+            action: 'register',
+            userId: user.id,
+            login: user.login,
+            expiresAt,
+            metadata
+        });
+        return {
+            challenge: options.challenge,
+            expiresAt: expiresAt.toISOString(),
+            userId: user.id
+        };
+    }
+    async createAuthenticationChallenge(params, metadata) {
+        const user = await this.requireUser({ userId: params.userId, login: params.login });
+        const credentials = await this.adapter.listUserCredentials(user.id);
+        const allowCredentials = credentials.map((credential) => {
+            const transports = sanitizeTransports(credential.transports);
+            return transports && transports.length > 0
+                ? { type: 'public-key', id: toBase64Url(credential.credentialId), transports }
+                : { type: 'public-key', id: toBase64Url(credential.credentialId) };
+        });
+        const options = await generateAuthenticationOptions({
+            allowCredentials,
+            userVerification: this.config.userVerification,
+            rpID: this.config.rpId
+        });
+        const expiresAt = this.createExpiry();
+        await this.adapter.saveChallenge({
+            challenge: options.challenge,
+            action: 'authenticate',
+            userId: user.id,
+            login: user.login,
+            expiresAt,
+            metadata
+        });
+        return {
+            challenge: options.challenge,
+            expiresAt: expiresAt.toISOString(),
+            userId: user.id
+        };
+    }
+    async verifyRegistration(params, record) {
+        const parsed = typeof params.response === 'object' && params.response ? { ...params.response } : {};
+        const response = {
+            ...parsed,
+            id: String(parsed.id ?? ''),
+            rawId: String(parsed.rawId ?? '')
+        };
+        const user = await this.requireUser({ userId: record.userId, login: record.login });
+        const result = await verifyRegistrationResponse({
+            response,
+            expectedChallenge: record.challenge,
+            expectedOrigin: this.config.origins,
+            expectedRPID: this.config.rpId,
+            requireUserVerification: true
+        });
+        if (!result.verified || !result.registrationInfo) {
+            return { verified: false };
+        }
+        const registrationInfo = result.registrationInfo;
+        await this.adapter.saveCredential({
+            userId: user.id,
+            credentialId: toBuffer(registrationInfo.credentialID),
+            publicKey: toBuffer(registrationInfo.credentialPublicKey),
+            counter: registrationInfo.counter,
+            transports: sanitizeTransports(params.response.transports),
+            backedUp: registrationInfo.credentialDeviceType === 'multiDevice',
+            deviceType: registrationInfo.credentialDeviceType
+        });
+        return { verified: true, userId: user.id, login: user.login };
+    }
+    async verifyAuthentication(params, record) {
+        const parsed = typeof params.response === 'object' && params.response ? { ...params.response } : {};
+        const response = {
+            ...parsed,
+            id: String(parsed.id ?? ''),
+            rawId: String(parsed.rawId ?? '')
+        };
+        const credential = await this.adapter.findCredentialById(fromBase64Url(response.id));
+        if (!credential) {
+            return { verified: false };
+        }
+        const user = await this.requireUser({ userId: credential.userId, login: record.login });
+        const storedAuthData = {
+            credentialID: credential.credentialId,
+            counter: credential.counter,
+            credentialBackedUp: credential.backedUp,
+            credentialDeviceType: credential.deviceType,
+            credentialPublicKey: credential.publicKey,
+            transports: credential.transports ?? undefined
+        };
+        const result = await verifyAuthenticationResponse({
+            response,
+            expectedChallenge: record.challenge,
+            expectedOrigin: this.config.origins,
+            expectedRPID: this.config.rpId,
+            authenticator: storedAuthData,
+            requireUserVerification: true
+        });
+        if (!result.verified) {
+            return { verified: false };
+        }
+        await this.adapter.updateCredentialCounter(credential.credentialId, result.authenticationInfo.newCounter);
+        return {
+            verified: true,
+            userId: user.id,
+            login: user.login
+        };
+    }
+    async requireUser(params) {
+        const user = await this.adapter.resolveUser(params);
+        if (!user) {
+            throw new Error('User not found');
+        }
+        return user;
+    }
+    createExpiry() {
+        return new Date(Date.now() + this.config.timeoutMs);
+    }
+}

package/dist/esm/passkey/types.d.ts

@@ -0,0 +1,75 @@
+import type { AuthIdentifier } from '../auth-api/types.js';
+import type { Token, TokenPair } from '../token/types.js';
+import type { AuthenticatorTransportFuture } from '@simplewebauthn/server';
+export type CredentialDeviceType = 'singleDevice' | 'multiDevice';
+export interface PasskeyServiceConfig {
+    rpId: string;
+    rpName: string;
+    origins: string[];
+    timeoutMs: number;
+    userVerification?: 'preferred' | 'required' | 'discouraged';
+}
+export interface PasskeyChallengeMetadata {
+    domain?: string;
+    fingerprint?: string;
+    label?: string;
+    userAgent?: string;
+}
+export interface PasskeyChallengeRecord {
+    challenge: string;
+    action: 'register' | 'authenticate';
+    userId?: AuthIdentifier;
+    login?: string;
+    expiresAt: Date;
+    metadata: PasskeyChallengeMetadata;
+}
+export interface PasskeyUserDescriptor {
+    id: AuthIdentifier;
+    login: string;
+    displayName: string;
+}
+export interface StoredPasskeyCredential {
+    userId: AuthIdentifier;
+    credentialId: Buffer;
+    publicKey: Buffer;
+    counter: number;
+    transports?: AuthenticatorTransportFuture[];
+    backedUp: boolean;
+    deviceType: CredentialDeviceType;
+}
+export interface PasskeyStorageAdapter {
+    resolveUser(params: {
+        userId?: AuthIdentifier;
+        login?: string;
+    }): Promise<PasskeyUserDescriptor | null>;
+    listUserCredentials(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
+    findCredentialById(credentialId: Buffer): Promise<StoredPasskeyCredential | null>;
+    saveCredential(record: StoredPasskeyCredential): Promise<void>;
+    updateCredentialCounter(credentialId: Buffer, counter: number): Promise<void>;
+    saveChallenge(record: PasskeyChallengeRecord): Promise<void>;
+    consumeChallenge(challenge: string): Promise<PasskeyChallengeRecord | null>;
+    cleanupChallenges?(now: Date): Promise<void>;
+}
+export interface PasskeyChallengeParams extends Partial<Omit<Token, 'userId'>> {
+    action: 'register' | 'authenticate';
+    login?: string;
+    userAgent?: string;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyChallenge extends Record<string, unknown> {
+    challenge: string;
+    expiresAt?: string | number | Date;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyVerificationParams extends Partial<Omit<Token, 'userId'>> {
+    expectedChallenge: string;
+    login?: string;
+    response: Record<string, unknown>;
+    userId?: AuthIdentifier;
+}
+export interface PasskeyVerificationResult extends Record<string, unknown> {
+    login?: string;
+    tokens?: TokenPair;
+    userId?: AuthIdentifier;
+    verified: boolean;
+}

package/dist/esm/passkey/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/token/base.d.ts

@@ -0,0 +1,38 @@
+import type { Token } from './types.js';
+import type { DecodeOptions, SignOptions, VerifyOptions } from 'jsonwebtoken';
+export interface JwtSignResult {
+    success: boolean;
+    token?: string;
+    error?: string;
+}
+export interface JwtVerifyResult<T> {
+    success: boolean;
+    data?: T;
+    expired?: boolean;
+    error?: string;
+}
+export interface JwtDecodeResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+export declare abstract class TokenStore {
+    abstract save(record: Token): Promise<void>;
+    abstract get(query: Partial<Token>, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    abstract delete(query: Partial<Token>): Promise<number>;
+    abstract update(update: Partial<Token> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    abstract list(userId: string | number, opts?: {
+        limit?: number;
+        offset?: number;
+        includeExpired?: boolean;
+    }): Promise<Token[]>;
+    abstract close(): Promise<void>;
+    normalizeToken(token: Partial<Token>): Token;
+    jwtSign(payload: any, secret: string, expiresInSeconds: number, options?: SignOptions): JwtSignResult;
+    jwtVerify<T>(token: string, secret: string, options?: VerifyOptions): JwtVerifyResult<T>;
+    jwtDecode<T>(token: string, options?: DecodeOptions): JwtDecodeResult<T>;
+}

package/dist/esm/token/base.js

@@ -0,0 +1,107 @@
+import jwt from 'jsonwebtoken';
+function normalizeScope(scope) {
+    if (!scope) {
+        return undefined;
+    }
+    if (Array.isArray(scope)) {
+        return scope.filter((entry) => typeof entry === 'string' && entry.length > 0);
+    }
+    return scope
+        .split(/\s+/)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function normalizeRefreshTtlSeconds(value) {
+    if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+        return Math.floor(value);
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return Math.floor(parsed);
+        }
+    }
+    return undefined;
+}
+function normalizeTokenInternal(input) {
+    if (!input.refreshToken) {
+        throw new Error('refreshToken is required');
+    }
+    if (!input.accessToken) {
+        throw new Error('accessToken is required');
+    }
+    if (input.userId === undefined || input.userId === null) {
+        throw new Error('userId is required');
+    }
+    const userId = String(input.userId);
+    const ruid = input.ruid === undefined || input.ruid === null ? undefined : String(input.ruid);
+    const expires = input.expires ? new Date(input.expires) : new Date(Date.now() + 30 * 24 * 60 * 60 * 1000);
+    const issuedAt = input.issuedAt ? new Date(input.issuedAt) : new Date();
+    const lastSeenAt = input.lastSeenAt ? new Date(input.lastSeenAt) : issuedAt;
+    const scope = normalizeScope(input.scope);
+    const refreshTtlSeconds = normalizeRefreshTtlSeconds(input.refreshTtlSeconds);
+    const status = input.status === 'revoked' ? 'revoked' : expires.getTime() < Date.now() ? 'expired' : 'active';
+    const sessionCookie = typeof input.sessionCookie === 'boolean' ? input.sessionCookie : false;
+    return {
+        ...input,
+        accessToken: input.accessToken,
+        refreshToken: input.refreshToken,
+        userId,
+        domain: typeof input.domain === 'string' ? input.domain : '',
+        fingerprint: typeof input.fingerprint === 'string' ? input.fingerprint : '',
+        label: typeof input.label === 'string' ? input.label : '',
+        browser: typeof input.browser === 'string' ? input.browser : '',
+        device: typeof input.device === 'string' ? input.device : '',
+        ip: typeof input.ip === 'string' ? input.ip : '',
+        os: typeof input.os === 'string' ? input.os : '',
+        loginType: typeof input.loginType === 'string' && input.loginType.length > 0 ? input.loginType : undefined,
+        scope,
+        refreshTtlSeconds,
+        expires,
+        issuedAt,
+        lastSeenAt,
+        status,
+        ruid,
+        sessionCookie
+    };
+}
+export class TokenStore {
+    // Instance helpers
+    normalizeToken(token) {
+        return normalizeTokenInternal(token);
+    }
+    jwtSign(payload, secret, expiresInSeconds, options) {
+        const opts = { ...(options ?? {}), expiresIn: expiresInSeconds };
+        try {
+            const token = jwt.sign(payload, secret, opts);
+            return { success: true, token };
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    jwtVerify(token, secret, options) {
+        try {
+            const data = jwt.verify(token, secret, options ?? {});
+            return { success: true, data };
+        }
+        catch (error) {
+            if (error instanceof jwt.TokenExpiredError) {
+                return { success: false, expired: true, error: 'Token expired' };
+            }
+            return { success: false, expired: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    jwtDecode(token, options) {
+        try {
+            const data = jwt.decode(token, options ?? {});
+            if (data === null) {
+                return { success: false, error: 'Invalid token format' };
+            }
+            return { success: true, data };
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}

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

@@ -0,0 +1,19 @@
+import { TokenStore } from './base.js';
+import type { Token } from './types.js';
+export declare class MemoryTokenStore extends TokenStore {
+    private readonly tokens;
+    save(record: Token): Promise<void>;
+    get(query: Partial<Token>, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    delete(query: Partial<Token>): Promise<number>;
+    update(params: Partial<Token> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    list(userId: string | number, opts?: {
+        limit?: number;
+        offset?: number;
+        includeExpired?: boolean;
+    }): Promise<Token[]>;
+    close(): Promise<void>;
+}

package/dist/esm/token/memory.js

@@ -0,0 +1,145 @@
+import { TokenStore } from './base.js';
+function comparableUserId(value) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return String(value);
+}
+function cloneToken(record) {
+    // this.normalizeToken is not available in static context; caller passes through instance.
+    // cloning handled via store instance methods.
+    const normalized = record;
+    return {
+        ...normalized,
+        scope: normalized.scope ? [...normalized.scope] : undefined
+    };
+}
+function matchesQuery(record, query, includeExpired) {
+    if (query.refreshToken && record.refreshToken !== query.refreshToken) {
+        return false;
+    }
+    if (query.accessToken && record.accessToken !== query.accessToken) {
+        return false;
+    }
+    if (query.userId !== undefined && comparableUserId(record.userId) !== comparableUserId(query.userId)) {
+        return false;
+    }
+    if (query.clientId && record.clientId !== query.clientId) {
+        return false;
+    }
+    if (query.domain !== undefined && (record.domain ?? '') !== (query.domain ?? '')) {
+        return false;
+    }
+    if (query.fingerprint !== undefined && (record.fingerprint ?? '') !== (query.fingerprint ?? '')) {
+        return false;
+    }
+    if (query.loginType !== undefined && record.loginType !== (query.loginType ?? undefined)) {
+        return false;
+    }
+    if (query.label && record.label !== query.label) {
+        return false;
+    }
+    if (!includeExpired && (record.expires ?? new Date(0)).getTime() < Date.now()) {
+        return false;
+    }
+    return true;
+}
+export class MemoryTokenStore extends TokenStore {
+    constructor() {
+        super(...arguments);
+        this.tokens = [];
+    }
+    async save(record) {
+        const stored = this.normalizeToken(record);
+        const normalizedUserId = comparableUserId(stored.userId);
+        const domainProvided = record.domain !== undefined;
+        const fingerprintProvided = record.fingerprint !== undefined;
+        for (let index = this.tokens.length - 1; index >= 0; index -= 1) {
+            const existing = this.tokens[index];
+            if (comparableUserId(existing.userId) !== normalizedUserId) {
+                continue;
+            }
+            if (record.clientId && existing.clientId !== record.clientId) {
+                continue;
+            }
+            if (domainProvided && existing.domain !== stored.domain) {
+                continue;
+            }
+            if (fingerprintProvided && existing.fingerprint !== stored.fingerprint) {
+                continue;
+            }
+            this.tokens.splice(index, 1);
+        }
+        this.tokens.push(stored);
+    }
+    async get(query, opts) {
+        if (!query.refreshToken && !query.accessToken && query.userId === undefined) {
+            throw new Error('At least one token lookup field must be provided');
+        }
+        const includeExpired = opts?.includeExpired ?? false;
+        const record = this.tokens.find((token) => matchesQuery(token, query, includeExpired));
+        return record ? cloneToken(record) : null;
+    }
+    async delete(query) {
+        if (!query.refreshToken && !query.accessToken && query.userId === undefined && !query.clientId) {
+            return 0;
+        }
+        let removed = 0;
+        for (let index = this.tokens.length - 1; index >= 0; index -= 1) {
+            if (matchesQuery(this.tokens[index], query, true)) {
+                this.tokens.splice(index, 1);
+                removed += 1;
+            }
+        }
+        return removed;
+    }
+    async update(params) {
+        const token = this.tokens.find((record) => {
+            if (record.refreshToken !== params.refreshToken) {
+                return false;
+            }
+            if (params.clientId && record.clientId !== params.clientId) {
+                return false;
+            }
+            return true;
+        });
+        if (!token) {
+            return false;
+        }
+        const merged = { ...token };
+        const maybeAssign = (key) => {
+            const value = params[key];
+            if (value !== undefined) {
+                merged[key] = value;
+            }
+        };
+        maybeAssign('accessToken');
+        maybeAssign('expires');
+        maybeAssign('scope');
+        maybeAssign('label');
+        maybeAssign('domain');
+        maybeAssign('fingerprint');
+        maybeAssign('browser');
+        maybeAssign('device');
+        maybeAssign('ip');
+        maybeAssign('os');
+        maybeAssign('refreshTtlSeconds');
+        maybeAssign('loginType');
+        maybeAssign('issuedAt');
+        maybeAssign('lastSeenAt');
+        maybeAssign('sessionCookie');
+        const normalized = this.normalizeToken(merged);
+        Object.assign(token, normalized);
+        return true;
+    }
+    async list(userId, opts = {}) {
+        const includeExpired = opts.includeExpired ?? false;
+        const filtered = this.tokens.filter((token) => matchesQuery(token, { userId: comparableUserId(userId) }, includeExpired));
+        const offset = opts.offset ?? 0;
+        const limit = opts.limit ?? filtered.length;
+        return filtered.slice(offset, offset + limit).map(cloneToken);
+    }
+    async close() {
+        return;
+    }
+}

package/dist/esm/token/sequelize.d.ts

@@ -0,0 +1,58 @@
+import { CreationOptional, Model, type InferAttributes, type InferCreationAttributes, type ModelStatic, type Sequelize } from 'sequelize';
+import { TokenStore } from './base.js';
+import type { Token } from './types.js';
+declare class TokenModel extends Model<InferAttributes<TokenModel>, InferCreationAttributes<TokenModel>> implements InferAttributes<TokenModel> {
+    token_id: CreationOptional<number>;
+    user_id: string;
+    real_user_id: CreationOptional<string | null>;
+    expires: Date;
+    issued_at: CreationOptional<Date>;
+    last_seen_at: CreationOptional<Date>;
+    access: string;
+    refresh: string;
+    domain: CreationOptional<string>;
+    fingerprint: CreationOptional<string>;
+    label: CreationOptional<string>;
+    browser: CreationOptional<string>;
+    device: CreationOptional<string>;
+    ip: CreationOptional<string>;
+    os: CreationOptional<string>;
+    client_id: CreationOptional<string | null>;
+    scope: CreationOptional<string>;
+    login_type: CreationOptional<string>;
+    refresh_ttl_seconds: CreationOptional<number | null>;
+    session_cookie: CreationOptional<boolean>;
+}
+export type TokenAttributes = InferAttributes<TokenModel>;
+export type TokenCreationAttributes = InferCreationAttributes<TokenModel>;
+export interface SequelizeTokenStoreOptions {
+    sequelize: Sequelize;
+    tokenModel?: ModelStatic<TokenModel>;
+    tokenModelFactory?: (sequelize: Sequelize) => ModelStatic<TokenModel>;
+}
+export declare class SequelizeTokenStore extends TokenStore {
+    readonly Tokens: ModelStatic<TokenModel>;
+    constructor(options: SequelizeTokenStoreOptions);
+    save(record: Token): Promise<void>;
+    get(query: Partial<Token>, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    delete(query: Partial<Token>): Promise<number>;
+    update(params: Partial<Token> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    list(userId: string | number, opts?: {
+        limit?: number;
+        offset?: number;
+        includeExpired?: boolean;
+    }): Promise<Token[]>;
+    close(): Promise<void>;
+    private normalizeUserId;
+    private resolveRealUserId;
+    private encodeStringArray;
+    private decodeStringArray;
+    private encodeScope;
+    private decodeScope;
+    private toTokenRecord;
+}
+export {};