@rebasepro/server-core 0.1.2 → 0.2.3

package/src/auth/routes.ts

@@ -3,7 +3,8 @@ import { ApiError, errorHandler } from "../api/errors";
 import { randomBytes, createHash } from "crypto";
 import type { AuthRepository, OAuthProvider } from "./interfaces";
 import { generateAccessToken, generateRefreshToken, hashRefreshToken, getRefreshTokenExpiry, getAccessTokenExpiry } from "./jwt";
-import { hashPassword, verifyPassword, validatePasswordStrength } from "./password";
+import type { AuthOverrides } from "./auth-overrides";
+import { resolveAuthOverrides } from "./auth-overrides";
 import { requireAuth } from "./middleware";
 import { EmailService, EmailConfig } from "../email";
 import { getPasswordResetTemplate, getEmailVerificationTemplate, getWelcomeEmailTemplate } from "../email/templates";
@@ -23,9 +24,15 @@ export interface AuthModuleConfig {
     /** Default role ID to assign to new users (default: none). Must NOT be "admin". */
     defaultRole?: string;
     /** Optional array of OAuth providers */
-    oauthProviders?: OAuthProvider[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    oauthProviders?: OAuthProvider<any>[];
     /** When true, blocks all self-registration regardless of `allowRegistration`. */
     disableSelfRegistration?: boolean;
+    /**
+     * Auth overrides for customizing password hashing, credential
+     * verification, lifecycle hooks, etc.
+     */
+    overrides?: AuthOverrides;
     /**
      * Callback that checks if bootstrap has already been completed.
      * Used by GET /auth/config to report `needsSetup` status.
@@ -38,7 +45,7 @@ export interface AuthModuleConfig {
  * Helper to build standard auth response output
  */
 function buildAuthResponse(
-    user: { id: string; email: string; displayName?: string | null; photoUrl?: string | null },
+    user: { id: string; email: string; displayName?: string | null; photoUrl?: string | null; metadata?: Record<string, unknown> | null },
     roleIds: string[],
     accessToken: string,
     refreshToken: string
@@ -49,7 +56,8 @@ function buildAuthResponse(
             email: user.email,
             displayName: user.displayName ?? null,
             photoURL: user.photoUrl ?? null,
-            roles: roleIds
+            roles: roleIds,
+            metadata: user.metadata ?? {}
         },
         tokens: {
             accessToken,
@@ -93,7 +101,8 @@ export function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv> {
     router.onError(errorHandler);
 
     const authRepo = config.authRepo;
-    const { emailService, emailConfig, allowRegistration = false } = config;
+    const { emailService, emailConfig, allowRegistration = false, overrides } = config;
+    const ops = resolveAuthOverrides(overrides);
 
     // ── Zod input schemas ──────────────────────────────────────────────
     const registerSchema = z.object({
@@ -214,7 +223,7 @@ export function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv> {
         }
 
         // Validate password strength
-        const passwordValidation = validatePasswordStrength(password);
+        const passwordValidation = ops.validatePasswordStrength(password);
         if (!passwordValidation.valid) {
             throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
         }
@@ -226,12 +235,16 @@ export function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv> {
         }
 
         // Create user
-        const passwordHash = await hashPassword(password);
-        const user = await authRepo.createUser({
+        const passwordHash = await ops.hashPassword(password);
+        let createData: import("./interfaces").CreateUserData = {
             email: email.toLowerCase(),
             passwordHash,
             displayName: displayName || undefined
-        });
+        };
+        if (overrides?.beforeUserCreate) {
+            createData = await overrides.beforeUserCreate(createData);
+        }
+        const user = await authRepo.createUser(createData);
 
         // Auto-bootstrap: if this is the very first user in the system, promote to admin.
         // This avoids the chicken-and-egg problem where the first user has no permissions
@@ -256,6 +269,20 @@ export function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv> {
         sendWelcomeEmail({ email: user.email,
 displayName: user.displayName });
 
+        // Fire afterUserCreate hook (fire-and-forget)
+        if (overrides?.afterUserCreate) {
+            overrides.afterUserCreate(user).catch(err => {
+                console.error("[AuthOverrides] afterUserCreate error:", err instanceof Error ? err.message : err);
+            });
+        }
+
+        // Fire onAuthenticated hook (fire-and-forget)
+        if (overrides?.onAuthenticated) {
+            overrides.onAuthenticated(user, "register").catch(err => {
+                console.error("[AuthOverrides] onAuthenticated error:", err instanceof Error ? err.message : err);
+            });
+        }
+
         return c.json(buildAuthResponse(user, roleIds, accessToken, refreshToken), 201);
     });
 
@@ -266,18 +293,29 @@ displayName: user.displayName });
     router.post("/login", defaultAuthLimiter, async (c) => {
         const { email, password } = parseBody(loginSchema, await c.req.json());
 
-        const user = await authRepo.getUserByEmail(email);
-        if (!user) {
-            throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
-        }
+        let user;
 
-        if (!user.passwordHash) {
-            throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
-        }
+        if (overrides?.verifyCredentials) {
+            // Full credential verification override
+            user = await overrides.verifyCredentials(email, password, authRepo);
+            if (!user) {
+                throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+            }
+        } else {
+            // Default: email lookup + password hash verification
+            user = await authRepo.getUserByEmail(email);
+            if (!user) {
+                throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+            }
 
-        const isValidPassword = await verifyPassword(password, user.passwordHash);
-        if (!isValidPassword) {
-            throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+            if (!user.passwordHash) {
+                throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+            }
+
+            const isValidPassword = await ops.verifyPassword(password, user.passwordHash);
+            if (!isValidPassword) {
+                throw ApiError.unauthorized("Invalid email or password", "INVALID_CREDENTIALS");
+            }
         }
 
         const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(
@@ -286,6 +324,13 @@ displayName: user.displayName });
             c.req.header("x-forwarded-for") || "unknown"
         );
 
+        // Fire onAuthenticated hook (fire-and-forget)
+        if (overrides?.onAuthenticated) {
+            overrides.onAuthenticated(user, "login").catch(err => {
+                console.error("[AuthOverrides] onAuthenticated error:", err instanceof Error ? err.message : err);
+            });
+        }
+
         return c.json(buildAuthResponse(user, roleIds, accessToken, refreshToken));
     });
 
@@ -434,7 +479,7 @@ displayName: user.displayName }, appName);
         const { token, password } = parseBody(resetPasswordSchema, await c.req.json());
 
         // Validate password strength
-        const passwordValidation = validatePasswordStrength(password);
+        const passwordValidation = ops.validatePasswordStrength(password);
         if (!passwordValidation.valid) {
             throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
         }
@@ -448,7 +493,7 @@ displayName: user.displayName }, appName);
         }
 
         // Update password
