@technomoron/apicore-server 1.0.0-beta.1

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

@@ -0,0 +1,116 @@
+import { type ApiRequest, type ApiRoute, type ApiServer } from '../apicore-server.js';
+import { BaseAuthModule, type AuthProviderModule } from './module.js';
+import type { AuthAdapter, AuthIdentifier } from './types.js';
+import type { OAuthCallbackParams, OAuthCallbackResult, OAuthStartParams, OAuthStartResult } from '../oauth/types.js';
+import type { TokenPair, Token } from '../token/types.js';
+interface CanImpersonateContext<UserEntity> {
+    apiReq: ApiRequest;
+    realUser: UserEntity;
+    realUserId: AuthIdentifier;
+    targetUser: UserEntity;
+    effectiveUserId: AuthIdentifier;
+}
+type AuthRateLimitEndpoint = 'login' | 'passkey-challenge' | 'oauth-token' | 'oauth-authorize';
+interface AuthModuleOptions<UserEntity> {
+    namespace?: string;
+    defaultDomain?: string;
+    canImpersonate?: (context: CanImpersonateContext<UserEntity>) => Promise<boolean> | boolean;
+    rateLimit?: (context: {
+        apiReq: ApiRequest;
+        endpoint: AuthRateLimitEndpoint;
+    }) => Promise<void> | void;
+    allowInsecurePkcePlain?: boolean;
+}
+type TokenMetadata = Partial<Token> & {
+    sessionCookie?: boolean;
+};
+interface TokenIssueOptions extends TokenMetadata {
+    expires?: Date;
+    sessionCookie?: boolean;
+}
+interface NormalizedTokenMetadata extends TokenMetadata {
+    domain: string;
+    fingerprint: string;
+    label: string;
+    browser: string;
+    device: string;
+    ip: string;
+    os: string;
+}
+type TokenClaims = TokenMetadata & {
+    uid: string;
+    exp?: number;
+    iat?: number;
+};
+type AuthCapableServer<PublicUser> = ApiServer & {
+    initiateOAuth?: (params: OAuthStartParams) => Promise<OAuthStartResult>;
+    completeOAuth?: (params: OAuthCallbackParams) => Promise<OAuthCallbackResult<PublicUser>>;
+};
+export default class AuthModule<UserEntity, PublicUser> extends BaseAuthModule<UserEntity> implements AuthProviderModule<UserEntity> {
+    static defaultNamespace: string;
+    get server(): AuthCapableServer<PublicUser>;
+    set server(value: AuthCapableServer<PublicUser>);
+    private readonly defaultDomain?;
+    private readonly canImpersonateHook?;
+    private readonly rateLimitHook?;
+    private readonly allowInsecurePkcePlain;
+    constructor(options?: AuthModuleOptions<UserEntity>);
+    protected get storage(): AuthAdapter<UserEntity, PublicUser>;
+    protected canImpersonate(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<boolean>;
+    protected ensureImpersonationAllowed(apiReq: ApiRequest, realUser: UserEntity, targetUser: UserEntity): Promise<void>;
+    protected buildTokenPayload(user: UserEntity, metadata?: TokenMetadata): TokenClaims;
+    protected buildTokenMetadata(metadata?: TokenMetadata): NormalizedTokenMetadata;
+    protected enrichTokenMetadata(apiReq: ApiRequest, metadata?: TokenMetadata): TokenMetadata;
+    private sessionRefreshTtlSeconds;
+    private normalizeRefreshTtlSeconds;
+    private resolveSessionPreferences;
+    private mergeSessionPreferences;
+    private sessionPrefsFromRecord;
+    private validateCredentialId;
+    private normalizeCredentialId;
+    private toIsoDate;
+    private cookieOptions;
+    private setJwtCookies;
+    issueTokens(apiReq: ApiRequest, user: UserEntity, metadata?: TokenIssueOptions): Promise<TokenPair>;
+    private assertAuthReady;
+    private parseLoginBody;
+    private parseImpersonationRequest;
+    private resolveImpersonationIdentifier;
+    private buildImpersonationMetadata;
+    private getUserOrThrow;
+    private getRealUserIdentifier;
+    private resolveActorContext;
+    private extractRefreshToken;
+    private normalizeScope;
+    private postLogin;
+    private postRefresh;
+    private postLogout;
+    private postWhoAmI;
+    private postPasskeyChallenge;
+    private postPasskeyVerify;
+    private getPasskeys;
+    private deletePasskey;
+    private postImpersonation;
+    private deleteImpersonation;
+    private getUserFromPasskey;
+    private postOAuthStart;
+    private postOAuthCallback;
+    private postOAuthAuthorize;
+    private postOAuthToken;
+    private handleAuthorizationCodeGrant;
+    private handleRefreshTokenGrant;
+    private clearOAuthCookies;
+    private buildTokenResponse;
+    private resolveScope;
+    private resolveClientAuthentication;
+    private assertRedirectUriAllowed;
+    private resolveUserForOAuth;
+    private hasPasskeyService;
+    private hasOAuthStore;
+    private storageImplements;
+    private storageImplementsAll;
+    private applyRateLimit;
+    private resolvePkceChallengeMethod;
+    defineRoutes(): ApiRoute[];
+}
+export {};

package/dist/cjs/auth-api/compat-auth-storage.cjs

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompositeAuthAdapter = void 0;
+const node_crypto_1 = require("node:crypto");
+const service_js_1 = require("../passkey/service.cjs");
+class CompositeAuthAdapter {
+    constructor(options) {
+        this.userStore = options.userStore;
+        this.tokenStore = options.tokenStore;
+        this.oauthStore = options.oauthStore;
+        this.canImpersonateFn = options.canImpersonate;
+        if (options.passkeys instanceof service_js_1.PasskeyService) {
+            this.passkeyService = options.passkeys;
+        }
+        else if (options.passkeys) {
+            this.passkeyService = new service_js_1.PasskeyService(options.passkeys.config, options.passkeys.store);
+        }
+    }
+    async getUser(identifier) {
+        return this.userStore.findUser(identifier);
+    }
+    getUserPasswordHash(user) {
+        return this.userStore.getPasswordHash(user) ?? '';
+    }
+    getUserId(user) {
+        return this.userStore.getUserId(user);
+    }
+    filterUser(user) {
+        return this.userStore.toPublic(user);
+    }
+    async verifyPassword(password, hash) {
+        return this.userStore.verifyPassword(password, hash);
+    }
+    async storeToken(data) {
+        return this.tokenStore.save(data);
+    }
+    async getToken(query, opts) {
+        return this.tokenStore.get(query, opts);
+    }
+    async deleteToken(query) {
+        return this.tokenStore.delete(query);
+    }
+    async updateToken(updates) {
+        return this.tokenStore.update(updates);
+    }
+    async createPasskeyChallenge(params) {
+        if (!this.passkeyService) {
+            throw new Error('Passkey storage is not configured');
+        }
+        return this.passkeyService.createChallenge(params);
+    }
+    async verifyPasskeyResponse(params) {
+        if (!this.passkeyService) {
+            throw new Error('Passkey storage is not configured');
+        }
+        return this.passkeyService.verifyResponse(params);
+    }
+    async listUserCredentials(userId) {
+        if (!this.passkeyService) {
+            throw new Error('Passkey storage is not configured');
+        }
+        return this.passkeyService.listUserCredentials(userId);
+    }
+    async deletePasskeyCredential(credentialId) {
+        if (!this.passkeyService) {
+            throw new Error('Passkey storage is not configured');
+        }
+        return this.passkeyService.deleteCredential(credentialId);
+    }
+    async getClient(clientId) {
+        if (!this.oauthStore) {
+            return null;
+        }
+        return this.oauthStore.getClient(clientId);
+    }
+    async verifyClientSecret(client, clientSecret) {
+        if (!this.oauthStore) {
+            throw new Error('OAuth storage is not configured');
+        }
+        return this.oauthStore.verifyClientSecret(client.clientId, clientSecret);
+    }
+    async createAuthCode(request) {
+        if (!this.oauthStore) {
+            throw new Error('OAuth storage is not configured');
+        }
+        const expiresAt = new Date(Date.now() + (request.expiresInSeconds ?? 300) * 1000);
+        const code = request.code ?? (0, node_crypto_1.randomUUID)();
+        await this.oauthStore.createAuthCode({
+            code,
+            clientId: request.clientId,
+            userId: request.userId,
+            scope: request.scope,
+            redirectUri: request.redirectUri,
+            codeChallenge: request.codeChallenge,
+            codeChallengeMethod: request.codeChallengeMethod,
+            expiresAt,
+            metadata: request.metadata
+        });
+        return {
+            code,
+            clientId: request.clientId,
+            userId: request.userId,
+            redirectUri: request.redirectUri,
+            scope: request.scope ?? [],
+            codeChallenge: request.codeChallenge,
+            codeChallengeMethod: request.codeChallengeMethod,
+            expiresAt,
+            metadata: request.metadata
+        };
+    }
+    async consumeAuthCode(code, clientId) {
+        if (!this.oauthStore) {
+            return null;
+        }
+        const consumed = await this.oauthStore.consumeAuthCode(code, clientId);
+        if (!consumed) {
+            return null;
+        }
+        return consumed;
+    }
+    async canImpersonate(params) {
+        if (this.canImpersonateFn) {
+            return !!(await this.canImpersonateFn(params));
+        }
+        return String(params.realUserId) === String(params.effectiveUserId);
+    }
+}
+exports.CompositeAuthAdapter = CompositeAuthAdapter;

package/dist/cjs/auth-api/compat-auth-storage.d.ts

@@ -0,0 +1,57 @@
+import { PasskeyService } from '../passkey/service.js';
+import type { AuthAdapter, AuthIdentifier } from './types.js';
+import type { OAuthStore } from '../oauth/base.js';
+import type { AuthCodeData, AuthCodeRequest, OAuthClient } from '../oauth/types.js';
+import type { PasskeyStore } from '../passkey/base.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, PasskeyServiceConfig, StoredPasskeyCredential, PasskeyVerificationParams, PasskeyVerificationResult } from '../passkey/types.js';
+import type { TokenStore } from '../token/base.js';
+import type { Token } from '../token/types.js';
+import type { UserStore } from '../user/base.js';
+interface PasskeyAdapterOptions {
+    store: PasskeyStore;
+    config: PasskeyServiceConfig;
+}
+export interface AuthAdapterOptions<UserRow, PublicUser> {
+    userStore: UserStore<UserRow, PublicUser>;
+    tokenStore: TokenStore;
+    passkeys?: PasskeyAdapterOptions | PasskeyService;
+    oauthStore?: OAuthStore;
+    canImpersonate?: (params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }) => boolean | Promise<boolean>;
+}
+export declare class CompositeAuthAdapter<UserRow, PublicUser> implements AuthAdapter<UserRow, PublicUser> {
+    private readonly userStore;
+    private readonly tokenStore;
+    private readonly oauthStore?;
+    private readonly passkeyService?;
+    private readonly canImpersonateFn?;
+    constructor(options: AuthAdapterOptions<UserRow, PublicUser>);
+    getUser(identifier: AuthIdentifier): Promise<UserRow | null>;
+    getUserPasswordHash(user: UserRow): string;
+    getUserId(user: UserRow): AuthIdentifier;
+    filterUser(user: UserRow): PublicUser;
+    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>;
+}
+export {};

