@rebasepro/server-core 0.1.2 → 0.2.3

package/src/auth/admin-routes.ts

@@ -2,7 +2,8 @@ import { Hono } from "hono";
 import { ApiError, errorHandler } from "../api/errors";
 import type { AuthRepository } from "./interfaces";
 import { requireAuth, requireAdmin, createRequireAuth } from "./middleware";
-import { hashPassword, validatePasswordStrength } from "./password";
+import type { AuthOverrides } from "./auth-overrides";
+import { resolveAuthOverrides } from "./auth-overrides";
 import { AuthModuleConfig } from "./routes";
 import type { BackendHooks, AdminUser, AdminRole, BackendHookContext } from "@rebasepro/types";
 
@@ -17,6 +18,11 @@ interface AdminRouteOptions extends AuthModuleConfig {
      * Backend-level hooks for intercepting admin data.
      */
     hooks?: BackendHooks;
+    /**
+     * Auth overrides for customizing password hashing, credential
+     * verification, lifecycle hooks, etc.
+     */
+    overrides?: AuthOverrides;
 }
 import { HonoEnv } from "../api/types";
 import { randomBytes, createHash } from "crypto";
@@ -68,7 +74,8 @@ function hashToken(token: string): string {
 export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
     const router = new Hono<HonoEnv>();
     const authRepo = config.authRepo;
-    const { emailService, emailConfig, hooks } = config;
+    const { emailService, emailConfig, hooks, overrides } = config;
+    const ops = resolveAuthOverrides(overrides);
 
     /** Build a BackendHookContext from Hono's context object */
     function buildHookContext(c: { get: (key: string) => unknown }, method: BackendHookContext["method"]): BackendHookContext {
@@ -192,41 +199,20 @@ export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
         const orderDir = c.req.query("orderDir") as "asc" | "desc" | undefined;
         const hookCtx = buildHookContext(c, "GET");
 
-        // If pagination params are provided, use the paginated path
-        if (limitParam !== undefined || search) {
-            const limit = limitParam ? parseInt(limitParam, 10) : 25;
-            const offset = offsetParam ? parseInt(offsetParam, 10) : 0;
-
-            const result = await authRepo.listUsersPaginated({
-                limit,
-                offset,
-                search: search || undefined,
-                orderBy: orderBy || undefined,
-                orderDir: orderDir || undefined,
-                roleId: c.req.query("role") || undefined
-            });
-
-            let usersWithRoles: AdminUser[] = await Promise.all(
-                result.users.map(async (u) => {
-                    const roles = await authRepo.getUserRoleIds(u.id);
-                    return toAdminUser(u, roles);
-                })
-            );
-
-            usersWithRoles = await applyUserAfterReadBatch(usersWithRoles, hookCtx);
+        const limit = limitParam ? parseInt(limitParam, 10) : 25;
+        const offset = offsetParam ? parseInt(offsetParam, 10) : 0;
 
-            return c.json({
-                users: usersWithRoles,
-                total: result.total,
-                limit: result.limit,
-                offset: result.offset
-            });
-        }
+        const result = await authRepo.listUsersPaginated({
+            limit,
+            offset,
+            search: search || undefined,
+            orderBy: orderBy || undefined,
+            orderDir: orderDir || undefined,
+            roleId: c.req.query("role") || undefined
+        });
 
-        // Legacy: return all users (no pagination)
-        const users = await authRepo.listUsers();
         let usersWithRoles: AdminUser[] = await Promise.all(
-            users.map(async (u) => {
+            result.users.map(async (u) => {
                 const roles = await authRepo.getUserRoleIds(u.id);
                 return toAdminUser(u, roles);
             })
@@ -234,7 +220,12 @@ export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
 
         usersWithRoles = await applyUserAfterReadBatch(usersWithRoles, hookCtx);
 
-        return c.json({ users: usersWithRoles });
+        return c.json({
+            users: usersWithRoles,
+            total: result.total,
+            limit: result.limit,
+            offset: result.offset
+        });
     });
 
     router.get("/users/:userId", requireAdmin, async (c) => {
@@ -258,7 +249,8 @@ export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
 
     router.post("/users", requireAdmin, async (c) => {
         const body = await c.req.json();
-        let { email, displayName, password, roles } = body;
+        const { password } = body;
+        let { email, displayName, roles } = body;
 
         if (!email) {
             throw ApiError.badRequest("Email is required", "INVALID_INPUT");
@@ -281,11 +273,11 @@ export function createAdminRoutes(config: AdminRouteOptions): Hono<HonoEnv> {
         // Use provided password or auto-generate one
         const clearPassword = password || generateSecurePassword();
 
-        const validation = validatePasswordStrength(clearPassword);
+        const validation = ops.validatePasswordStrength(clearPassword);
         if (!validation.valid) {
             throw ApiError.badRequest(validation.errors.join(". "), "WEAK_PASSWORD");
         }
-        const passwordHash = await hashPassword(clearPassword);
+        const passwordHash = await ops.hashPassword(clearPassword);
 
         const user = await authRepo.createUser({
             email: email.toLowerCase(),
@@ -401,14 +393,14 @@ displayName: existing.displayName }, appName);
                 console.error("Failed to send reset email:", emailError instanceof Error ? emailError.message : emailError);
                 // Fall back to returning the temporary password
                 const clearPassword = generateSecurePassword();
-                const passwordHash = await hashPassword(clearPassword);
+                const passwordHash = await ops.hashPassword(clearPassword);
                 await authRepo.updatePassword(existing.id, passwordHash);
                 temporaryPassword = clearPassword;
             }
         } else {
             // No email service — generate password, set it, and return one-time
             const clearPassword = generateSecurePassword();
-            const passwordHash = await hashPassword(clearPassword);
+            const passwordHash = await ops.hashPassword(clearPassword);
             await authRepo.updatePassword(existing.id, passwordHash);
             temporaryPassword = clearPassword;
         }
@@ -430,7 +422,8 @@ displayName: existing.displayName }, appName);
     router.put("/users/:userId", requireAdmin, async (c) => {
         const userId = c.req.param("userId");
         const body = await c.req.json();
-        let { email, displayName, password, roles } = body;
+        const { password } = body;
+        let { email, displayName, roles } = body;
 
         const existing = await authRepo.getUserById(userId);
         if (!existing) {
@@ -451,11 +444,11 @@ displayName: existing.displayName }, appName);
         if (displayName !== undefined) updates.displayName = displayName;
 
         if (password) {
-            const validation = validatePasswordStrength(password);
+            const validation = ops.validatePasswordStrength(password);
             if (!validation.valid) {
                 throw ApiError.badRequest(validation.errors.join(". "), "WEAK_PASSWORD");
             }
-            updates.passwordHash = await hashPassword(password);
+            updates.passwordHash = await ops.hashPassword(password);
         }
 
         if (Object.keys(updates).length > 0) {

package/src/auth/auth-overrides.ts

@@ -0,0 +1,172 @@
+/**
+ * AuthOverrides
+ *
+ * Override specific behaviors of the built-in Rebase auth system.
+ *
+ * Each method replaces one piece of the default implementation.
+ * Unset methods fall through to the built-in defaults (scrypt passwords,
+ * standard validation rules, etc.).
+ *
+ * This interface is intentionally open for extension — new overrides
+ * can be added as optional methods without breaking existing configurations.
+ *
+ * @example bcrypt password support
+ * ```ts
+ * import bcrypt from "bcrypt";
+ *
+ * const overrides: AuthOverrides = {
+ *     hashPassword: (pw) => bcrypt.hash(pw, 12),
+ *     verifyPassword: (pw, hash) => bcrypt.compare(pw, hash),
+ *     validatePasswordStrength: (pw) => ({
+ *         valid: pw.length >= 6,
+ *         errors: pw.length < 6 ? ["Password must be at least 6 characters"] : []
+ *     })
+ * };
+ * ```
+ *
+ * @example Override the entire login credential check
+ * ```ts
+ * const overrides: AuthOverrides = {
+ *     verifyCredentials: async (email, password, repo) => {
+ *         const user = await repo.getUserByEmail(email);
+ *         if (!user || !user.passwordHash) return null;
+ *         const valid = await myCustomVerify(password, user.passwordHash);
+ *         return valid ? user : null;
+ *     }
+ * };
+ * ```
+ */
+
+import {
+    hashPassword as defaultHashPassword,
+    verifyPassword as defaultVerifyPassword,
+    validatePasswordStrength as defaultValidatePasswordStrength
+} from "./password";
+import type { PasswordValidationResult } from "./password";
+import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
+
+/**
+ * Authentication method identifier for lifecycle hooks.
+ */
+export type AuthMethod = "login" | "register" | "oauth" | "refresh" | "password-reset";
+
+/**
+ * Override specific parts of the built-in Rebase auth implementation.
+ *
+ * Every method is optional. The built-in defaults apply for any method
+ * that is not provided.
+ */
+export interface AuthOverrides {
+    // ─── Password Operations ──────────────────────────────────────────────
+
+    /**
+     * Hash a cleartext password for storage.
+     *
+     * Default: scrypt (Node.js crypto, 64-byte key, random 32-byte salt).
+     *
+     * @param password - The cleartext password.
+     * @returns The hashed password string (format is implementation-defined).
+     */
+    hashPassword?(password: string): Promise<string>;
+
+    /**
+     * Verify a cleartext password against a stored hash.
+     *
+     * Default: scrypt verification with timing-safe comparison.
+     *
+     * @param password - The cleartext password to check.
+     * @param storedHash - The hash string retrieved from the database.
+     * @returns `true` if the password matches the hash.
+     */
+    verifyPassword?(password: string, storedHash: string): Promise<boolean>;
+
+    /**
+     * Validate password strength before hashing.
+     *
+     * Default: minimum 8 characters, at least one uppercase, one lowercase, one digit.
+     *
+     * @param password - The cleartext password to validate.
+     * @returns Validation result with `valid` flag and error messages.
+     */
+    validatePasswordStrength?(password: string): PasswordValidationResult;
+
+    // ─── Credential Resolution ────────────────────────────────────────────
+
+    /**
+     * Override the complete credential verification during email/password login.
+     *
+     * When set, this replaces the default flow:
+     *   1. Look up user by email
+     *   2. Verify password hash
+     *
+     * The auth repository is provided for database access. Return the user
+     * data if credentials are valid, or `null` to reject the login.
+     *
+     * Default: `getUserByEmail(email)` + `verifyPassword(password, user.passwordHash)`.
+     */
+    verifyCredentials?(email: string, password: string, repo: AuthRepository): Promise<UserData | null>;
+
+    // ─── Lifecycle Hooks ──────────────────────────────────────────────────
+
+    /**
+     * Called after any successful authentication event (login, register,
+     * OAuth, token refresh, password reset).
+     *
+     * Use for audit logging, syncing external state, updating
+     * last-login timestamps, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    onAuthenticated?(user: UserData, method: AuthMethod): Promise<void>;
+
+    /**
+     * Called before a new user is created (registration or admin creation).
+     *
+     * Return modified data to alter what gets stored, or throw an error
+     * to reject the creation entirely.
+     *
+     * Default: passthrough (returns data unchanged).
+     */
+    beforeUserCreate?(data: CreateUserData): Promise<CreateUserData>;
+
+    /**
+     * Called after a new user is created.
+     *
+     * Use for provisioning external resources, sending notifications
+     * to third-party systems, etc.
+     *
+     * This is fire-and-forget — errors are logged but do not fail the request.
+     */
+    afterUserCreate?(user: UserData): Promise<void>;
+}
+
+/**
+ * Resolved auth operations — every method is guaranteed to exist.
+ * Created by `resolveAuthOverrides()` which merges user overrides
+ * with built-in defaults.
+ */
+export interface ResolvedAuthOperations {
+    hashPassword(password: string): Promise<string>;
+    verifyPassword(password: string, storedHash: string): Promise<boolean>;
+    validatePasswordStrength(password: string): PasswordValidationResult;
+}
+
+/**
+ * Merge user-provided overrides with the built-in defaults to produce
+ * a complete set of resolved operations.
+ *
+ * This is the single point where defaults are applied — all consumers
+ * call this once and use the resolved operations throughout.
+ */
+export function resolveAuthOverrides(overrides?: AuthOverrides): ResolvedAuthOperations {
+    return {
+        hashPassword: overrides?.hashPassword
+            ?? defaultHashPassword,
+
+        verifyPassword: overrides?.verifyPassword
+            ?? defaultVerifyPassword,
+
+        validatePasswordStrength: overrides?.validatePasswordStrength
+            ?? defaultValidatePasswordStrength,
+    };
+}