@rebasepro/server-core 0.6.1 → 0.8.0

package/src/auth/auth-hooks.ts

@@ -45,6 +45,7 @@ import {
 import type { PasswordValidationResult } from "./password";
 import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
 import type { EmailService, EmailConfig } from "../email";
+import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
 
 /**
  * Authentication method identifier for lifecycle hooks.
@@ -181,6 +182,26 @@ export interface AuthHooks {
      */
     customizeAccessToken?(claims: Record<string, unknown>, user: UserData): Promise<Record<string, unknown>>;
 
+    /**
+     * Transform the auth response before sending it to the client.
+     *
+     * Called after successful login, register, refresh, OAuth, anonymous,
+     * magic-link, and MFA flows. The hook receives the fully-formed
+     * response and returns a (potentially enriched) response.
+     *
+     * Use cases:
+     * - Inject tokens from external auth systems (custom provider tokens, etc.)
+     * - Add project-specific metadata to the response
+     * - Enrich the user object with data from external sources
+     *
+     * The hook runs in the request path — keep it fast.
+     * Heavy work should be offloaded to `onAuthenticated` (fire-and-forget).
+     */
+    transformAuthResponse?(
+        response: AuthResponsePayload,
+        context: TransformAuthResponseContext
+    ): Promise<AuthResponsePayload>;
+
     /**
      * Called after a successful password reset.
      *

package/src/auth/bitbucket-oauth.ts

@@ -72,7 +72,8 @@ export function createBitbucketProvider(config: { clientId: string; clientSecret
                     providerId: p.uuid,
                     email,
                     displayName: p.display_name || p.username || null,
-                    photoUrl: p.links?.avatar?.href || null
+                    photoUrl: p.links?.avatar?.href || null,
+                    emailVerified: true
                 };
             } catch (error) {
                 logger.error("Bitbucket OAuth error", { error: error });

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

@@ -22,11 +22,13 @@ import type {
     BootstrappedAuth
 } from "@rebasepro/types";
 
-import type { Hono } from "hono";
+import { Hono } from "hono";
 import { verifyAccessToken } from "./jwt";
 import type { AccessTokenPayload } from "./jwt";
 import { createAuthRoutes } from "./routes";
 import { createResetPasswordRoute } from "./reset-password-admin";
+import { createAdminRolesRoute } from "./admin-roles-route";
+import { createAdminUsersRoute } from "./admin-users-route";
 import { prepareAdminUserValues, finalizeAdminUserCreation } from "./admin-user-ops";
 import type { AuthRepository, OAuthProvider } from "./interfaces";
 import type { AuthHooks, ResolvedAuthHooks } from "./auth-hooks";
@@ -54,14 +56,15 @@ export interface BuiltinAuthAdapterConfig {
     /** 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>[];
+    oauthProviders?: OAuthProvider<unknown>[];
     /** Static service key for server-to-server auth. */
     serviceKey?: string;
     /** Auth hooks for customizing password, credentials, lifecycle, etc. */
     authHooks?: AuthHooks;
     /** The parsed auth config from the collection (if `auth` is an object, not just `true`). */
     collectionAuthConfig?: import("@rebasepro/types").AuthCollectionConfig;
+    /** Enable magic link (passwordless email) login. Requires email service. */
+    enableMagicLink?: boolean;
 }
 
 /**
@@ -81,7 +84,8 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
         oauthProviders = [],
         serviceKey,
         authHooks,
-        collectionAuthConfig
+        collectionAuthConfig,
+        enableMagicLink = false
     } = config;
 
     const resolvedOps = resolveAuthHooks(authHooks);
@@ -188,12 +192,26 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
                 allowRegistration,
                 defaultRole,
                 oauthProviders,
-                authHooks
+                authHooks,
+                enableMagicLink
             });
         },
 
         createAdminRoutes(): Hono<HonoEnv> | undefined {
-            return createResetPasswordRoute({
+            const router = new Hono<HonoEnv>();
+            const resetPasswordRoute = createResetPasswordRoute({
+                authRepo: authRepository,
+                emailService,
+                emailConfig,
+                serviceKey,
+                authHooks,
+                collectionAuthConfig
+            });
+            const rolesRoute = createAdminRolesRoute({
+                authRepo: authRepository,
+                serviceKey
+            });
+            const adminUsersRoute = createAdminUsersRoute({
                 authRepo: authRepository,
                 emailService,
                 emailConfig,
@@ -201,6 +219,10 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
                 authHooks,
                 collectionAuthConfig
             });
+            router.route("/", resetPasswordRoute);
+            router.route("/", rolesRoute);
+            router.route("/", adminUsersRoute);
+            return router;
         },
 
         async prepareUserCreation(values, collectionAuth) {
@@ -245,6 +267,7 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
                 sessionManagement: true,
                 profileUpdate: true,
                 emailVerification: !!emailService?.isConfigured(),
+                magicLink: enableMagicLink && !!emailService?.isConfigured(),
                 enabledProviders,
                 needsSetup
             };

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

@@ -51,6 +51,7 @@ export function createCustomAuthAdapter(options: CustomAuthAdapterOptions): Auth
         sessionManagement: false,
         profileUpdate: false,
         emailVerification: false,
+        magicLink: false,
         enabledProviders: [],
         ...options.capabilities
     };
@@ -76,6 +77,7 @@ export function createCustomAuthAdapter(options: CustomAuthAdapterOptions): Auth
 
         userManagement: options.userManagement,
 
+        transformAuthResponse: options.transformAuthResponse,
 
         getCapabilities() {
             return defaultCapabilities;

package/src/auth/discord-oauth.ts

@@ -73,7 +73,8 @@ export function createDiscordProvider(config: { clientId: string; clientSecret:
                     providerId: profileData.id,
                     email: profileData.email,
                     displayName: profileData.global_name || profileData.username || null,
-                    photoUrl
+                    photoUrl,
+                    emailVerified: profileData.verified === true
                 };
             } catch (error) {
                 logger.error("Discord OAuth error", { error: error });

package/src/auth/facebook-oauth.ts

@@ -62,7 +62,8 @@ export function createFacebookProvider(config: { clientId: string; clientSecret:
                     providerId: profileData.id,
                     email: profileData.email,
                     displayName: profileData.name || null,
-                    photoUrl: profileData.picture?.data?.url || null
+                    photoUrl: profileData.picture?.data?.url || null,
+                    emailVerified: true
                 };
             } catch (error) {
                 logger.error("Facebook OAuth error", { error: error });

package/src/auth/github-oauth.ts

@@ -100,7 +100,8 @@ export function createGitHubProvider(config: { clientId: string; clientSecret: s
                     providerId: String(profileData.id),
                     email,
                     displayName: profileData.name || profileData.login || null,
-                    photoUrl: profileData.avatar_url || null
+                    photoUrl: profileData.avatar_url || null,
+                    emailVerified: true
                 };
             } catch (error) {
                 logger.error("GitHub OAuth error", { error: error });

package/src/auth/gitlab-oauth.ts

@@ -60,7 +60,8 @@ export function createGitLabProvider(config: {
                     providerId: String(p.id),
                     email: p.email,
                     displayName: p.name || p.username || null,
-                    photoUrl: p.avatar_url || null
+                    photoUrl: p.avatar_url || null,
+                    emailVerified: true
                 };
             } catch (error) {
                 logger.error("GitLab OAuth error", { error: error });

package/src/auth/google-oauth.ts

@@ -89,7 +89,8 @@ export function createGoogleProvider(config: GoogleProviderConfig | string): OAu
                         providerId: content.sub,
                         email: content.email || "",
                         displayName: content.name || null,
-                        photoUrl: content.picture || null
+                        photoUrl: content.picture || null,
+                        emailVerified: true
                     };
                 }
 
@@ -115,7 +116,8 @@ export function createGoogleProvider(config: GoogleProviderConfig | string): OAu
                         providerId: info.sub,
                         email: info.email,
                         displayName: info.name || null,
-                        photoUrl: info.picture || null
+                        photoUrl: info.picture || null,
+                        emailVerified: true
                     };
                 }
 
@@ -176,7 +178,8 @@ export function createGoogleProvider(config: GoogleProviderConfig | string): OAu
                             providerId: content.sub,
                             email: content.email || "",
                             displayName: content.name || null,
-                            photoUrl: content.picture || null
+                            photoUrl: content.picture || null,
+                            emailVerified: true
                         };
                     }
 
@@ -202,7 +205,8 @@ export function createGoogleProvider(config: GoogleProviderConfig | string): OAu
                             providerId: info.sub,
                             email: info.email,
                             displayName: info.name || null,
-                            photoUrl: info.picture || null
+                            photoUrl: info.picture || null,
+                            emailVerified: true
                         };
                     }
 

package/src/auth/index.ts

@@ -35,6 +35,8 @@ export type { AuthMiddlewareOptions, AuthResult } from "./middleware";
 export { createAuthRoutes } from "./routes";
 export type { AuthModuleConfig } from "./routes";
 
+export { mountMagicLinkRoutes } from "./magic-link-routes";
+
 export { createResetPasswordRoute } from "./reset-password-admin";
 export type { ResetPasswordRouteConfig } from "./reset-password-admin";
 

package/src/auth/interfaces.ts

@@ -60,6 +60,8 @@ export interface OAuthProviderProfile {
     email: string;
     displayName?: string | null;
     photoUrl?: string | null;
+    /** Whether the OAuth provider has verified the user's email address */
+    emailVerified?: boolean;
 }
 
 /**
@@ -72,8 +74,17 @@ export interface OAuthProvider<T = unknown> {
     /** Zod schema validating the expected request payload (e.g. { code: string }) */
     schema: z.ZodSchema<T>;
 
