@xcelsior/auth-adapter-knex 1.0.0

package/src/knex.ts

@@ -0,0 +1,351 @@
+import type { Knex } from 'knex';
+import type {
+    IStorageProvider,
+    User,
+    Session,
+    UserFilter,
+    FindUsersOptions,
+    FindUsersResult,
+} from '@xcelsior/auth';
+
+export interface KnexConfig {
+    /** Pre-configured Knex instance */
+    knex: Knex;
+    /** Table name for users */
+    tableName: string;
+    /** Table name for sessions */
+    sessionsTableName: string;
+    /** Optional schema (for PostgreSQL) */
+    schema?: string;
+}
+
+export class KnexStorageProvider implements IStorageProvider {
+    private knex: Knex;
+    private tableName: string;
+    private sessionsTableName: string;
+    private schema?: string;
+
+    constructor(config: KnexConfig) {
+        this.knex = config.knex;
+        this.tableName = config.tableName;
+        this.sessionsTableName = config.sessionsTableName;
+        this.schema = config.schema;
+    }
+
+    private get table() {
+        const query = this.knex(this.tableName);
+        if (this.schema) {
+            return query.withSchema(this.schema);
+        }
+        return query;
+    }
+
+    private get sessionsTable() {
+        const query = this.knex(this.sessionsTableName);
+        if (this.schema) {
+            return query.withSchema(this.schema);
+        }
+        return query;
+    }
+
+    // ==================== User Methods ====================
+
+    async createUser(user: User): Promise<void> {
+        await this.table.insert(this.toDbUser(user));
+    }
+
+    async getUserById(id: string): Promise<User | null> {
+        const row = await this.table.where({ id }).first();
+        return row ? this.fromDbUser(row) : null;
+    }
+
+    async getUserByEmail(email: string): Promise<User | null> {
+        const row = await this.table.where({ email }).first();
+        return row ? this.fromDbUser(row) : null;
+    }
+
+    async getUserByResetPasswordToken(resetPasswordToken: string): Promise<User | null> {
+        const row = await this.table.where({ reset_password_token: resetPasswordToken }).first();
+        return row ? this.fromDbUser(row) : null;
+    }
+
+    async getUserByVerifyEmailToken(verifyEmailToken: string): Promise<User | null> {
+        const row = await this.table.where({ verification_token: verifyEmailToken }).first();
+        return row ? this.fromDbUser(row) : null;
+    }
+
+    async updateUser(id: string, updates: Partial<User>): Promise<void> {
+        const dbUpdates = this.toDbUpdates(updates);
+
+        if (Object.keys(dbUpdates).length === 0) {
+            return;
+        }
+
+        await this.table.where({ id }).update(dbUpdates);
+    }
+
+    async deleteUser(id: string): Promise<void> {
+        // Delete all user sessions first
+        await this.deleteAllUserSessions(id);
+        // Then delete the user
+        await this.table.where({ id }).delete();
+    }
+
+    async findUsers(filter: UserFilter, options: FindUsersOptions = {}): Promise<FindUsersResult> {
+        const limit = options.limit ?? 50;
+
+        let query = this.table.clone();
+
+        // Email exact match
+        if (filter.email) {
+            query = query.where('email', filter.email);
+        }
+
+        // Email contains (partial match)
+        if (filter.emailContains) {
+            query = query.where('email', 'like', `%${filter.emailContains}%`);
+        }
+
+        // Email verification status
+        if (filter.isEmailVerified !== undefined) {
+            query = query.where('is_email_verified', filter.isEmailVerified);
+        }
+
+        // Roles filtering - user must have ALL specified roles
+        if (filter.roles && filter.roles.length > 0) {
+            for (const role of filter.roles) {
+                // Use JSON contains - works for PostgreSQL (jsonb) and MySQL (json)
+                // For SQLite, we fall back to LIKE on the JSON string
+                query = query.whereRaw(
+                    this.knex.client.config.client === 'sqlite3' ? `roles LIKE ?` : `roles @> ?`,
+                    this.knex.client.config.client === 'sqlite3'
+                        ? [`%"${role}"%`]
+                        : [JSON.stringify([role])]
+                );
+            }
+        }
+
+        // HasAnyRole - user must have at least ONE of specified roles
+        if (filter.hasAnyRole && filter.hasAnyRole.length > 0) {
+            query = query.where((builder: Knex.QueryBuilder) => {
+                for (const role of filter.hasAnyRole!) {
+                    builder.orWhereRaw(
+                        this.knex.client.config.client === 'sqlite3'
+                            ? `roles LIKE ?`
+                            : `roles @> ?`,
+                        this.knex.client.config.client === 'sqlite3'
+                            ? [`%"${role}"%`]
+                            : [JSON.stringify([role])]
+                    );
+                }
+            });
+        }
+
+        // Apply pagination
+        if (options.cursor) {
+            const cursorData = JSON.parse(Buffer.from(options.cursor, 'base64').toString());
+            query = query.where('id', '>', cursorData.lastId);
+        }
+
+        // Order by id for consistent pagination
+        query = query.orderBy('id', 'asc').limit(limit + 1);
+
+        const rows = await query;
+        const hasMore = rows.length > limit;
+        const resultRows = hasMore ? rows.slice(0, limit) : rows;
+        const users = resultRows.map((row: Record<string, unknown>) => this.fromDbUser(row));
+
+        let nextCursor: string | undefined;
+        if (hasMore && resultRows.length > 0) {
+            const lastUser = resultRows[resultRows.length - 1];
+            nextCursor = Buffer.from(JSON.stringify({ lastId: lastUser.id })).toString('base64');
+        }
+
+        return { users, nextCursor };
+    }
+
+    // ==================== Session Methods ====================
+
+    async createSession(session: Session): Promise<void> {
+        await this.sessionsTable.insert(this.toDbSession(session));
+    }
+
+    async getSessionById(id: string): Promise<Session | null> {
+        const row = await this.sessionsTable.where({ id }).first();
+        return row ? this.fromDbSession(row) : null;
+    }
+
+    async getSessionsByUserId(userId: string): Promise<Session[]> {
+        const rows = await this.sessionsTable.where({ user_id: userId });
+        return rows.map((row: Record<string, unknown>) => this.fromDbSession(row));
+    }
+
+    async updateSession(id: string, updates: Partial<Session>): Promise<void> {
+        const dbUpdates = this.toDbSessionUpdates(updates);
+
+        if (Object.keys(dbUpdates).length === 0) {
+            return;
+        }
+
+        await this.sessionsTable.where({ id }).update(dbUpdates);
+    }
+
+    async deleteSession(id: string): Promise<void> {
+        await this.sessionsTable.where({ id }).delete();
+    }
+
+    async deleteAllUserSessions(userId: string): Promise<void> {
+        await this.sessionsTable.where({ user_id: userId }).delete();
+    }
+
+    async deleteExpiredSessions(): Promise<void> {
+        const now = Date.now();
+        await this.sessionsTable.where('expires_at', '<', now).delete();
+    }
+
+    // ==================== User Mapping Helpers ====================
+
+    /**
+     * Convert User object to database row format (snake_case)
+     */
+    private toDbUser(user: User): Record<string, unknown> {
+        return {
+            id: user.id,
+            email: user.email,
+            first_name: user.firstName ?? null,
+            last_name: user.lastName ?? null,
+            password_hash: user.passwordHash,
+            roles: JSON.stringify(user.roles),
+            is_email_verified: user.isEmailVerified,
+            verification_token: user.verificationToken ?? null,
+            reset_password_token: user.resetPasswordToken ?? null,
+            reset_password_expires: user.resetPasswordExpires ?? null,
+            created_at: user.createdAt,
+            updated_at: user.updatedAt,
+        };
+    }
+
+    /**
+     * Convert database row to User object (camelCase)
+     */
+    private fromDbUser(row: Record<string, unknown>): User {
+        return {
+            id: row.id as string,
+            email: row.email as string,
+            firstName: row.first_name as string | undefined,
+            lastName: row.last_name as string | undefined,
+            passwordHash: row.password_hash as string,
+            roles: typeof row.roles === 'string' ? JSON.parse(row.roles) : row.roles,
+            isEmailVerified: Boolean(row.is_email_verified),
+            verificationToken: row.verification_token as string | undefined,
+            resetPasswordToken: row.reset_password_token as string | undefined,
+            resetPasswordExpires: row.reset_password_expires as number | undefined,
+            createdAt: row.created_at as number,
+            updatedAt: row.updated_at as number,
+        };
+    }
+
+    /**
+     * Convert partial User updates to database format
+     */
+    private toDbUpdates(updates: Partial<User>): Record<string, unknown> {
+        const dbUpdates: Record<string, unknown> = {};
+
+        if (updates.email !== undefined) {
+            dbUpdates.email = updates.email;
+        }
+        if ('firstName' in updates) {
+            dbUpdates.first_name = updates.firstName ?? null;
+        }
+        if ('lastName' in updates) {
+            dbUpdates.last_name = updates.lastName ?? null;
+        }
+        if (updates.passwordHash !== undefined) {
+            dbUpdates.password_hash = updates.passwordHash;
+        }
+        if (updates.roles !== undefined) {
+            dbUpdates.roles = JSON.stringify(updates.roles);
+        }
+        if (updates.isEmailVerified !== undefined) {
+            dbUpdates.is_email_verified = updates.isEmailVerified;
+        }
+        if ('verificationToken' in updates) {
+            dbUpdates.verification_token = updates.verificationToken ?? null;
+        }
+        if ('resetPasswordToken' in updates) {
+            dbUpdates.reset_password_token = updates.resetPasswordToken ?? null;
+        }
+        if ('resetPasswordExpires' in updates) {
+            dbUpdates.reset_password_expires = updates.resetPasswordExpires ?? null;
+        }
+        if (updates.updatedAt !== undefined) {
+            dbUpdates.updated_at = updates.updatedAt;
+        }
+
+        return dbUpdates;
+    }
+
+    // ==================== Session Mapping Helpers ====================
+
+    /**
+     * Convert Session object to database row format (snake_case)
+     */
+    private toDbSession(session: Session): Record<string, unknown> {
+        return {
+            id: session.id,
+            user_id: session.userId,
+            refresh_token_hash: session.refreshTokenHash,
+            user_agent: session.userAgent ?? null,
+            ip_address: session.ipAddress ?? null,
+            device_name: session.deviceName ?? null,
+            created_at: session.createdAt,
+            last_used_at: session.lastUsedAt,
+            expires_at: session.expiresAt,
+        };
+    }
+
+    /**
+     * Convert database row to Session object (camelCase)
+     */
+    private fromDbSession(row: Record<string, unknown>): Session {
+        return {
+            id: row.id as string,
+            userId: row.user_id as string,
+            refreshTokenHash: row.refresh_token_hash as string,
+            userAgent: row.user_agent as string | undefined,
+            ipAddress: row.ip_address as string | undefined,
+            deviceName: row.device_name as string | undefined,
+            createdAt: row.created_at as number,
+            lastUsedAt: row.last_used_at as number,
+            expiresAt: row.expires_at as number,
+        };
+    }
+
+    /**
+     * Convert partial Session updates to database format
+     */
+    private toDbSessionUpdates(updates: Partial<Session>): Record<string, unknown> {
+        const dbUpdates: Record<string, unknown> = {};
+
+        if (updates.refreshTokenHash !== undefined) {
+            dbUpdates.refresh_token_hash = updates.refreshTokenHash;
+        }
+        if ('userAgent' in updates) {
+            dbUpdates.user_agent = updates.userAgent ?? null;
+        }
+        if ('ipAddress' in updates) {
+            dbUpdates.ip_address = updates.ipAddress ?? null;
+        }
+        if ('deviceName' in updates) {
+            dbUpdates.device_name = updates.deviceName ?? null;
+        }
+        if (updates.lastUsedAt !== undefined) {
+            dbUpdates.last_used_at = updates.lastUsedAt;
+        }
+        if (updates.expiresAt !== undefined) {
+            dbUpdates.expires_at = updates.expiresAt;
+        }
+
+        return dbUpdates;
+    }
+}

