@rebasepro/server-core 0.1.2 → 0.2.1

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,
+    };
+}

package/src/auth/builtin-auth-adapter.ts

@@ -0,0 +1,384 @@
+/**
+ * RebaseBuiltinAuthAdapter
+ *
+ * Wraps Rebase's existing built-in JWT auth system (routes, middleware, user/role
+ * management) into the `AuthAdapter` interface. This is the default adapter used
+ * when the user passes a plain `RebaseAuthConfig` object.
+ *
+ * This is NOT a rewrite — it delegates to the existing `createAuthRoutes()`,
+ * `createAdminRoutes()`, and `verifyAccessToken()` functions. The goal is to
+ * present the same functionality through the pluggable `AuthAdapter` contract.
+ */
+
+import type {
+    AuthAdapter,
+    AuthenticatedUser,
+    AuthAdapterCapabilities,
+    UserManagementAdapter,
+    RoleManagementAdapter,
+    AuthUserListOptions,
+    AuthUserListResult,
+    AuthUserData,
+    AuthCreateUserData,
+    AuthRoleData,
+    AuthCreateRoleData,
+    BootstrappedAuth,
+    BackendHooks,
+} from "@rebasepro/types";
+
+import type { Hono } from "hono";
+import { verifyAccessToken } from "./jwt";
+import type { AccessTokenPayload } from "./jwt";
+import { createAuthRoutes } from "./routes";
+import { createAdminRoutes } from "./admin-routes";
+import type { AuthRepository, OAuthProvider } from "./interfaces";
+import type { AuthOverrides, ResolvedAuthOperations } from "./auth-overrides";
+import { resolveAuthOverrides } from "./auth-overrides";
+import type { EmailService, EmailConfig } from "../email";
+import type { HonoEnv } from "../api/types";
+import { safeCompare } from "./crypto-utils";
+
+/**
+ * Configuration for the built-in Rebase auth adapter.
+ *
+ * This mirrors the existing `RebaseAuthConfig` — users pass this and
+ * server-core auto-wraps it in a `RebaseBuiltinAuthAdapter`.
+ */
+export interface BuiltinAuthAdapterConfig {
+    /** The bootstrapper-provided auth repository (users, roles, tokens). */
+    authRepository: AuthRepository;
+    /** Email service for password resets, verification, etc. */
+    emailService?: EmailService;
+    /** Email configuration. */
+    emailConfig?: EmailConfig;
+    /** Whether to allow new user registration. */
+    allowRegistration?: boolean;
+    /** Default role to assign to new users. */
+    defaultRole?: string;
+    /** OAuth providers to register. */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    oauthProviders?: OAuthProvider<any>[];
+    /** Static service key for server-to-server auth. */
+    serviceKey?: string;
+    /** Backend hooks for intercepting admin data. */
+    hooks?: BackendHooks;
+    /** Auth overrides for customizing password, credentials, lifecycle, etc. */
+    overrides?: AuthOverrides;
+}
+
+/**
+ * Create the built-in Rebase auth adapter.
+ *
+ * This wraps the existing auth infrastructure (JWT, OAuth, user/role management)
+ * into the `AuthAdapter` interface. It's used internally by `initializeRebaseBackend()`
+ * when the user passes a plain `RebaseAuthConfig` object.
+ */
+export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): AuthAdapter {
+    const {
+        authRepository,
+        emailService,
+        emailConfig,
+        allowRegistration = false,
+        defaultRole,
+        oauthProviders = [],
+        serviceKey,
+        hooks,
+        overrides,
+    } = config;
+
+    const resolvedOps = resolveAuthOverrides(overrides);
+
+    const adapter: AuthAdapter = {
+        id: "rebase-builtin",
+
+        serviceKey,
+
+        async verifyRequest(request: Request): Promise<AuthenticatedUser | null> {
+            const authHeader = request.headers.get("authorization");
+            const url = new URL(request.url, "http://localhost");
+            const queryToken = url.searchParams.get("token");
+            const hasBearer = authHeader?.startsWith("Bearer ");
+
+            if (!hasBearer && !queryToken) {
+                return null;
+            }
+
+            const token = hasBearer ? authHeader!.substring(7) : queryToken!;
+
+            // Check service key first (constant-time)
+            if (serviceKey && safeCompare(token, serviceKey)) {
+                return {
+                    uid: "service",
+                    email: "service@rebase.internal",
+                    roles: ["admin"],
+                    isAdmin: true,
+                    rawToken: token,
+                };
+            }
+
+            // JWT verification
+            const payload = verifyAccessToken(token);
+            if (!payload) {
+                return null;
+            }
+
+            // The decoded JWT may contain additional claims beyond the typed payload
+            const extendedPayload = payload as AccessTokenPayload & {
+                email?: string;
+                displayName?: string;
+            };
+
+            // Resolve roles from the repository
+            let roles: string[] = payload.roles || [];
+            try {
+                const userRoles = await authRepository.getUserRoles(payload.userId);
+                roles = userRoles.map((r) => r.id);
+            } catch {
+                // Fall back to token roles if repository lookup fails
+            }
+
+            const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
+
+            return {
+                uid: payload.userId,
+                email: extendedPayload.email ?? "",
+                displayName: extendedPayload.displayName ?? null,
+                roles,
+                isAdmin,
+                rawToken: token,
+            };
+        },
+
+        async verifyToken(token: string): Promise<AuthenticatedUser | null> {
+            // Service key check (constant-time)
+            if (serviceKey && safeCompare(token, serviceKey)) {
+                return {
+                    uid: "service",
+                    email: "service@rebase.internal",
+                    roles: ["admin"],
+                    isAdmin: true,
+                    rawToken: token,
+                };
+            }
+
+            // JWT verification
+            const payload = verifyAccessToken(token);
+            if (!payload) {
+                return null;
+            }
+
+            const extendedPayload = payload as AccessTokenPayload & {
+                email?: string;
+                displayName?: string;
+            };
+
+            let roles: string[] = payload.roles || [];
+            try {
+                const userRoles = await authRepository.getUserRoles(payload.userId);
+                roles = userRoles.map((r) => r.id);
+            } catch {
+                // Fall back to token roles if repository lookup fails
+            }
+
+            const isAdmin = roles.some((r) => r === "admin" || r === "schema-admin");
+
+            return {
+                uid: payload.userId,
+                email: extendedPayload.email ?? "",
+                displayName: extendedPayload.displayName ?? null,
+                roles,
+                isAdmin,
+                rawToken: token,
+            };
+        },
+
+        userManagement: createUserManagementFromRepo(authRepository, resolvedOps, overrides),
+
+        roleManagement: createRoleManagementFromRepo(authRepository),
+
+        createAuthRoutes(): Hono<HonoEnv> | undefined {
+            return createAuthRoutes({
+                authRepo: authRepository,
+                emailService,
+                emailConfig,
+                allowRegistration,
+                defaultRole,
+                oauthProviders,
+                overrides,
+            });
+        },
+
+        createAdminRoutes(): Hono<HonoEnv> | undefined {
+            return createAdminRoutes({
+                authRepo: authRepository,
+                emailService,
+                emailConfig,
+                serviceKey,
+                hooks,
+                overrides,
+            });
+        },
+
+        async getCapabilities(): Promise<AuthAdapterCapabilities> {
+            // Detect bootstrap mode: are there any users?
+            let needsSetup = false;
+            try {
+                const result = await authRepository.listUsersPaginated({ limit: 1 });
+                needsSetup = result.total === 0;
+            } catch {
+                // If the check fails, assume not in setup mode
+            }
+
+            const enabledProviders = oauthProviders.map((p) => p.id);
+
+            return {
+                hasBuiltInAuthRoutes: true,
+                emailPasswordLogin: true,
+                registration: allowRegistration || needsSetup,
+                registrationEnabled: allowRegistration || needsSetup,
+                passwordReset: !!emailService?.isConfigured(),
+                sessionManagement: true,
+                profileUpdate: true,
+                emailVerification: !!emailService?.isConfigured(),
+                enabledProviders,
+                needsSetup,
+            };
+        },
+    };
+
+    return adapter;
+}
+
+// ─── Internal Helpers ────────────────────────────────────────────────────────
+
+function createUserManagementFromRepo(repo: AuthRepository, resolvedOps: ResolvedAuthOperations, overrides?: AuthOverrides): UserManagementAdapter {
+    return {
+        async listUsers(options?: AuthUserListOptions): Promise<AuthUserListResult> {
+            const result = await repo.listUsersPaginated({
+                limit: options?.limit,
+                offset: options?.offset,
+                search: options?.search,
+                orderBy: options?.orderBy,
+                orderDir: options?.orderDir,
+                roleId: options?.roleId,
+            });
+            return {
+                users: result.users.map(toAuthUserData),
+                total: result.total,
+                limit: result.limit,
+                offset: result.offset,
+            };
+        },
+
+        async getUserById(id: string): Promise<AuthUserData | null> {
+            const user = await repo.getUserById(id);
+            return user ? toAuthUserData(user) : null;
+        },
+
+        async createUser(data: AuthCreateUserData): Promise<AuthUserData> {
+            const passwordHash = data.password ? await resolvedOps.hashPassword(data.password) : undefined;
+            let createData: import("./interfaces").CreateUserData = {
+                email: data.email,
+                passwordHash,
+                displayName: data.displayName,
+                photoUrl: data.photoUrl,
+                metadata: data.metadata,
+            };
+            if (overrides?.beforeUserCreate) {
+                createData = await overrides.beforeUserCreate(createData);
+            }
+            const user = await repo.createUser(createData);
+            if (overrides?.afterUserCreate) {
+                overrides.afterUserCreate(user).catch(err => {
+                    console.error("[AuthOverrides] afterUserCreate error:", err instanceof Error ? err.message : err);
+                });
+            }
+            return toAuthUserData(user);
+        },
+
+        async updateUser(id: string, data: Partial<AuthCreateUserData>): Promise<AuthUserData | null> {
+            const updateData: Record<string, unknown> = {};
+            if (data.email !== undefined) updateData.email = data.email;
+            if (data.displayName !== undefined) updateData.displayName = data.displayName;
+            if (data.photoUrl !== undefined) updateData.photoUrl = data.photoUrl;
+            if (data.metadata !== undefined) updateData.metadata = data.metadata;
+            if (data.password) {
+                updateData.passwordHash = await resolvedOps.hashPassword(data.password);
+            }
+            const user = await repo.updateUser(id, updateData);
+            return user ? toAuthUserData(user) : null;
+        },
+
+        async deleteUser(id: string): Promise<void> {
+            await repo.deleteUser(id);
+        },
+
+        async getUserRoles(userId: string): Promise<AuthRoleData[]> {
+            const roles = await repo.getUserRoles(userId);
+            return roles.map(toAuthRoleData);
+        },
+
+        async setUserRoles(userId: string, roleIds: string[]): Promise<void> {
+            await repo.setUserRoles(userId, roleIds);
+        },
+    };
+}
+
+function createRoleManagementFromRepo(repo: AuthRepository): RoleManagementAdapter {
+    return {
+        async listRoles(): Promise<AuthRoleData[]> {
+            const roles = await repo.listRoles();
+            return roles.map(toAuthRoleData);
+        },
+
+        async getRoleById(id: string): Promise<AuthRoleData | null> {
+            const role = await repo.getRoleById(id);
+            return role ? toAuthRoleData(role) : null;
+        },
+
+        async createRole(data: AuthCreateRoleData): Promise<AuthRoleData> {
+            const role = await repo.createRole({
+                id: data.id,
+                name: data.name,
+                isAdmin: data.isAdmin,
+                defaultPermissions: data.defaultPermissions,
+                collectionPermissions: data.collectionPermissions,
+                config: data.config,
+            });
+            return toAuthRoleData(role);
+        },
+
+        async updateRole(id: string, data: Partial<AuthRoleData>): Promise<AuthRoleData | null> {
+            const role = await repo.updateRole(id, data);
+            return role ? toAuthRoleData(role) : null;
+        },
+
+        async deleteRole(id: string): Promise<void> {
+            await repo.deleteRole(id);
+        },
+    };
+}
+
+function toAuthUserData(user: { id: string; email: string; displayName?: string | null; photoUrl?: string | null; emailVerified?: boolean; metadata?: Record<string, unknown>; createdAt?: Date; updatedAt?: Date }): AuthUserData {
+    return {
+        id: user.id,
+        email: user.email,
+        displayName: user.displayName,
+        photoUrl: user.photoUrl,
+        emailVerified: user.emailVerified,
+        metadata: user.metadata,
+        createdAt: user.createdAt,
+        updatedAt: user.updatedAt,
+    };
+}
+
+function toAuthRoleData(role: { id: string; name: string; isAdmin: boolean; defaultPermissions?: unknown; collectionPermissions?: unknown; config?: unknown }): AuthRoleData {
+    return {
+        id: role.id,
+        name: role.name,
+        isAdmin: role.isAdmin,
+        defaultPermissions: role.defaultPermissions as AuthRoleData["defaultPermissions"],
+        collectionPermissions: role.collectionPermissions as AuthRoleData["collectionPermissions"],
+        config: role.config as AuthRoleData["config"],
+    };
+}

