@rebasepro/server-core 0.1.2 → 0.2.3

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";

package/src/auth/interfaces.ts

@@ -20,6 +20,7 @@ export interface UserData {
     emailVerified: boolean;
     emailVerificationToken?: string | null;
     emailVerificationSentAt?: Date | null;
+    metadata?: Record<string, unknown>;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -33,6 +34,7 @@ export interface CreateUserData {
     displayName?: string;
     photoUrl?: string;
     emailVerified?: boolean;
+    metadata?: Record<string, unknown>;
 }
 
 /**

package/src/auth/jwt.ts

@@ -42,7 +42,9 @@ export function configureJwt(config: JwtConfig): void {
         "example-secret",
         "please-change-me",
         "replace-this-with-a-real-secret",
-        "default-secret"
+        "default-secret",
+        "rebase_saas_jwt_secret_must_be_long_long_long_long",
+        "rebase_saas_service_key_must_be_long_long_long_long"
     ]);
 
     if (!config.secret || config.secret.length < 32) {

package/src/auth/middleware.ts

@@ -2,7 +2,8 @@ import { MiddlewareHandler, Context } from "hono";
 import { DataDriver } from "@rebasepro/types";
 import { verifyAccessToken, AccessTokenPayload } from "./jwt";
 import { HonoEnv } from "../api/types";
-import { timingSafeEqual } from "crypto";
+import { scopeDataDriver } from "./rls-scope";
+import { safeCompare } from "./crypto-utils";
 
 /**
  * Result from a custom auth validator.
@@ -202,23 +203,6 @@ export function extractUserFromToken(token: string): AccessTokenPayload | null {
     return verifyAccessToken(token);
 }
 
-/**
- * Helper to scope a DataDriver via withAuth() for RLS.
- * SECURITY: If withAuth() is available but fails, the error is re-thrown
- * so the request is denied rather than proceeding with unscoped access.
- */
-async function scopeDataDriver(
-    driver: DataDriver,
-    user: { uid: string; roles?: string[] }
-): Promise<DataDriver> {
-    if ("withAuth" in driver && typeof (driver as Record<string, unknown>).withAuth === "function") {
-        // Fail closed — do NOT catch and swallow errors here.
-        // If RLS scoping fails the request must be rejected.
-        return await (driver as unknown as { withAuth: (user: Record<string, unknown>) => Promise<DataDriver> }).withAuth(user);
-    }
-    return driver;
-}
-
 /**
  * Create a configurable auth middleware that handles:
  * 1. Token extraction (via custom validator or JWT Bearer token)
@@ -237,34 +221,6 @@ async function scopeDataDriver(
  * This is the single source of truth for HTTP auth in Rebase.
  * Use this instead of manually parsing tokens in route handlers.
  */
-/**
- * Constant-time string comparison to prevent timing attacks on service keys.
- *
- * We intentionally avoid early-returning on length mismatch because that
- * would leak the key's length through timing differences. Instead, both
- * inputs are padded to the same length so `timingSafeEqual` always runs
- * over equal-length buffers.
- */
-function safeCompare(a: string, b: string): boolean {
-    const maxLen = Math.max(a.length, b.length);
-    // Pad both to maxLen so timingSafeEqual always compares equal-length buffers.
-    // If the original lengths differ the result will be false due to the padding
-    // difference, but the comparison still takes constant time.
-    const bufA = Buffer.alloc(maxLen);
-    const bufB = Buffer.alloc(maxLen);
-    bufA.write(a);
-    bufB.write(b);
-    try {
-        const isEqual = timingSafeEqual(bufA, bufB);
-        // Even though padding makes mismatched-length strings compare as
-        // different bytes, we still need to verify lengths match to avoid
-        // a padded shorter string accidentally equaling a longer one that
-        // has trailing null bytes.
-        return isEqual && a.length === b.length;
-    } catch {
-        return false;
-    }
-}
 
 export function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv> {
     const { driver, requireAuth: enforceAuth = true, validator, serviceKey } = options;

package/src/auth/rls-scope.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared RLS (Row-Level Security) scoping helper.
+ *
+ * DataDrivers may implement a `withAuth()` method that returns a scoped
+ * clone of the driver with RLS policies applied for the given user.
+ * This is database-specific (e.g. Postgres SET LOCAL ROLE) and is not
+ * part of the core DataDriver interface.
+ *
+ * This module provides the shared duck-typing logic used by the
+ * adapter-aware middleware.
+ *
+ * @module
+ */
+
+import type { DataDriver } from "@rebasepro/types";
+
+/**
+ * A DataDriver that supports RLS scoping via `withAuth()`.
+ *
+ * This is not part of the public DataDriver interface because not all
+ * database implementations support RLS. Drivers that do (e.g. Postgres)
+ * extend DataDriver with this method.
+ */
+interface RLSScopedDriver extends DataDriver {
+    withAuth(user: { uid: string; roles?: string[] }): Promise<DataDriver>;
+}
+
+/**
+ * Returns true if the driver supports RLS scoping via `withAuth()`.
+ */
+function isRLSScopedDriver(driver: DataDriver): driver is RLSScopedDriver {
+    return "withAuth" in driver && typeof (driver as Record<string, unknown>).withAuth === "function";
+}
+
+/**
+ * Scope a DataDriver via `withAuth()` for RLS.
+ *
+ * SECURITY: If `withAuth()` is available but fails, the error is re-thrown
+ * so the request is **denied** rather than proceeding with unscoped access
+ * (fail-closed behavior).
+ *
+ * If the driver does not support RLS, the original driver is returned.
+ *
+ * @param driver - The DataDriver to scope.
+ * @param user   - The authenticated user identity for RLS.
+ * @returns The RLS-scoped DataDriver (or the original if RLS is unsupported).
+ */
+export async function scopeDataDriver(
+    driver: DataDriver,
+    user: { uid: string; roles?: string[] },
+): Promise<DataDriver> {
+    if (isRLSScopedDriver(driver)) {
+        // Fail closed — do NOT catch and swallow errors here.
+        // If RLS scoping fails the request must be rejected.
+        return await driver.withAuth(user);
+    }
+    return driver;
+}