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

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

@@ -1,4 +1,3 @@
-// Numeric database id or lookup string such as username/email.
 // Handy base you can extend when wiring a real storage adapter. Every method
 // throws by default so unimplemented hooks fail loudly.
 export class BaseAuthStorage {
@@ -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

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

@@ -0,0 +1,29 @@
+import type { AuthCodeData, AuthCodeRequest, OAuthClient } from '../oauth/types.js';
+import type { PasskeyChallenge, PasskeyChallengeParams, PasskeyVerificationParams, PasskeyVerificationResult } from '../passkey/types.js';
+import type { Token } from '../token/types.js';
+export type AuthIdentifier = string | number;
+export interface AuthStorage<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>;
+    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>;
+}

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 } from './api-server-base.js';
+export type { AuthIdentifier, AuthStorage } 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 { nullAuthStorage, BaseAuthStorage } from './auth-api/storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-api/module.js';
+export { AuthStorageAdapter } 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 { nullAuthStorage, BaseAuthStorage } from './auth-api/storage.js';
+export { nullAuthModule, BaseAuthModule } from './auth-api/module.js';
+export { AuthStorageAdapter } 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;
+}

package/dist/esm/oauth/sequelize.js

@@ -0,0 +1,199 @@
+import bcrypt from 'bcryptjs';
+import { DataTypes, Model } from 'sequelize';
+import { OAuthStore } from './base.js';
+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;
+}
+function encodeStringArray(values) {
+    return JSON.stringify(values ?? []);
+}
+function decodeStringArray(raw) {
+    if (!raw) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed)) {
+            return parsed.filter((entry) => typeof entry === 'string' && entry.length > 0);
+        }
+    }
+    catch {
+        // ignore malformed values
+    }
+    return raw
+        .split(/\s+/)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+}
+function serializeMetadata(metadata) {
+    if (!metadata) {
+        return null;
+    }
+    return JSON.stringify(metadata);
+}
+function parseMetadata(raw) {
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            return parsed;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return 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 SequelizeOAuthStore extends OAuthStore {
+    constructor(options) {
+        super();
+        if (!options?.sequelize) {
+            throw new Error('SequelizeOAuthStore requires an initialised Sequelize instance');
+        }
+        this.clients = options.clientModel ?? (options.clientModelFactory ?? initOAuthClientModel)(options.sequelize);
+        this.codes = options.codeModel ?? (options.codeModelFactory ?? initOAuthCodeModel)(options.sequelize);
+        this.bcryptRounds = options.bcryptRounds ?? 12;
+    }
+    async getClient(clientId) {
+        const model = await this.clients.findByPk(clientId);
+        return model ? this.toOAuthClient(model) : null;
+    }
+    async createClient(input) {
+        const existing = await this.clients.findByPk(input.clientId);
+        const hashedSecret = input.clientSecret !== undefined && input.clientSecret !== null
+            ? await bcrypt.hash(input.clientSecret, this.bcryptRounds)
+            : (existing?.client_secret ?? '');
+        const redirectUris = input.redirectUris ?? (existing ? decodeStringArray(existing.redirect_uris) : undefined);
+        const scope = input.scope ?? (existing ? decodeStringArray(existing.scope) : undefined);
+        const metadata = input.metadata ?? (existing ? parseMetadata(existing.metadata) : undefined);
+        await this.clients.upsert({
+            client_id: input.clientId,
+            client_secret: hashedSecret,
+            name: input.name ?? existing?.name ?? null,
+            redirect_uris: encodeStringArray(redirectUris),
+            scope: encodeStringArray(scope),
+            metadata: serializeMetadata(metadata),
+            first_party: input.firstParty ?? existing?.first_party ?? false
+        });
+        const model = await this.clients.findByPk(input.clientId);
+        if (!model) {
+            throw new Error(`Unable to persist OAuth client ${input.clientId}`);
+        }
+        return this.toOAuthClient(model);
+    }
+    async verifyClientSecret(clientId, clientSecret) {
+        const model = await this.clients.findByPk(clientId);
+        if (!model) {
+            return false;
+        }
+        if (!model.client_secret) {
+            return !clientSecret || clientSecret.length === 0;
+        }
+        if (!clientSecret) {
+            return false;
+        }
+        return bcrypt.compare(clientSecret, model.client_secret);
+    }
+    async createAuthCode(code) {
+        await this.codes.create({
+            code: code.code,
+            client_id: code.clientId,
+            user_id: normalizeUserId(code.userId),
+            redirect_uri: code.redirectUri ?? '',
+            scope: encodeStringArray(code.scope),
+            code_challenge: code.codeChallenge ?? null,
+            code_challenge_method: code.codeChallengeMethod ?? null,
+            expires: code.expiresAt,
+            metadata: serializeMetadata(code.metadata)
+        });
+    }
+    async consumeAuthCode(code) {
+        const model = await this.codes.findByPk(code);
+        if (!model) {
+            return null;
+        }
+        await model.destroy();
+        return this.toAuthCode(model);
+    }
+    async close() {
+        return;
+    }
+    toOAuthClient(model) {
+        return {
+            clientId: model.client_id,
+            clientSecret: model.client_secret,
+            name: model.name ?? undefined,
+            redirectUris: decodeStringArray(model.redirect_uris),
+            scope: decodeStringArray(model.scope),
+            metadata: parseMetadata(model.metadata),
+            firstParty: model.first_party ?? false
+        };
+    }
+    toAuthCode(model) {
+        return {
+            code: model.code,
+            clientId: model.client_id,
+            userId: model.user_id,
+            redirectUri: model.redirect_uri,
+            scope: decodeStringArray(model.scope),
+            codeChallenge: model.code_challenge ?? undefined,
+            codeChallengeMethod: model.code_challenge_method ?? undefined,
+            expiresAt: model.expires,
+            metadata: parseMetadata(model.metadata)
+        };
+    }
+}

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

@@ -0,0 +1,50 @@
+import type { AuthIdentifier } from '../auth-api/types.js';
+export interface OAuthClient {
+    clientId: string;
+    clientSecret?: string;
+    firstParty?: boolean;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    redirectUris: string[];
+    scope?: string[];
+}
+export interface AuthCodeData {
+    code: string;
+    clientId: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'plain' | 'S256';
+    expiresAt: Date;
+    metadata?: Record<string, unknown>;
+    redirectUri?: string;
+    scope?: string[];
+    userId: AuthIdentifier;
+}
+export type AuthCode = AuthCodeData;
+export type AuthCodeRequest = Omit<AuthCodeData, 'code' | 'expiresAt'> & {
+    code?: string;
+    expiresInSeconds?: number;
+};
+export interface OAuthStartParams {
+    provider: string;
+    redirectUri?: string;
+    scope?: string | string[];
+    state?: string;
+    extras?: Record<string, unknown>;
+}
+export interface OAuthStartResult extends Record<string, unknown> {
+    url: string;
+    state?: string;
+    codeVerifier?: string;
+}
+export interface OAuthCallbackParams {
+    provider: string;
+    query: Record<string, string | string[]>;
+    body: Record<string, unknown>;
+}
+export interface OAuthCallbackResult<PublicUser> extends Record<string, unknown> {
+    user: PublicUser;
+    tokens?: {
+        accessToken: string;
+        refreshToken: string;
+    };
+}

package/dist/esm/oauth/types.js

@@ -0,0 +1,2 @@
+// OAuth-specific contracts kept alongside the OAuth module.
+export {};