package/src/auth/crypto-utils.ts

@@ -0,0 +1,31 @@
+/**
+ * Cryptographic utility functions for auth.
+ *
+ * @module
+ */
+
+import { timingSafeEqual } from "crypto";
+
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ *
+ * Used for comparing service keys, tokens, and other secrets where
+ * timing side-channels could leak information about the expected value.
+ *
+ * @param a - First string to compare.
+ * @param b - Second string to compare.
+ * @returns `true` if the strings are identical, `false` otherwise.
+ */
+export function safeCompare(a: string, b: string): boolean {
+    const maxLen = Math.max(a.length, b.length);
+    const bufA = Buffer.alloc(maxLen);
+    const bufB = Buffer.alloc(maxLen);
+    bufA.write(a);
+    bufB.write(b);
+    try {
+        const isEqual = timingSafeEqual(bufA, bufB);
+        return isEqual && a.length === b.length;
+    } catch {
+        return false;
+    }
+}

package/src/auth/custom-auth-adapter.ts

@@ -0,0 +1,85 @@
+/**
+ * Custom Auth Adapter Factory
+ *
+ * Provides a minimal-config way for users with existing auth systems
+ * to plug into Rebase. Only `verifyRequest` is required — everything
+ * else is optional.
+ *
+ * @example
+ * ```ts
+ * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ *
+ * const auth = createCustomAuthAdapter({
+ *   verifyRequest: async (request) => {
+ *     const token = request.headers.get("Authorization")?.replace("Bearer ", "");
+ *     if (!token) return null;
+ *     const decoded = jwt.verify(token, MY_SECRET);
+ *     return {
+ *       uid: decoded.sub,
+ *       email: decoded.email,
+ *       displayName: decoded.name,
+ *       roles: decoded.roles || [],
+ *       isAdmin: decoded.roles?.includes("admin") ?? false,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+
+import type {
+    AuthAdapter,
+    AuthAdapterCapabilities,
+    CustomAuthAdapterOptions,
+} from "@rebasepro/types";
+
+/**
+ * Create a custom auth adapter from minimal options.
+ *
+ * This is the recommended entry point for users who already have their own
+ * auth system and just need to tell Rebase how to extract the user from
+ * incoming requests.
+ *
+ * @param options - Configuration options. Only `verifyRequest` is required.
+ * @returns A fully-formed `AuthAdapter` ready for `initializeRebaseBackend()`.
+ */
+export function createCustomAuthAdapter(options: CustomAuthAdapterOptions): AuthAdapter {
+    const defaultCapabilities: AuthAdapterCapabilities = {
+        hasBuiltInAuthRoutes: false,
+        emailPasswordLogin: false,
+        registration: false,
+        passwordReset: false,
+        sessionManagement: false,
+        profileUpdate: false,
+        emailVerification: false,
+        enabledProviders: [],
+        ...options.capabilities,
+    };
+
+    const resolvedVerifyToken = options.verifyToken
+        ?? (async (token: string) => {
+            // Synthesize a minimal Request so adapters that only implement
+            // verifyRequest still work for WebSocket token verification.
+            const syntheticRequest = new Request("http://localhost/_ws_auth", {
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            return options.verifyRequest(syntheticRequest);
+        });
+
+    return {
+        id: "custom",
+
+        serviceKey: options.serviceKey,
+
+        verifyRequest: options.verifyRequest,
+
+        verifyToken: resolvedVerifyToken,
+
+        userManagement: options.userManagement,
+
+        roleManagement: options.roleManagement,
+
+        getCapabilities() {
+            return defaultCapabilities;
+        },
+    };
+}

package/src/auth/index.ts

@@ -7,6 +7,9 @@ export type { JwtConfig, AccessTokenPayload } from "./jwt";
 export { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
 export type { PasswordValidationResult } from "./password";
 
+export type { AuthOverrides, AuthMethod, ResolvedAuthOperations } from "./auth-overrides";
+export { resolveAuthOverrides } from "./auth-overrides";
+
 // OAuth Providers
 export { createGoogleProvider } from "./google-oauth";
 export type { GoogleProviderConfig } from "./google-oauth";
@@ -33,3 +36,10 @@ export { createAdminRoutes } from "./admin-routes";
 
 
 export { createRateLimiter, defaultAuthLimiter, strictAuthLimiter } from "./rate-limiter";
+
+// Auth Adapters
+export { createBuiltinAuthAdapter } from "./builtin-auth-adapter";
+export type { BuiltinAuthAdapterConfig } from "./builtin-auth-adapter";
+export { createCustomAuthAdapter } from "./custom-auth-adapter";
+export { createAdapterAuthMiddleware } from "./adapter-middleware";
+export type { AdapterAuthMiddlewareOptions } from "./adapter-middleware";