-        const passwordHash = await hashPassword(password);
+        const passwordHash = await ops.hashPassword(password);
         await authRepo.updatePassword(storedToken.userId, passwordHash);
 
         // Mark token as used
@@ -480,19 +525,19 @@ message: "Password has been reset successfully" });
         }
 
         // Verify old password
-        const isValidOldPassword = await verifyPassword(oldPassword, user.passwordHash);
+        const isValidOldPassword = await ops.verifyPassword(oldPassword, user.passwordHash);
         if (!isValidOldPassword) {
             throw ApiError.unauthorized("Current password is incorrect", "INVALID_CREDENTIALS");
         }
 
         // Validate new password strength
-        const passwordValidation = validatePasswordStrength(newPassword);
+        const passwordValidation = ops.validatePasswordStrength(newPassword);
         if (!passwordValidation.valid) {
             throw ApiError.badRequest(passwordValidation.errors.join(". "), "WEAK_PASSWORD");
         }
 
         // Update password
-        const passwordHash = await hashPassword(newPassword);
+        const passwordHash = await ops.hashPassword(newPassword);
         await authRepo.updatePassword(user.id, passwordHash);
 
         // Invalidate all refresh tokens (security: log out all sessions)
@@ -727,7 +772,8 @@ message: "Session revoked successfully" });
                 displayName: result.user.displayName,
                 photoURL: result.user.photoUrl,
                 emailVerified: result.user.emailVerified,
