@technomoron/apicore-server 1.0.0-beta.1

package/dist/esm/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/esm/auth-api/compat-auth-storage.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { PasskeyService } from '../passkey/service.js';
+export class CompositeAuthAdapter {
+    constructor(options) {
+        this.userStore = options.userStore;
+        this.tokenStore = options.tokenStore;
+        this.oauthStore = options.oauthStore;
+        this.canImpersonateFn = options.canImpersonate;
+        if (options.passkeys instanceof PasskeyService) {
+            this.passkeyService = options.passkeys;
+        }
+        else if (options.passkeys) {
+            this.passkeyService = new 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 ?? 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);
+    }
+}

package/dist/esm/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/esm/auth-api/mem-auth-store.js

@@ -0,0 +1,117 @@
+import { MemoryOAuthStore } from '../oauth/memory.js';
+import { normalizePasskeyConfig } from '../passkey/config.js';
+import { MemoryPasskeyStore } from '../passkey/memory.js';
+import { MemoryTokenStore } from '../token/memory.js';
+import { MemoryUserStore } from '../user/memory.js';
+import { CompositeAuthAdapter } from './compat-auth-storage.js';
+import { toOptionalStringId } from './user-id.js';
+export class MemAuthStore {
+    constructor(params = {}) {
+        this.userStore = new MemoryUserStore({
+            toPublic: params.publicUserMapper ?? params.toPublic,
+            userIdFactory: params.userIdFactory,
+            startingUserId: params.startingUserId,
+            bcryptRounds: params.bcryptRounds,
+            bcryptPepper: params.passwordPepper
+        });
+        this.tokenStore = params.tokenStore ?? new MemoryTokenStore();
+        this.oauthStore = new MemoryOAuthStore({ bcryptRounds: params.bcryptRounds });
+        let passkeyStore;
+        let passkeyConfig;
+        if (params.passkeys !== false) {
+            passkeyConfig = 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 MemoryPasskeyStore({ resolveUser });
+            this.passkeyStore = passkeyStore;
+        }
+        this.adapter = new 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: toOptionalStringId(query.userId),
+            ruid: toOptionalStringId(query.ruid)
+        };
+        return this.adapter.getToken(normalized, opts);
+    }
+    async deleteToken(query) {
+        const normalized = {
+            ...query,
+            userId: toOptionalStringId(query.userId),
+            ruid: 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);
+    }
+}

package/dist/esm/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>;

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

@@ -0,0 +1,21 @@
+import { ApiModule } from '../api-module.js';
+// Handy base that you can extend when wiring a real auth module. Subclasses
+// must supply a namespace via the constructor and implement token issuance.
+export class BaseAuthModule extends ApiModule {
+    constructor(opts) {
+        super(opts);
+        this.moduleType = 'auth';
+    }
+}
+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.');
+    }
+}
+export const nullAuthModule = new NullAuthModule();

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

@@ -0,0 +1,21 @@
+/**
+ * JSON Schema definitions for auth module routes.
+ * These are the runtime validation source-of-truth; TypeScript interfaces
+ * in auth-module.ts remain for handler-internal typing only.
+ */
+/** Loose JSON Schema object type used for Fastify route schema definitions. */
+type JsonSchema = Record<string, unknown>;
+export declare const loginBodySchema: JsonSchema;
+export declare const refreshBodySchema: JsonSchema;
+export declare const logoutBodySchema: JsonSchema;
+export declare const whoamiBodySchema: JsonSchema;
+export declare const passkeyChallengeBodySchema: JsonSchema;
+export declare const passkeyVerifyBodySchema: JsonSchema;
+export declare const passkeyCredentialParamsSchema: JsonSchema;
+export declare const impersonateBodySchema: JsonSchema;
+export declare const deleteImpersonationQuerySchema: JsonSchema;
+export declare const oauthProviderParamsSchema: JsonSchema;
+export declare const oauthStartBodySchema: JsonSchema;
+export declare const oauthAuthorizeBodySchema: JsonSchema;
+export declare const oauthTokenBodySchema: JsonSchema;
+export {};

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