package/src/migration.ts

@@ -0,0 +1,78 @@
+import type { Knex } from 'knex';
+
+/**
+ * SQL migration helper to create the users table
+ * Can be used with Knex migrations
+ *
+ * @example
+ * ```ts
+ * // In your migration file
+ * import { createUsersTableMigration, createSessionsTableMigration } from '@xcelsior/auth-adapter-knex';
+ *
+ * export async function up(knex: Knex): Promise<void> {
+ *   await createUsersTableMigration(knex, 'users');
+ *   await createSessionsTableMigration(knex, 'sessions');
+ * }
+ *
+ * export async function down(knex: Knex): Promise<void> {
+ *   await knex.schema.dropTableIfExists('sessions');
+ *   await knex.schema.dropTableIfExists('users');
+ * }
+ * ```
+ */
+export async function createUsersTableMigration(
+    knex: Knex,
+    tableName: string,
+    schema?: string
+): Promise<void> {
+    const schemaBuilder = schema ? knex.schema.withSchema(schema) : knex.schema;
+
+    await schemaBuilder.createTable(tableName, (table) => {
+        table.string('id').primary();
+        table.string('email').notNullable().unique();
+        table.string('first_name').nullable();
+        table.string('last_name').nullable();
+        table.string('password_hash').notNullable();
+        table.jsonb('roles').notNullable();
+        table.boolean('is_email_verified').notNullable().defaultTo(false);
+        table.string('verification_token').nullable();
+        table.string('reset_password_token').nullable();
+        table.bigInteger('reset_password_expires').nullable();
+        table.bigInteger('created_at').notNullable();
+        table.bigInteger('updated_at').notNullable();
+
+        // Indexes for common lookups
+        table.index('email');
+        table.index('verification_token');
+        table.index('reset_password_token');
+    });
+}
+
+/**
+ * SQL migration helper to create the sessions table
+ * Can be used with Knex migrations
+ */
+export async function createSessionsTableMigration(
+    knex: Knex,
+    tableName: string,
+    schema?: string
+): Promise<void> {
+    const schemaBuilder = schema ? knex.schema.withSchema(schema) : knex.schema;
+
+    await schemaBuilder.createTable(tableName, (table) => {
+        table.string('id').primary();
+        table.string('user_id').notNullable();
+        table.string('refresh_token_hash').notNullable();
+        table.string('user_agent').nullable();
+        table.string('ip_address').nullable();
+        table.string('device_name').nullable();
+        table.bigInteger('created_at').notNullable();
+        table.bigInteger('last_used_at').notNullable();
+        table.bigInteger('expires_at').notNullable();
+
+        // Index for querying sessions by user
+        table.index('user_id');
+        // Index for cleaning up expired sessions
+        table.index('expires_at');
+    });
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": "../../../tsconfig.json",
+    "compilerOptions": {
+        "outDir": "dist",
+        "rootDir": "src"
+    },
+    "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+    entry: ['src/index.ts'],
+    format: ['cjs', 'esm'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    clean: true,
+});