-                roles: result.roles.map(r => r.id)
+                roles: result.roles.map(r => r.id),
+                metadata: result.user.metadata ?? {}
             }
         });
     });
@@ -765,7 +811,8 @@ message: "Session revoked successfully" });
                 displayName: result.user.displayName,
                 photoURL: result.user.photoUrl,
                 emailVerified: result.user.emailVerified,
-                roles: result.roles.map(r => r.id)
+                roles: result.roles.map(r => r.id),
+                metadata: result.user.metadata ?? {}
             }
         });
     });
@@ -788,18 +835,13 @@ message: "Session revoked successfully" });
         // Registration is allowed when explicitly enabled OR during initial setup
         const registrationAllowed = needsSetup || !!allowRegistration;
 
-        // Build a dynamic map of enabled providers for frontend discovery.
-        // Also maintain legacy boolean fields for backward compatibility.
+        // Build the list of enabled OAuth providers for frontend discovery.
         const enabledProviders = (config.oauthProviders || []).map(p => p.id);
 
         return c.json({
             needsSetup,
             registrationEnabled: registrationAllowed,
-            // Legacy fields (kept for backward compat)
-            googleEnabled: enabledProviders.includes("google"),
-            linkedinEnabled: enabledProviders.includes("linkedin"),
             emailServiceEnabled: isEmailConfigured(),
-            // New: complete list of available OAuth providers
             enabledProviders
         });
     });

package/src/cron/cron-scheduler.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals";
 import { CronScheduler, validateCronExpression } from "./cron-scheduler";
-import type { CronJobDefinition } from "@rebasepro/types";
+import type { CronJobDefinition, CronJobLogEntry } from "@rebasepro/types";
 import type { LoadedCronJob } from "./cron-loader";
 
 // ─── Helpers ────────────────────────────────────────────────────────