@@ -0,0 +1,168 @@
+/**
+ * JSON Schema definitions for auth module routes.
+ * These are the runtime validation source-of-truth; TypeScript interfaces
+ * in auth-module.ts remain for handler-internal typing only.
+ */
+/* ------------------------------------------------------------------ */
+/*  Shared fragments                                                   */
+/* ------------------------------------------------------------------ */
+const tokenMetadataProperties = {
+    domain: { type: 'string' },
+    fingerprint: { type: 'string' },
+    label: { type: 'string' },
+    browser: { type: 'string' },
+    device: { type: 'string' },
+    ip: { type: 'string' },
+    os: { type: 'string' }
+};
+const keepSessionProperty = {
+    keepSession: { type: ['boolean', 'number', 'string'] }
+};
+function authIdentifierProperty(name) {
+    return { [name]: { type: ['string', 'number'] } };
+}
+/* ------------------------------------------------------------------ */
+/*  Auth route schemas                                                 */
+/* ------------------------------------------------------------------ */
+export const loginBodySchema = {
+    type: 'object',
+    required: ['login', 'password'],
+    properties: {
+        login: { type: 'string', minLength: 1 },
+        password: { type: 'string', minLength: 1 },
+        ...tokenMetadataProperties,
+        ...keepSessionProperty
+    },
+    additionalProperties: true
+};
+export const refreshBodySchema = {
+    type: 'object',
+    properties: {
+        refreshToken: { type: 'string' },
+        domain: { type: 'string' },
+        fingerprint: { type: 'string' },
+        label: { type: 'string' },
+        ...keepSessionProperty
+    },
+    additionalProperties: false
+};
+export const logoutBodySchema = {
+    type: 'object',
+    properties: {
+        token: { type: 'string' },
+        refreshToken: { type: 'string' }
+    },
+    additionalProperties: false
+};
+export const whoamiBodySchema = {
+    type: 'object',
+    properties: {
+        refreshToken: { type: 'string' },
+        refresh: { type: 'boolean' }
+    },
+    additionalProperties: false
+};
+/* ------------------------------------------------------------------ */
+/*  Passkey schemas                                                    */
+/* ------------------------------------------------------------------ */
+export const passkeyChallengeBodySchema = {
+    type: 'object',
+    required: ['action'],
+    properties: {
+        action: { type: 'string', enum: ['register', 'authenticate'] },
+        login: { type: 'string' },
+        ...authIdentifierProperty('userId')
+    },
+    additionalProperties: false
+};
+export const passkeyVerifyBodySchema = {
+    type: 'object',
+    required: ['expectedChallenge', 'response'],
+    properties: {
+        expectedChallenge: { type: 'string' },
+        response: { type: 'object' },
+        login: { type: 'string' },
+        ...authIdentifierProperty('userId'),
+        userAgent: { type: 'string' },
+        ...tokenMetadataProperties,
+        ...keepSessionProperty
+    },
+    additionalProperties: true
+};
+export const passkeyCredentialParamsSchema = {
+    type: 'object',
+    required: ['credentialId'],
+    properties: {
+        credentialId: { type: 'string', minLength: 1 }
+    }
+};
+/* ------------------------------------------------------------------ */
+/*  Impersonation schemas                                              */
+/* ------------------------------------------------------------------ */
+export const impersonateBodySchema = {
+    type: 'object',
+    properties: {
+        ...authIdentifierProperty('userId'),
+        login: { type: 'string' },
+        ...tokenMetadataProperties,
+        ...keepSessionProperty,
+        clientId: { type: 'string' },
+        scope: {},
+        loginType: { type: 'string' }
+    },
+    additionalProperties: true
+};
+export const deleteImpersonationQuerySchema = {
+    type: 'object',
+    additionalProperties: true
+};
+/* ------------------------------------------------------------------ */
+/*  OAuth schemas                                                      */
+/* ------------------------------------------------------------------ */
+export const oauthProviderParamsSchema = {
+    type: 'object',
+    required: ['provider'],
+    properties: {
+        provider: { type: 'string', minLength: 1 }
+    }
+};
+export const oauthStartBodySchema = {
+    type: 'object',
+    properties: {
+        redirectUri: { type: 'string' },
+        scope: {},
+        state: { type: 'string' },
+        extras: { type: 'object' }
+    },
+    additionalProperties: true
+};
+export const oauthAuthorizeBodySchema = {
+    type: 'object',
+    required: ['clientId', 'redirectUri'],
+    properties: {
+        clientId: { type: 'string', minLength: 1 },
+        redirectUri: { type: 'string', minLength: 1 },
+        scope: {},
+        state: { type: 'string' },
+        codeChallenge: { type: 'string' },
+        codeChallengeMethod: { type: 'string' },
+        login: { type: 'string' },
+        password: { type: 'string' }
+    },
+    additionalProperties: false
+};
+export const oauthTokenBodySchema = {
+    type: 'object',
+    required: ['grant_type'],
+    properties: {
+        grant_type: { type: 'string', enum: ['authorization_code', 'refresh_token'] },
+        code: { type: 'string' },
+        redirect_uri: { type: 'string' },
+        code_verifier: { type: 'string' },
+        client_id: { type: 'string' },
+        client_secret: { type: 'string' },
+        refresh_token: { type: 'string' },
+        scope: { type: 'string' }
+    },
+    additionalProperties: false
+};