-    /** Verify external tokens/codes and return a standardized user profile */
-    verify: (payload: T) => Promise<OAuthProviderProfile | null>;
+    /**
+     * Verify external tokens/codes and return a standardized user profile.
+     *
+     * NOTE: Declared as method syntax (not arrow property) intentionally.
+     * This makes `OAuthProvider` bivariant in `T`, which is correct because
+     * each provider is self-contained — `schema` validates the request body
+     * and `verify` consumes the same `T`. Bivariance lets heterogeneous
+     * providers (`OAuthProvider<SpecificPayload>`) coexist in a single
+     * `OAuthProvider<unknown>[]` array without resorting to `any`.
+     */
+    verify(payload: T): Promise<OAuthProviderProfile | null>;
 }
 
 /**
@@ -129,6 +140,14 @@ export interface PasswordResetTokenInfo {
     expiresAt: Date;
 }
 
+/**
+ * Magic link token info
+ */
+export interface MagicLinkTokenInfo {
+    userId: string;
+    expiresAt: Date;
+}
+
 // =============================================================================
 // AUTH REPOSITORY INTERFACES
 // =============================================================================
@@ -357,6 +376,23 @@ export interface TokenRepository {
      * Clean up expired tokens
      */
     deleteExpiredTokens(): Promise<void>;
+
+    // Magic link tokens
+
+    /**
+     * Create a magic link token
+     */
+    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+
+    /**
+     * Find a valid (not expired, not used) magic link token by hash
+     */
+    findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
+
+    /**
+     * Mark a magic link token as used
+     */
+    markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
 }
 
 // =============================================================================

