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

package/dist/esm/auth-api/storage.d.ts

@@ -0,0 +1,38 @@
+import type { AuthAdapter, AuthIdentifier } from './types.js';
+import type { AuthCodeData, AuthCodeRequest, OAuthClient } from '../oauth/types.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, PasskeyVerificationParams, PasskeyVerificationResult, StoredPasskeyCredential } from '../passkey/types.js';
+import type { Token } from '../token/types.js';
+export declare class BaseAuthAdapter<UserRow = unknown, SafeUser = unknown> implements AuthAdapter<UserRow, SafeUser> {
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): SafeUser;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: Token): Promise<void>;
+    getToken(query: Partial<Omit<Token, 'userId' | 'ruid'>> & {
+        userId?: string | number;
+        ruid?: string | number;
+    }, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    deleteToken(query: Partial<Omit<Token, 'userId' | 'ruid'>> & {
+        userId?: string | number;
+        ruid?: string | number;
+    }): Promise<number>;
+    updateToken(updates: Partial<Token> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    createPasskeyChallenge(params: PasskeyChallengeParams): Promise<PasskeyChallenge>;
+    verifyPasskeyResponse(params: PasskeyVerificationParams): Promise<PasskeyVerificationResult>;
+    listUserCredentials(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
+    deletePasskeyCredential(credentialId: Buffer | string): Promise<boolean>;
+    getClient(clientId: string): Promise<OAuthClient | null>;
+    verifyClientSecret(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
+    createAuthCode(request: AuthCodeRequest): Promise<AuthCodeData>;
+    consumeAuthCode(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
+}
+export declare const nullAuthAdapter: AuthAdapter<unknown, unknown>;

package/dist/esm/{auth-storage.js → auth-api/storage.js}

@@ -1,7 +1,6 @@
-// Numeric database id or lookup string such as username/email.
-// Handy base you can extend when wiring a real storage adapter. Every method
+// Handy base you can extend when wiring a real auth adapter. Every method
 // throws by default so unimplemented hooks fail loudly.
-export class BaseAuthStorage {
+export class BaseAuthAdapter {
     // Override to load a user record by identifier
     async getUser(identifier) {
         void identifier;
@@ -33,8 +32,9 @@ export class BaseAuthStorage {
         throw new Error('Auth storage not configured');
     }
     // Override to look up a stored token by query
-    async getToken(query) {
+    async getToken(query, opts) {
         void query;
+        void opts;
         return null;
     }
     // Override to remove stored tokens that match the query
@@ -57,6 +57,16 @@ export class BaseAuthStorage {
         void params;
         throw new Error('Auth storage not configured');
     }
+    // Override to list passkey credentials for a user
+    async listUserCredentials(userId) {
+        void userId;
+        throw new Error('Auth storage not configured');
+    }
+    // Override to delete a passkey credential
+    async deletePasskeyCredential(credentialId) {
+        void credentialId;
+        throw new Error('Auth storage not configured');
+    }
     // Override to fetch an OAuth client by identifier
     async getClient(clientId) {
         void clientId;
@@ -85,4 +95,4 @@ export class BaseAuthStorage {
         return false;
     }
 }
-export const nullAuthStorage = new BaseAuthStorage();
+export const nullAuthAdapter = new BaseAuthAdapter();

package/dist/esm/auth-api/types.d.ts

@@ -0,0 +1,34 @@
+import type { AuthCodeData, AuthCodeRequest, OAuthClient } from '../oauth/types.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, PasskeyVerificationParams, PasskeyVerificationResult, StoredPasskeyCredential } from '../passkey/types.js';
+import type { Token } from '../token/types.js';
+export type AuthIdentifier = string | number;
+/** @internal */
+export interface AuthAdapter<UserRow, SafeUser> {
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): SafeUser;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: Token): Promise<void>;
+    getToken(query: Partial<Token>, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    deleteToken(query: Partial<Token>): Promise<number>;
+    updateToken?(updates: Partial<Token> & {
+        refreshToken: string;
+    }): Promise<boolean>;
+    createPasskeyChallenge?(params: PasskeyChallengeParams): Promise<PasskeyChallenge>;
+    verifyPasskeyResponse?(params: PasskeyVerificationParams): Promise<PasskeyVerificationResult>;
+    listUserCredentials?(userId: AuthIdentifier): Promise<StoredPasskeyCredential[]>;
+    deletePasskeyCredential?(credentialId: Buffer | string): Promise<boolean>;
+    getClient?(clientId: string): Promise<OAuthClient | null>;
+    verifyClientSecret?(client: OAuthClient, clientSecret: string | null): Promise<boolean>;
+    createAuthCode?(request: AuthCodeRequest): Promise<AuthCodeData>;
+    consumeAuthCode?(code: string, clientId: string): Promise<AuthCodeData | null>;
+    canImpersonate?(params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }): Promise<boolean>;
+}
+/** @internal */
+export type AuthStorage<UserRow, SafeUser> = AuthAdapter<UserRow, SafeUser>;

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

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

package/dist/esm/index.d.ts

@@ -1,8 +1,32 @@
 export { default as ApiServer } from './api-server-base.js';
 export { ApiError } from './api-server-base.js';
 export { ApiModule } from './api-module.js';
-export type { ApiErrorParams, ApiHandler, ApiKey, ApiServerConf, ApiRequest, ApiRoute, ApiAuthType, ApiAuthClass, ApiTokenData, RequestWithStuff } from './api-server-base.js';
-export type { AuthIdentifier, AuthTokenMetadata, AuthTokenData, AuthTokenQuery, AuthTokenPair, AuthTokenPayload, PasskeyChallengeParams, PasskeyChallenge, PasskeyVerificationParams, PasskeyVerificationResult, OAuthClient, AuthCodeData, AuthCodeRequest, AuthStorage } from './auth-storage.js';
-export type { AuthProviderModule } from './auth-module.js';
-export { nullAuthStorage, BaseAuthStorage } from './auth-storage.js';
-export { nullAuthModule, BaseAuthModule } from './auth-module.js';
+export type { ApiErrorParams, ApiHandler, ApiKey, ApiServerConf, ApiRequest, ApiRoute, ApiAuthType, ApiAuthClass, ApiTokenData, ExtendedReq, ExpressApiRequest, ExpressApiLocals } from './api-server-base.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 { SqlAuthStore } from './auth-api/sql-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 { SequelizeUserStore } from './user/sequelize.js';
+export type { MemoryUserAttributes, MemoryUserStoreOptions } from './user/memory.js';
+export { TokenStore } from './token/base.js';
+export { MemoryTokenStore } from './token/memory.js';
+export { SequelizeTokenStore } from './token/sequelize.js';
+export { PasskeyService } from './passkey/service.js';
+export { PasskeyStore } from './passkey/base.js';
+export { MemoryPasskeyStore } from './passkey/memory.js';
+export { SequelizePasskeyStore } from './passkey/sequelize.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 { SequelizeOAuthStore } from './oauth/sequelize.js';

package/dist/esm/index.js

@@ -1,5 +1,22 @@
 export { default as ApiServer } from './api-server-base.js';
 export { ApiError } from './api-server-base.js';
 export { ApiModule } from './api-module.js';
-export { nullAuthStorage, BaseAuthStorage } from './auth-storage.js';
-export { nullAuthModule, BaseAuthModule } from './auth-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 { SqlAuthStore } from './auth-api/sql-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 { SequelizeUserStore } from './user/sequelize.js';
+export { TokenStore } from './token/base.js';
+export { MemoryTokenStore } from './token/memory.js';
+export { SequelizeTokenStore } from './token/sequelize.js';
+export { PasskeyService } from './passkey/service.js';
+export { PasskeyStore } from './passkey/base.js';
+export { MemoryPasskeyStore } from './passkey/memory.js';
+export { SequelizePasskeyStore } from './passkey/sequelize.js';
+export { OAuthStore } from './oauth/base.js';
+export { MemoryOAuthStore } from './oauth/memory.js';
+export { SequelizeOAuthStore } from './oauth/sequelize.js';

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

@@ -0,0 +1,10 @@
+import type { AuthCode, OAuthClient } from './types.js';
+export declare abstract class OAuthStore {
+    abstract getClient(clientId: string): Promise<OAuthClient | null>;
+    abstract createClient(input: OAuthClient): Promise<OAuthClient>;
+    abstract verifyClientSecret(clientId: string, secret: string | null): Promise<boolean>;
+    abstract createAuthCode(code: AuthCode): Promise<void>;
+    abstract consumeAuthCode(code: string): Promise<AuthCode | null>;
+    abstract close(): Promise<void>;
+}
+export type { OAuthClient, AuthCode } from './types.js';

package/dist/esm/oauth/base.js

@@ -0,0 +1,2 @@
+export class OAuthStore {
+}

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

@@ -0,0 +1,16 @@
+import { OAuthStore, type AuthCode, type OAuthClient } from './base.js';
+export interface MemoryOAuthStoreOptions {
+    bcryptRounds?: number;
+}
+export declare class MemoryOAuthStore extends OAuthStore {
+    private readonly clients;
+    private readonly codes;
+    private readonly bcryptRounds;
+    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): Promise<AuthCode | null>;
+    close(): Promise<void>;
+}

package/dist/esm/oauth/memory.js

@@ -0,0 +1,92 @@
+import bcrypt from 'bcryptjs';
+import { OAuthStore } from './base.js';
+function cloneClient(client) {
+    if (!client) {
+        return null;
+    }
+    return {
+        clientId: client.clientId,
+        clientSecret: client.clientSecret,
+        name: client.name,
+        redirectUris: [...client.redirectUris],
+        scope: client.scope ? [...client.scope] : undefined,
+        metadata: client.metadata ? { ...client.metadata } : undefined,
+        firstParty: client.firstParty
+    };
+}
+function cloneCode(code) {
+    return {
+        ...code,
+        scope: code.scope ? [...code.scope] : undefined,
+        expiresAt: new Date(code.expiresAt),
+        metadata: code.metadata ? { ...code.metadata } : undefined
+    };
+}
+function normalizeUserId(identifier) {
+    if (typeof identifier === 'number' && Number.isFinite(identifier)) {
+        return identifier;
+    }
+    if (typeof identifier === 'string' && /^\d+$/.test(identifier)) {
+        return Number(identifier);
+    }
+    throw new Error(`Unable to normalise user identifier: ${identifier}`);
+}
+export class MemoryOAuthStore extends OAuthStore {
+    constructor(options = {}) {
+        super();
+        this.clients = new Map();
+        this.codes = new Map();
+        this.bcryptRounds = options.bcryptRounds ?? 12;
+    }
+    async getClient(clientId) {
+        return cloneClient(this.clients.get(clientId));
+    }
+    async createClient(input) {
+        const clientSecret = input.clientSecret ? await bcrypt.hash(input.clientSecret, this.bcryptRounds) : '';
+        const stored = {
+            clientId: input.clientId,
+            clientSecret,
+            name: input.name,
+            redirectUris: [...input.redirectUris],
+            scope: input.scope ? [...input.scope] : undefined,
+            metadata: input.metadata ? { ...input.metadata } : undefined,
+            firstParty: input.firstParty
+        };
+        this.clients.set(stored.clientId, stored);
+        return cloneClient(stored);
+    }
+    async verifyClientSecret(clientId, secret) {
+        const client = this.clients.get(clientId);
+        if (!client) {
+            return false;
+        }
+        if (!client.clientSecret) {
+            return !secret || secret.length === 0;
+        }
+        if (!secret) {
+            return false;
+        }
+        return bcrypt.compare(secret, client.clientSecret);
+    }
+    async createAuthCode(code) {
+        const record = {
+            ...code,
+            userId: normalizeUserId(code.userId),
+            scope: code.scope ? [...code.scope] : undefined,
+            expiresAt: code.expiresAt,
+            metadata: code.metadata ? { ...code.metadata } : undefined
+        };
+        this.codes.set(record.code, record);
+    }
+    async consumeAuthCode(code) {
+        const record = this.codes.get(code);
+        if (!record) {
+            return null;
+        }
+        this.codes.delete(code);
+        return cloneCode(record);
+    }
+    async close() {
+        return;
+    }
+}

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

@@ -0,0 +1,45 @@
+import { Model, type Optional, type Sequelize } from 'sequelize';
+export interface OAuthClientAttributes {
+    client_id: string;
+    client_secret: string;
+    name: string | null;
+    redirect_uris: string;
+    scope: string;
+    metadata: string | null;
+    first_party: boolean;
+}
+export type OAuthClientCreationAttributes = Optional<OAuthClientAttributes, 'client_secret' | 'name' | 'scope' | 'metadata' | 'first_party'>;
+export declare class OAuthClientModel extends Model<OAuthClientAttributes, OAuthClientCreationAttributes> implements OAuthClientAttributes {
+    client_id: string;
+    client_secret: string;
+    name: string | null;
+    redirect_uris: string;
+    scope: string;
+    metadata: string | null;
+    first_party: boolean;
+}
+export declare function initOAuthClientModel(sequelize: Sequelize): typeof OAuthClientModel;
+export interface OAuthCodeAttributes {
+    code: string;
+    client_id: string;
+    user_id: number;
+    redirect_uri: string;
+    scope: string;
+    code_challenge: string | null;
+    code_challenge_method: 'plain' | 'S256' | null;
+    expires: Date;
+    metadata: string | null;
+}
+export type OAuthCodeCreationAttributes = Optional<OAuthCodeAttributes, 'code_challenge' | 'code_challenge_method' | 'metadata'>;
+export declare class OAuthCodeModel extends Model<OAuthCodeAttributes, OAuthCodeCreationAttributes> implements OAuthCodeAttributes {
+    code: string;
+    client_id: string;
+    user_id: number;
+    redirect_uri: string;
+    scope: string;
+    code_challenge: string | null;
+    code_challenge_method: 'plain' | 'S256' | null;
+    expires: Date;
+    metadata: string | null;
+}
+export declare function initOAuthCodeModel(sequelize: Sequelize): typeof OAuthCodeModel;

package/dist/esm/oauth/models.js

@@ -0,0 +1,51 @@
+import { DataTypes, Model } from 'sequelize';
+const DIALECTS_SUPPORTING_UNSIGNED = new Set(['mysql', 'mariadb']);
+function integerIdType(sequelize) {
+    return DIALECTS_SUPPORTING_UNSIGNED.has(sequelize.getDialect()) ? DataTypes.INTEGER.UNSIGNED : DataTypes.INTEGER;
+}
+function tableOptions(sequelize, tableName, extra) {
+    const opts = { sequelize, tableName };
+    if (extra) {
+        Object.assign(opts, extra);
+    }
+    if (DIALECTS_SUPPORTING_UNSIGNED.has(sequelize.getDialect())) {
+        opts.charset = 'utf8mb4';
+        opts.collate = 'utf8mb4_unicode_ci';
+    }
+    return opts;
+}
+export class OAuthClientModel extends Model {
+}
+export function initOAuthClientModel(sequelize) {
+    OAuthClientModel.init({
+        client_id: { type: DataTypes.STRING(128), allowNull: false, primaryKey: true },
+        client_secret: { type: DataTypes.STRING(255), allowNull: false, defaultValue: '' },
+        name: { type: DataTypes.STRING(128), allowNull: true, defaultValue: null },
+        redirect_uris: { type: DataTypes.TEXT, allowNull: false, defaultValue: '[]' },
+        scope: { type: DataTypes.TEXT, allowNull: false, defaultValue: '[]' },
+        metadata: { type: DataTypes.TEXT, allowNull: true, defaultValue: null },
+        first_party: { type: DataTypes.BOOLEAN, allowNull: false, defaultValue: false }
+    }, {
+        ...tableOptions(sequelize, 'oauth_clients', { timestamps: false })
+    });
+    return OAuthClientModel;
+}
+export class OAuthCodeModel extends Model {
+}
+export function initOAuthCodeModel(sequelize) {
+    const idType = integerIdType(sequelize);
+    OAuthCodeModel.init({
+        code: { type: DataTypes.STRING(128), allowNull: false, primaryKey: true },
+        client_id: { type: DataTypes.STRING(128), allowNull: false },
+        user_id: { type: idType, allowNull: false },
+        redirect_uri: { type: DataTypes.TEXT, allowNull: false },
+        scope: { type: DataTypes.TEXT, allowNull: false, defaultValue: '[]' },
+        code_challenge: { type: DataTypes.STRING(255), allowNull: true, defaultValue: null },
+        code_challenge_method: { type: DataTypes.STRING(10), allowNull: true, defaultValue: null },
+        expires: { type: DataTypes.DATE, allowNull: false },
+        metadata: { type: DataTypes.TEXT, allowNull: true, defaultValue: null }
+    }, {
+        ...tableOptions(sequelize, 'oauth_codes', { timestamps: false })
+    });
+    return OAuthCodeModel;
+}

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

@@ -0,0 +1,68 @@
+import { Model, type Optional, type Sequelize } from 'sequelize';
+import { OAuthStore, type AuthCode, type OAuthClient } from './base.js';
+export interface OAuthClientAttributes {
+    client_id: string;
+    client_secret: string;
+    name: string | null;
+    redirect_uris: string;
+    scope: string;
+    metadata: string | null;
+    first_party: boolean;
+}
+export type OAuthClientCreationAttributes = Optional<OAuthClientAttributes, 'client_secret' | 'name' | 'scope' | 'metadata' | 'first_party'>;
+export declare class OAuthClientModel extends Model<OAuthClientAttributes, OAuthClientCreationAttributes> implements OAuthClientAttributes {
+    client_id: string;
+    client_secret: string;
+    name: string | null;
+    redirect_uris: string;
+    scope: string;
+    metadata: string | null;
+    first_party: boolean;
+}
+export declare function initOAuthClientModel(sequelize: Sequelize): typeof OAuthClientModel;
+export interface OAuthCodeAttributes {
+    code: string;
+    client_id: string;
+    user_id: number;
+    redirect_uri: string;
+    scope: string;
+    code_challenge: string | null;
+    code_challenge_method: 'plain' | 'S256' | null;
+    expires: Date;
+    metadata: string | null;
+}
+export type OAuthCodeCreationAttributes = Optional<OAuthCodeAttributes, 'code_challenge' | 'code_challenge_method' | 'metadata'>;
+export declare class OAuthCodeModel extends Model<OAuthCodeAttributes, OAuthCodeCreationAttributes> implements OAuthCodeAttributes {
+    code: string;
+    client_id: string;
+    user_id: number;
+    redirect_uri: string;
+    scope: string;
+    code_challenge: string | null;
+    code_challenge_method: 'plain' | 'S256' | null;
+    expires: Date;
+    metadata: string | null;
+}
+export declare function initOAuthCodeModel(sequelize: Sequelize): typeof OAuthCodeModel;
+export interface SequelizeOAuthStoreOptions {
+    sequelize: Sequelize;
+    clientModel?: typeof OAuthClientModel;
+    codeModel?: typeof OAuthCodeModel;
+    clientModelFactory?: (sequelize: Sequelize) => typeof OAuthClientModel;
+    codeModelFactory?: (sequelize: Sequelize) => typeof OAuthCodeModel;
+    bcryptRounds?: number;
+}
+export declare class SequelizeOAuthStore extends OAuthStore {
+    private readonly clients;
+    private readonly codes;
+    private readonly bcryptRounds;
+    constructor(options: SequelizeOAuthStoreOptions);
+    getClient(clientId: string): Promise<OAuthClient | null>;
+    createClient(input: OAuthClient): Promise<OAuthClient>;
+    verifyClientSecret(clientId: string, clientSecret: string | null): Promise<boolean>;
+    createAuthCode(code: AuthCode): Promise<void>;
+    consumeAuthCode(code: string): Promise<AuthCode | null>;
+    close(): Promise<void>;
+    private toOAuthClient;
+    private toAuthCode;
+}