package/dist/cjs/auth-api/mem-auth-store.cjs

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemAuthStore = void 0;
+const memory_js_1 = require("../oauth/memory.cjs");
+const config_js_1 = require("../passkey/config.cjs");
+const memory_js_2 = require("../passkey/memory.cjs");
+const memory_js_3 = require("../token/memory.cjs");
+const memory_js_4 = require("../user/memory.cjs");
+const compat_auth_storage_js_1 = require("./compat-auth-storage.cjs");
+const user_id_js_1 = require("./user-id.cjs");
+class MemAuthStore {
+    constructor(params = {}) {
+        this.userStore = new memory_js_4.MemoryUserStore({
+            toPublic: params.publicUserMapper ?? params.toPublic,
+            userIdFactory: params.userIdFactory,
+            startingUserId: params.startingUserId,
+            bcryptRounds: params.bcryptRounds,
+            bcryptPepper: params.passwordPepper
+        });
+        this.tokenStore = params.tokenStore ?? new memory_js_3.MemoryTokenStore();
+        this.oauthStore = new memory_js_1.MemoryOAuthStore({ bcryptRounds: params.bcryptRounds });
+        let passkeyStore;
+        let passkeyConfig;
+        if (params.passkeys !== false) {
+            passkeyConfig = (0, config_js_1.normalizePasskeyConfig)(params.passkeys ?? {});
+            const resolveUser = async (lookup) => {
+                const found = await this.userStore.findUser(lookup.userId ?? lookup.login ?? '');
+                if (!found) {
+                    return null;
+                }
+                const mapper = params.passkeyUserMapper ??
+                    ((user) => ({
+                        id: user.user_id,
+                        login: user.login,
+                        displayName: user.login
+                    }));
+                return mapper(found);
+            };
+            passkeyStore = new memory_js_2.MemoryPasskeyStore({ resolveUser });
+            this.passkeyStore = passkeyStore;
+        }
+        this.adapter = new compat_auth_storage_js_1.CompositeAuthAdapter({
+            userStore: this.userStore,
+            tokenStore: this.tokenStore,
+            passkeys: passkeyStore && passkeyConfig ? { store: passkeyStore, config: passkeyConfig } : undefined,
+            oauthStore: this.oauthStore,
+            canImpersonate: params.canImpersonate
+        });
+    }
+    async initialise() {
+        return;
+    }
+    async close() {
+        return;
+    }
+    async getUser(identifier) {
+        return this.adapter.getUser(identifier);
+    }
+    getUserPasswordHash(user) {
+        return this.adapter.getUserPasswordHash(user);
+    }
+    getUserId(user) {
+        return this.adapter.getUserId(user);
+    }
+    filterUser(user) {
+        return this.adapter.filterUser(user);
+    }
+    async verifyPassword(password, hash) {
+        return this.adapter.verifyPassword(password, hash);
+    }
+    async storeToken(data) {
+        return this.adapter.storeToken(data);
+    }
+    async getToken(query, opts) {
+        const normalized = {
+            ...query,
+            userId: (0, user_id_js_1.toOptionalStringId)(query.userId),
+            ruid: (0, user_id_js_1.toOptionalStringId)(query.ruid)
+        };
+        return this.adapter.getToken(normalized, opts);
+    }
+    async deleteToken(query) {
+        const normalized = {
+            ...query,
+            userId: (0, user_id_js_1.toOptionalStringId)(query.userId),
+            ruid: (0, user_id_js_1.toOptionalStringId)(query.ruid)
+        };
+        return this.adapter.deleteToken(normalized);
+    }
+    async updateToken(updates) {
+        return this.adapter.updateToken(updates);
+    }
+    async createPasskeyChallenge(params) {
+        return this.adapter.createPasskeyChallenge(params);
+    }
+    async verifyPasskeyResponse(params) {
+        return this.adapter.verifyPasskeyResponse(params);
+    }
+    async listUserCredentials(userId) {
+        return this.adapter.listUserCredentials(userId);
+    }
+    async deletePasskeyCredential(credentialId) {
+        return this.adapter.deletePasskeyCredential(credentialId);
+    }
+    async getClient(clientId) {
+        return this.adapter.getClient(clientId);
+    }
+    async verifyClientSecret(client, clientSecret) {
+        return this.adapter.verifyClientSecret(client, clientSecret);
+    }
+    async createAuthCode(request) {
+        return this.adapter.createAuthCode(request);
+    }
+    async consumeAuthCode(code, clientId) {
+        return this.adapter.consumeAuthCode(code, clientId);
+    }
+    async canImpersonate(params) {
+        return this.adapter.canImpersonate(params);
+    }
+}
+exports.MemAuthStore = MemAuthStore;