package/src/auth/linkedin-oauth.ts

@@ -71,7 +71,8 @@ export function createLinkedinProvider(config: { clientId: string, clientSecret:
                     providerId: profileData.sub,
                     email: profileData.email,
                     displayName: profileData.name || null,
-                    photoUrl: profileData.picture || null
+                    photoUrl: profileData.picture || null,
+                    emailVerified: profileData.email_verified === true
                 };
             } catch (error) {
                 logger.error("LinkedIn OAuth error", { error: error });

package/src/auth/magic-link-routes.ts

@@ -0,0 +1,167 @@
+import { Hono } from "hono";
+import type { AuthModuleConfig } from "./routes";
+import type { ResolvedAuthHooks } from "./auth-hooks";
+import type { HonoEnv } from "../api/types";
+import { ApiError } from "../api/errors";
+import { generateSecureToken, hashToken } from "./admin-user-ops";
+import { getMagicLinkTemplate } from "../email/templates";
+import { strictAuthLimiter } from "./rate-limiter";
+import { z } from "zod";
+import { logger } from "../utils/logger";
+import type { AuthResponsePayload, TransformAuthResponseContext } from "@rebasepro/types";
+
+/**
+ * Magic link token expiry (15 minutes from now)
+ */
+function getMagicLinkExpiry(): Date {
+    return new Date(Date.now() + 15 * 60 * 1000);
+}
+
+/**
+ * Mount magic link routes onto the auth router.
+ *
+ * Follows the same delegation pattern as `mountMfaRoutes()` and `mountSessionRoutes()`.
+ */
+export function mountMagicLinkRoutes(deps: {
+    router: Hono<HonoEnv>;
+    config: AuthModuleConfig;
+    ops: ResolvedAuthHooks;
+    parseBody: <T>(schema: z.ZodSchema<T>, body: unknown) => T;
+    buildAuthResponse: (
+        user: { id: string; email: string; displayName?: string | null; photoUrl?: string | null; metadata?: Record<string, unknown> | null },
+        roleIds: string[],
+        accessToken: string,
+        refreshToken: string
+    ) => unknown;
+    createSessionAndTokens: (userId: string, userAgent: string, ipAddress: string) => Promise<{ roleIds: string[]; accessToken: string; refreshToken: string }>;
+    applyTransformHook: (
+        response: AuthResponsePayload,
+        method: TransformAuthResponseContext["method"],
+        request: Request,
+        userId: string
+    ) => Promise<AuthResponsePayload>;
+}) {
+    const { router, config, ops, parseBody, buildAuthResponse, createSessionAndTokens, applyTransformHook } = deps;
+    const { authRepo, emailService, emailConfig } = config;
+
+    const magicLinkSchema = z.object({
+        email: z.string().email("Invalid email address").max(255)
+    });
+
+    const verifyMagicLinkSchema = z.object({
+        token: z.string().min(1, "Token is required")
+    });
+
+    function isEmailConfigured(): boolean {
+        return !!(emailService && emailService.isConfigured());
+    }
+
+    /**
+     * POST /auth/magic-link
+     * Request a magic link email
+     */
+    router.post("/magic-link", strictAuthLimiter, async (c) => {
+        const { email } = parseBody(magicLinkSchema, await c.req.json());
+
+        // Require email service
+        if (!isEmailConfigured()) {
+            throw ApiError.serviceUnavailable("Email service not configured. Magic link login is not available.", "EMAIL_NOT_CONFIGURED");
+        }
+
+        // Always return success (security: don't reveal if email exists)
+        const user = await authRepo.getUserByEmail(email);
+
+        if (user) {
+            // Call beforeLogin hook if provided (throw to reject)
+            if (ops.beforeLogin) {
+                await ops.beforeLogin(email, "magic-link");
+            }
+
+            // Generate magic link token
+            const token = generateSecureToken();
+            const tokenHash = hashToken(token);
+            const expiresAt = getMagicLinkExpiry();
+
+            await authRepo.createMagicLinkToken(user.id, tokenHash, expiresAt);
+
+            // Build magic link URL
+            const baseUrl = emailConfig?.magicLinkUrl || emailConfig?.resetPasswordUrl || "";
+            const magicLinkUrl = `${baseUrl}/auth/magic-link?token=${token}`;
+
+            // Get email template
+            const appName = emailConfig?.appName || "Rebase";
+            const templateFn = emailConfig?.templates?.magicLink;
+            const emailContent = templateFn
+                ? templateFn(magicLinkUrl, { email: user.email, displayName: user.displayName })
+                : getMagicLinkTemplate(magicLinkUrl, { email: user.email, displayName: user.displayName }, appName);
+
+            // Send email
+            try {
+                await emailService!.send({
+                    to: user.email,
+                    subject: emailContent.subject,
+                    html: emailContent.html,
+                    text: emailContent.text
+                });
+            } catch (emailError: unknown) {
+                logger.error("Failed to send magic link email", { error: emailError instanceof Error ? emailError.message : emailError });
+                // Don't reveal email sending failure to client
+            }
+        }
+
+        // Always return success
+        return c.json({
+            success: true,
+            message: "If an account with that email exists, a magic link has been sent."
+        });
+    });
+
+    /**
+     * POST /auth/magic-link/verify
+     * Verify magic link token and create session
+     */
+    router.post("/magic-link/verify", strictAuthLimiter, async (c) => {
+        const { token } = parseBody(verifyMagicLinkSchema, await c.req.json());
+
+        // Find valid token
+        const tokenHash = hashToken(token);
+        const storedToken = await authRepo.findValidMagicLinkToken(tokenHash);
+
+        if (!storedToken) {
+            throw ApiError.badRequest("Invalid or expired magic link", "INVALID_TOKEN");
+        }
+
+        // Mark token as used (one-time use)
+        await authRepo.markMagicLinkTokenUsed(tokenHash);
+
+        // Get user
+        const user = await authRepo.getUserById(storedToken.userId);
+        if (!user) {
+            throw ApiError.badRequest("Invalid or expired magic link", "INVALID_TOKEN");
+        }
+
+        // Clicking a magic link proves email ownership — auto-verify
+        if (!user.emailVerified) {
+            await authRepo.setEmailVerified(user.id, true);
+            user.emailVerified = true;
+        }
+
+        // Create session
+        const { roleIds, accessToken, refreshToken } = await createSessionAndTokens(
+            user.id,
+            c.req.header("user-agent") || "unknown",
+            c.req.header("x-forwarded-for") || "unknown"
+        );
+
+        // Fire onAuthenticated hook (fire-and-forget)
+        if (ops.onAuthenticated) {
+            ops.onAuthenticated(user, "magic-link").catch(err => {
+                logger.error("[AuthHooks] onAuthenticated error", { error: err instanceof Error ? err.message : err });
+            });
+        }
+
+        const authResponse = buildAuthResponse(user, roleIds, accessToken, refreshToken) as AuthResponsePayload;
+        const finalResponse = await applyTransformHook(authResponse, "magic-link", c.req.raw, user.id);
+        return c.json(finalResponse);
+    });
+}

package/src/auth/mfa-crypto.ts

@@ -0,0 +1,91 @@
+/**
+ * Envelope encryption for TOTP secrets using AES-256-GCM.
+ *
+ * - Derives a 32-byte key via SHA-256 from `MFA_ENCRYPTION_KEY` or `JWT_SECRET`.
+ * - Generates a random 12-byte IV per encryption call.
+ * - Returns ciphertexts in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ *
+ * @module
+ */
+
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "crypto";
+import { logger } from "../utils/logger";
+
+const ALGORITHM = "aes-256-gcm";
+const IV_BYTES = 12;
+const AUTH_TAG_LENGTH = 16;
+
+/**
+ * Resolve the raw key string from environment variables.
+ *
+ * Prefers `MFA_ENCRYPTION_KEY`; falls back to `JWT_SECRET` with a warning.
+ * Throws if neither is set.
+ */
+function resolveKeyString(): string {
+    const explicit = process.env.MFA_ENCRYPTION_KEY;
+    if (explicit) {
+        return explicit;
+    }
+
+    const fallback = process.env.JWT_SECRET;
+    if (fallback) {
+        logger.warn(
+            "[MFA-Crypto] MFA_ENCRYPTION_KEY is not set — falling back to JWT_SECRET. " +
+                "Set a dedicated MFA_ENCRYPTION_KEY for production."
+        );
+        return fallback;
+    }
+
+    throw new Error(
+        "Cannot encrypt TOTP secret: neither MFA_ENCRYPTION_KEY nor JWT_SECRET is configured."
+    );
+}
+
+/**
+ * Derive a deterministic 32-byte AES-256 key from the raw secret string.
+ */
+function deriveKey(raw: string): Buffer {
+    return createHash("sha256").update(raw).digest();
+}
+
+/**
+ * Encrypt a plaintext TOTP secret.
+ *
+ * @param plaintext - The Base32 TOTP secret to encrypt.
+ * @returns A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ */
+export function encryptTotpSecret(plaintext: string): string {
+    const key = deriveKey(resolveKeyString());
+    const iv = randomBytes(IV_BYTES);
+
+    const cipher = createCipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    return `${iv.toString("hex")}:${authTag.toString("hex")}:${encrypted.toString("hex")}`;
+}
+
+/**
+ * Decrypt a previously encrypted TOTP secret.
+ *
+ * @param ciphertext - A string in the format `iv_hex:authTag_hex:ciphertext_hex`.
+ * @returns The original Base32 TOTP secret.
+ */
+export function decryptTotpSecret(ciphertext: string): string {
+    const parts = ciphertext.split(":");
+    if (parts.length !== 3) {
+        throw new Error("Invalid encrypted TOTP secret format — expected iv:authTag:ciphertext");
+    }
+
+    const [ivHex, authTagHex, encryptedHex] = parts;
+    const key = deriveKey(resolveKeyString());
+    const iv = Buffer.from(ivHex, "hex");
+    const authTag = Buffer.from(authTagHex, "hex");
+    const encrypted = Buffer.from(encryptedHex, "hex");
+
+    const decipher = createDecipheriv(ALGORITHM, key, iv, { authTagLength: AUTH_TAG_LENGTH });
+    decipher.setAuthTag(authTag);
+
+    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    return decrypted.toString("utf8");
+}