@@ -475,12 +475,12 @@ describe("CronScheduler", () => {
         beforeEach(() => { jest.useRealTimers(); });
 
         it("persists logs to store after execution", async () => {
-            const insertLog = jest.fn<(entry: any) => Promise<void>>().mockResolvedValue(undefined);
+            const insertLog = jest.fn<(entry: CronJobLogEntry) => Promise<void>>().mockResolvedValue(undefined);
             const mockStore = {
                 ensureTable: jest.fn<() => Promise<void>>().mockResolvedValue(undefined),
                 insertLog,
-                fetchLogs: jest.fn<() => Promise<any[]>>().mockResolvedValue([]),
-                fetchJobStats: jest.fn<() => Promise<Map<string, any>>>().mockResolvedValue(new Map()),
+                fetchLogs: jest.fn<() => Promise<CronJobLogEntry[]>>().mockResolvedValue([]),
+                fetchJobStats: jest.fn<() => Promise<Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string | Date | null }>>>().mockResolvedValue(new Map()),
             };
             scheduler.setStore(mockStore);
             scheduler.registerJobs([makeJob("persisted")]);
@@ -493,8 +493,8 @@ describe("CronScheduler", () => {
             const mockStore = {
                 ensureTable: jest.fn<() => Promise<void>>().mockResolvedValue(undefined),
                 insertLog: jest.fn<() => Promise<void>>().mockRejectedValue(new Error("DB down")),
-                fetchLogs: jest.fn<() => Promise<any[]>>().mockResolvedValue([]),
-                fetchJobStats: jest.fn<() => Promise<Map<string, any>>>().mockResolvedValue(new Map()),
+                fetchLogs: jest.fn<() => Promise<CronJobLogEntry[]>>().mockResolvedValue([]),
+                fetchJobStats: jest.fn<() => Promise<Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string | Date | null }>>>().mockResolvedValue(new Map()),
             };
             scheduler.setStore(mockStore);
             scheduler.registerJobs([makeJob("resilient")]);
@@ -504,13 +504,13 @@ describe("CronScheduler", () => {
         });
 
         it("seeds counters from store on start", async () => {
-            const stats = new Map<string, any>();
+            const stats = new Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string | Date | null }>();
             stats.set("seeded", { totalRuns: 42, totalFailures: 3, lastRunAt: "2026-01-01T00:00:00Z" });
             const mockStore = {
                 ensureTable: jest.fn<() => Promise<void>>().mockResolvedValue(undefined),
                 insertLog: jest.fn<() => Promise<void>>().mockResolvedValue(undefined),
-                fetchLogs: jest.fn<() => Promise<any[]>>().mockResolvedValue([]),
-                fetchJobStats: jest.fn<() => Promise<Map<string, any>>>().mockResolvedValue(stats),
+                fetchLogs: jest.fn<() => Promise<CronJobLogEntry[]>>().mockResolvedValue([]),
+                fetchJobStats: jest.fn<() => Promise<Map<string, { totalRuns: number; totalFailures: number; lastRunAt?: string | Date | null }>>>().mockResolvedValue(stats),
             };
             scheduler.setStore(mockStore);
             scheduler.registerJobs([makeJob("seeded")]);

package/src/cron/cron-scheduler.ts

@@ -15,7 +15,7 @@ import type { CronStore } from "./cron-store";
 
 /**
  * Expand a single cron field into an ordered array of allowed values.
- * Supports: `*`, `N`, `N-M`, `N/S`, `N-M/S`, `*​/S`, and comma-separated combinations.
+ * Supports: `*`, `N`, `N-M`, `N/S`, `N-M/S`, `*\/S`, and comma-separated combinations.
  */
 function expandCronField(field: string, min: number, max: number): number[] {
     const results = new Set<number>();

package/src/env.ts

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import * as crypto from "crypto";
+
+/**
+ * Generate a cryptographically secure random secret (hex-encoded).
+ * Used as a fallback when secrets are not explicitly configured —
+ * avoids the need for hardcoded dev secrets.
+ */
+function generateSecret(bytes = 48): string {
+    return crypto.randomBytes(bytes).toString("hex");
+}
+
+/**
+ * Zod coercion helper: transforms `"true"` → `true`, everything else → `false`.
+ */
+const boolString = z.enum(["true", "false", ""]).default("false").transform(v => v === "true");
+
+/**
+ * Zod coercion helper for optional boolean strings.
+ */
+const optionalBoolString = z.enum(["true", "false", ""]).optional().transform(v => v === "true");
+
+/**
+ * Helper to determine if a string is a localhost or loopback address/URL.
+ */
+function isLocalhostOrLoopback(value: string): boolean {
+    const trimmed = value.trim();
+    if (!trimmed) return false;
+
+    // 1. Try parsing as URL
+    try {
+        const parsed = new URL(trimmed);
+        const host = parsed.hostname.toLowerCase();
+        if (
+            host === "localhost" ||
+            host === "127.0.0.1" ||
+            host === "::1" ||
+            host.startsWith("127.")
+        ) {
+            return true;
+        }
+    } catch {
+        // Not a standard URL, or custom protocol that URL class fails to parse
+    }
+
+    // 2. Custom protocol parser fallback (e.g. postgres://, mongodb://, etc.)
+    const protocolMatch = trimmed.match(/^[a-zA-Z0-9+-.]+:\/\/(?:[^@/]+@)?(?:\[([^\]]+)\]|([^:/]+))/);
+    if (protocolMatch) {
+        const host = (protocolMatch[1] || protocolMatch[2] || "").toLowerCase();
+        if (
+            host === "localhost" ||
+            host === "127.0.0.1" ||
+            host === "::1" ||
+            host.startsWith("127.")
+        ) {
+            return true;
+        }
+    }
+
+    // 3. Plain hostname / host:port checker (e.g. "localhost", "127.0.0.1:5432", "[::1]:6379")
+    let plainHost = trimmed.toLowerCase();
+    if (plainHost.startsWith("[") && plainHost.includes("]")) {
+        const endBracket = plainHost.indexOf("]");
+        plainHost = plainHost.slice(1, endBracket);
+    } else {
+        const colonIndex = plainHost.lastIndexOf(":");
+        if (colonIndex !== -1 && plainHost.indexOf(":") === colonIndex) {
+            plainHost = plainHost.substring(0, colonIndex);
+        }
+    }
+
+    if (
+        plainHost === "localhost" ||
+        plainHost === "127.0.0.1" ||
+        plainHost === "::1" ||
+        plainHost.startsWith("127.")
+    ) {
+        return true;
+    }
+
+    return false;
+}
+
+/**
+ * The full set of environment variables recognized by a Rebase backend.
+ */
+const rebaseEnvSchema = z.object({
+    NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
+    PORT: z.string().default("3001").transform(Number),
+    DATABASE_URL: z.string().url("DATABASE_URL must be a valid URL"),
+    ADMIN_CONNECTION_STRING: z.string().url().optional(),
+    JWT_SECRET: z.string().min(32, "JWT_SECRET must be at least 32 characters long"),
+    JWT_ACCESS_EXPIRES_IN: z.string().default("1h"),
+    JWT_REFRESH_EXPIRES_IN: z.string().default("30d"),
+    GOOGLE_CLIENT_ID: z.string().optional(),
+    GOOGLE_CLIENT_SECRET: z.string().optional(),
+    REBASE_SERVICE_KEY: z.string().optional(),
+    ALLOW_REGISTRATION: boolString,
+    ALLOW_LOCALHOST_IN_PRODUCTION: optionalBoolString,
+    CORS_ORIGINS: z.string().optional(),
+    FRONTEND_URL: z.string().optional(),
+    DB_POOL_MAX: z.string().default("20").transform(Number),
+    DB_POOL_IDLE_TIMEOUT: z.string().default("30000").transform(Number),
+    DB_POOL_CONNECT_TIMEOUT: z.string().default("10000").transform(Number),
+    FORCE_LOCAL_STORAGE: optionalBoolString,
+    STORAGE_TYPE: z.enum(["local", "s3"]).default("local"),
+    STORAGE_PATH: z.string().optional(),
+    S3_BUCKET: z.string().optional(),
+    S3_REGION: z.string().optional(),
+    S3_ACCESS_KEY_ID: z.string().optional(),
+    S3_SECRET_ACCESS_KEY: z.string().optional(),
+    S3_ENDPOINT: z.string().url().optional(),
+    S3_FORCE_PATH_STYLE: optionalBoolString,
+});
+
+/** Inferred type of the validated environment. */
+export type RebaseEnv = z.infer<typeof rebaseEnvSchema>;
+
+/**
+ * Load and validate the Rebase environment configuration from `process.env`.
+ *
+ * Call this **after** your `.env` file has been loaded (via `dotenv`, `--env-file`,
+ * container injection, etc.). This function does not load `.env` files itself —
+ * that is a deployment concern, not a framework concern.
+ *
+ * Behavior:
+ * - Auto-generates ephemeral `JWT_SECRET` and `REBASE_SERVICE_KEY` in
+ *   non-production mode so developers can start without manual setup.
+ * - Blocks auto-generated secrets in production.
+ * - Returns a fully typed, validated env object.
+ *
+ * Use `extend` to add your own typed env variables on top of the base Rebase schema:
+ *
+ * @example
+ * ```ts
+ * import dotenv from "dotenv";
+ * import { z } from "zod";
+ * import { loadEnv } from "@rebasepro/server-core";
+ *
+ * dotenv.config({ path: "../../.env" });
+ *
+ * // Basic — just Rebase env vars:
+ * export const env = loadEnv();
+ *
+ * // Extended — add your own typed vars:
+ * export const env = loadEnv({
+ *     extend: z.object({
+ *         SMTP_HOST: z.string().optional(),
+ *         SMTP_PORT: z.string().default("587").transform(Number),
+ *         STRIPE_SECRET_KEY: z.string(),
+ *     })
+ * });
+ * // env.SMTP_HOST  → string | undefined  (fully typed)
+ * // env.STRIPE_SECRET_KEY → string        (validated, required)
+ * ```
+ */
+export function loadEnv(): RebaseEnv;
+export function loadEnv<E extends z.AnyZodObject>(options: { extend: E }): RebaseEnv & z.infer<E>;
+export function loadEnv(options?: { extend?: z.AnyZodObject }): Record<string, unknown> {
+    // Auto-generate dev secrets before validation so the Zod schema sees valid values.
+    const isProduction = process.env.NODE_ENV === "production";
+    const autoGeneratedSecrets: string[] = [];
+
+    if (!isProduction) {
+        if (!process.env.JWT_SECRET) {
+            process.env.JWT_SECRET = generateSecret();
+            autoGeneratedSecrets.push("JWT_SECRET");
+        }
+        if (!process.env.REBASE_SERVICE_KEY) {
+            process.env.REBASE_SERVICE_KEY = generateSecret();
+            autoGeneratedSecrets.push("REBASE_SERVICE_KEY");
+        }
+    }
+
+    // Merge base schema with user extensions (if provided).
+    const combinedSchema = options?.extend
+        ? rebaseEnvSchema.merge(options.extend)
+        : rebaseEnvSchema;
+
+    // Validate with production-specific refinements.
+    const schema = combinedSchema.superRefine((data, ctx) => {
+        const d = data as RebaseEnv & Record<string, unknown>;
+        if (d.NODE_ENV === "production" && !d.CORS_ORIGINS && !d.FRONTEND_URL) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "CORS_ORIGINS or FRONTEND_URL must be set in production to secure the API.",
+                path: ["CORS_ORIGINS"],
+            });
+        }
+        if (d.NODE_ENV === "production" && autoGeneratedSecrets.length > 0) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `${autoGeneratedSecrets.join(", ")} must be explicitly set in production. ` +
+                    `Do not rely on auto-generated secrets outside development.`,
+                path: [autoGeneratedSecrets[0]],
+            });
+        }
+        if (d.NODE_ENV === "production" && !d.ALLOW_LOCALHOST_IN_PRODUCTION) {
+            for (const [key, value] of Object.entries(data)) {
+                if (key === "CORS_ORIGINS") continue;
+                if (typeof value === "string" && isLocalhostOrLoopback(value)) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: `Environment variable ${key} contains a local/loopback URL or host "${value}". Deployed instances must not connect to localhost.`,
+                        path: [key],
+                    });
+                }
+            }
+        }
+    });
+
+    const env = schema.parse(process.env);
+
+    // Warn after successful parse so the server still starts in dev.
+    if (autoGeneratedSecrets.length > 0) {
+        console.warn(
+            `⚠️  Auto-generated secrets for: ${autoGeneratedSecrets.join(", ")}. ` +
+            `These are ephemeral — existing tokens will be invalidated on restart. ` +
+            `Set them explicitly in .env for persistent sessions.`,
+        );
+    }
+
+    return env as Record<string, unknown>;
+}

package/src/index.ts

@@ -62,5 +62,9 @@ export * from "./serve-spa";
 // Dev-mode port resolution (retry on EADDRINUSE)
 export * from "./utils/dev-port";
 
+// Environment validation
+export { loadEnv } from "./env";
+export type { RebaseEnv } from "./env";
+
 // Backend bootstrappers (pluggable driver initialization)