package/dist/cjs/auth-api/mem-auth-store.d.ts

@@ -0,0 +1,68 @@
+import { MemoryOAuthStore } from '../oauth/memory.js';
+import { MemoryPasskeyStore } from '../passkey/memory.js';
+import { TokenStore } from '../token/base.js';
+import { MemoryUserStore } from '../user/memory.js';
+import type { AuthAdapter, AuthIdentifier } from './types.js';
+import type { MemoryOAuthStoreOptions } from '../oauth/memory.js';
+import type { AuthCodeData, AuthCodeRequest, OAuthClient } from '../oauth/types.js';
+import type { MemoryPasskeyStoreOptions } from '../passkey/memory.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, PasskeyServiceConfig, PasskeyUserDescriptor, StoredPasskeyCredential, PasskeyVerificationParams, PasskeyVerificationResult } from '../passkey/types.js';
+import type { Token } from '../token/types.js';
+import type { MemoryUserAttributes, MemoryPublicUser, MemoryUserStoreOptions } from '../user/memory.js';
+interface PasskeyOptions extends Partial<PasskeyServiceConfig> {
+    enabled?: boolean;
+}
+export interface MemAuthStoreParams<UserAttributes extends MemoryUserAttributes = MemoryUserAttributes, PublicUserShape extends MemoryPublicUser<UserAttributes> = MemoryPublicUser<UserAttributes>> extends Omit<MemoryUserStoreOptions<UserAttributes, PublicUserShape>, 'hasher'>, MemoryOAuthStoreOptions, Partial<MemoryPasskeyStoreOptions> {
+    bcryptRounds?: number;
+    passwordPepper?: string;
+    publicUserMapper?: (user: UserAttributes) => PublicUserShape;
+    passkeyUserMapper?: (user: UserAttributes) => PasskeyUserDescriptor;
+    passkeys?: false | PasskeyOptions;
+    canImpersonate?: (params: {
+        realUserId: AuthIdentifier;
+        effectiveUserId: AuthIdentifier;
+    }) => boolean | Promise<boolean>;
+    tokenStore?: TokenStore;
+}
+export declare class MemAuthStore<UserAttributes extends MemoryUserAttributes = MemoryUserAttributes, PublicUserShape extends MemoryPublicUser<UserAttributes> = MemoryPublicUser<UserAttributes>> implements AuthAdapter<UserAttributes, PublicUserShape> {
+    readonly userStore: MemoryUserStore<UserAttributes, PublicUserShape>;
+    readonly tokenStore: TokenStore;
+    readonly passkeyStore?: MemoryPasskeyStore;
+    readonly oauthStore: MemoryOAuthStore;
+    private readonly adapter;
+    constructor(params?: MemAuthStoreParams<UserAttributes, PublicUserShape>);
+    initialise(): Promise<void>;
+    close(): Promise<void>;
+    getUser(identifier: AuthIdentifier): Promise<UserAttributes | null>;
+    getUserPasswordHash(user: UserAttributes): string;
+    getUserId(user: UserAttributes): AuthIdentifier;
+    filterUser(user: UserAttributes): PublicUserShape;
+    verifyPassword(password: string, hash: string): Promise<boolean>;
+    storeToken(data: Token): Promise<void>;
+    getToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }, opts?: {
+        includeExpired?: boolean;
+    }): Promise<Token | null>;
+    deleteToken(query: Partial<Token> & {
+        userId?: AuthIdentifier;
+        ruid?: AuthIdentifier;
+    }): 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 {};

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nullAuthModule = exports.BaseAuthModule = void 0;
+const api_module_js_1 = require("../api-module.cjs");
+// Handy base that you can extend when wiring a real auth module. Subclasses
+// must supply a namespace via the constructor and implement token issuance.
+class BaseAuthModule extends api_module_js_1.ApiModule {
+    constructor(opts) {
+        super(opts);
+        this.moduleType = 'auth';
+    }
+}
+exports.BaseAuthModule = BaseAuthModule;
+class NullAuthModule extends BaseAuthModule {
+    constructor() {
+        super({ namespace: '__null__' });
+    }
+    async issueTokens(apiReq, user, metadata) {
+        void apiReq;
+        void user;
+        void metadata;
+        throw new Error('Auth module not configured. Inject a real auth module before issuing tokens.');
+    }
+}
+exports.nullAuthModule = new NullAuthModule();

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

@@ -0,0 +1,20 @@
+import { ApiModule } from '../api-module.js';
+import type { ApiRequest } from '../apicore-server.js';
+import type { Token, TokenPair } from '../token/types.js';
+export interface AuthProviderModule<UserRow = unknown> {
+    readonly moduleType: 'auth';
+    readonly namespace: string;
+    issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: Partial<Token> & {
+        expires?: Date;
+    }): Promise<TokenPair>;
+}
+export declare abstract class BaseAuthModule<UserRow = unknown> extends ApiModule implements AuthProviderModule<UserRow> {
+    readonly moduleType: "auth";
+    protected constructor(opts: {
+        namespace: string;
+    });
+    abstract issueTokens(apiReq: ApiRequest, user: UserRow, metadata?: Partial<Token> & {
+        expires?: Date;
+    }): Promise<TokenPair>;
+}
+export declare const nullAuthModule: AuthProviderModule<unknown>;