@rebasepro/server-core 0.5.0 → 0.6.0

package/src/auth/admin-user-ops.ts

@@ -0,0 +1,236 @@
+/**
+ * Admin User Operations
+ *
+ * Shared utilities and orchestration for admin-initiated user management
+ * (user creation via REST API, password reset via admin panel).
+ *
+ * Hook resolution order:
+ * 1. Collection-level hook (`auth.onCreateUser` on the collection) — closest to the data
+ * 2. Backend-level hook (`AuthHooks.onAdminCreateUser`) — global override
+ * 3. Built-in default — framework fallback
+ */
+
+import { randomBytes, createHash, randomInt } from "node:crypto";
+import type { AuthRepository } from "./interfaces";
+import type { EmailService, EmailConfig } from "../email";
+import type { ResolvedAuthHooks } from "./auth-hooks";
+import type { AuthCollectionConfig, AuthCollectionContext } from "@rebasepro/types";
+import { getPasswordResetTemplate } from "../email/templates";
+import { logger } from "../utils/logger";
+
+// ─── Shared Crypto Utilities ────────────────────────────────────────────────
+
+/**
+ * Generate a cryptographically secure random password that meets strength requirements.
+ *
+ * 16 characters, guaranteed at least one uppercase, one lowercase, one digit.
+ * Ambiguous characters (0, O, 1, l, I) are excluded.
+ */
+export function generateSecurePassword(): string {
+    const upper = "ABCDEFGHJKLMNPQRSTUVWXYZ";
+    const lower = "abcdefghjkmnpqrstuvwxyz";
+    const digits = "23456789";
+    const all = upper + lower + digits;
+
+    const pick = (chars: string) => chars[randomInt(chars.length)];
+    const parts = [pick(upper), pick(lower), pick(digits)];
+
+    for (let i = parts.length; i < 16; i++) {
+        parts.push(pick(all));
+    }
+
+    // Shuffle
+    for (let i = parts.length - 1; i > 0; i--) {
+        const j = randomInt(i + 1);
+        [parts[i], parts[j]] = [parts[j], parts[i]];
+    }
+    return parts.join("");
+}
+
+/**
+ * Generate a cryptographically secure random token (80 hex characters).
+ */
+export function generateSecureToken(): string {
+    return randomBytes(40).toString("hex");
+}
+
+/**
+ * Hash a token for database storage using SHA-256.
+ */
+export function hashToken(token: string): string {
+    return createHash("sha256").update(token).digest("hex");
+}
+
+// ─── Admin User Creation ────────────────────────────────────────────────────
+
+/**
+ * Context needed by admin user creation / password reset operations.
+ */
+export interface AdminUserContext {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    resolvedHooks: ResolvedAuthHooks;
+    /** The parsed auth config from the collection (if `auth` is an object, not just `true`). */
+    collectionAuthConfig?: AuthCollectionConfig;
+}
+
+/**
+ * Result of preparing user values for admin-initiated creation.
+ */
+export interface AdminUserPrepareResult {
+    /** Values ready for `driver.saveEntity()`. */
+    values: Record<string, unknown>;
+    /** The cleartext password (for returning to admin or sending via email). */
+    clearPassword?: string;
+    /** Whether the hook already handled the invitation email. */
+    hookHandledEmail: boolean;
+    /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
+    invitationSent: boolean;
+}
+
+/**
+ * Build the `AuthCollectionContext` facade from server internals.
+ *
+ * This is the simplified context exposed to collection-level auth hooks,
+ * keeping them decoupled from internal interfaces like `AuthRepository`.
+ */
+function buildCollectionContext(ctx: AdminUserContext): AuthCollectionContext {
+    const isEmailConfigured = !!(ctx.emailService && ctx.emailService.isConfigured());
+
+    return {
+        hashPassword: (password: string) => ctx.resolvedHooks.hashPassword(password),
+        sendEmail: isEmailConfigured
+            ? (options) => ctx.emailService!.send(options)
+            : undefined,
+        emailConfigured: isEmailConfigured,
+        appName: ctx.emailConfig?.appName || "Rebase",
+        resetPasswordUrl: ctx.emailConfig?.resetPasswordUrl || ""
+    };
+}
+
+/**
+ * Prepare user values for an admin-initiated user creation.
+ *
+ * Resolution order:
+ * 1. Collection-level `auth.onCreateUser` — closest to the data
+ * 2. Backend-level `AuthHooks.onAdminCreateUser` — global override
+ * 3. Built-in default — generate password → hash → normalize email
+ *
+ * The caller is responsible for persisting (via `driver.saveEntity()`).
+ */
+export async function prepareAdminUserValues(
+    body: Record<string, unknown>,
+    ctx: AdminUserContext
+): Promise<AdminUserPrepareResult> {
+    const { resolvedHooks, collectionAuthConfig } = ctx;
+
+    // 1. Collection-level hook (closest to the data)
+    if (collectionAuthConfig?.onCreateUser) {
+        const collectionCtx = buildCollectionContext(ctx);
+        const hookResult = await collectionAuthConfig.onCreateUser(body, collectionCtx);
+        return {
+            values: hookResult.values,
+            clearPassword: hookResult.temporaryPassword,
+            hookHandledEmail: true,
+            invitationSent: hookResult.invitationSent ?? false
+        };
+    }
+
+    // 2. Backend-level hook (global override)
+    if (resolvedHooks.onAdminCreateUser) {
+        const hookResult = await resolvedHooks.onAdminCreateUser(body, {
+            authRepo: ctx.authRepo,
+            emailService: ctx.emailService,
+            emailConfig: ctx.emailConfig,
+            hashPassword: (password: string) => resolvedHooks.hashPassword(password)
+        });
+        return {
+            values: hookResult.values,
+            clearPassword: hookResult.temporaryPassword,
+            hookHandledEmail: true,
+            invitationSent: hookResult.invitationSent ?? false
+        };
+    }
+
+    // 3. Built-in default
+    const password = body.password as string | undefined;
+    const clearPassword = password || generateSecurePassword();
+    const passwordHash = await resolvedHooks.hashPassword(clearPassword);
+
+    const values = { ...body };
+    values.passwordHash = passwordHash;
+    if (values.email) {
+        values.email = (values.email as string).toLowerCase();
+    }
+    values.emailVerified = true;
+    delete values.password;
+
+    return {
+        values,
+        clearPassword: password ? undefined : clearPassword,
+        hookHandledEmail: false,
+        invitationSent: false
+    };
+}
+
+/**
+ * Handle post-creation work for admin-created users.
+ *
+ * Sends an invitation email (password-reset link) if email is configured
+ * and no explicit password was provided. Falls back to returning the
+ * temporary password if email fails or is not configured.
+ */
+export async function finalizeAdminUserCreation(
+    entity: { id: string; values: Record<string, unknown> },
+    clearPassword: string | undefined,
+    ctx: AdminUserContext
+): Promise<{
+    temporaryPassword?: string;
+    invitationSent: boolean;
+}> {
+    // If an explicit password was provided (clearPassword is undefined), nothing to do
+    if (!clearPassword) {
+        return { invitationSent: false };
+    }
+
+    const isEmailConfigured = !!(ctx.emailService && ctx.emailService.isConfigured());
+
+    if (isEmailConfigured) {
+        try {
+            const token = generateSecureToken();
+            const tokenHash = hashToken(token);
+            const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours
+
+            await ctx.authRepo.createPasswordResetToken(entity.id, tokenHash, expiresAt);
+
+            const baseUrl = ctx.emailConfig?.resetPasswordUrl || "";
+            const setPasswordUrl = `${baseUrl}/reset-password?token=${token}`;
+
+            const appName = ctx.emailConfig?.appName || "Rebase";
+            const templateFn = ctx.emailConfig?.templates?.passwordReset;
+            const emailContent = templateFn
+                ? templateFn(setPasswordUrl, { email: entity.values.email as string,
+displayName: entity.values.displayName as string })
+                : getPasswordResetTemplate(setPasswordUrl, { email: entity.values.email as string,
+displayName: entity.values.displayName as string }, appName);
+
+            await ctx.emailService!.send({
+                to: entity.values.email as string,
+                subject: emailContent.subject,
+                html: emailContent.html,
+                text: emailContent.text
+            });
+            return { invitationSent: true };
+        } catch (emailError: unknown) {
+            logger.error("Failed to send reset email", { error: emailError instanceof Error ? emailError.message : emailError });
+            // Fall back to returning the temporary password
+            return { temporaryPassword: clearPassword,
+invitationSent: false };
+        }
+    }
+
+    // No email service — return the temporary password
+    return { temporaryPassword: clearPassword,
+invitationSent: false };
+}

package/src/auth/api-keys/api-key-middleware.ts

@@ -20,6 +20,7 @@ import type { HonoEnv } from "../../api/types";
 import type { ApiKeyStore } from "./api-key-store";
 import type { ApiKeyMasked } from "./api-key-types";
 import { scopeDataDriver } from "../rls-scope";
+import { logger } from "../../utils/logger";
 
 /**
  * Check whether a token looks like a Rebase API key.
@@ -55,7 +56,7 @@ export interface ApiKeyAuthOptions {
 export async function validateApiKey(
     c: Context<HonoEnv>,
     token: string,
-    options: ApiKeyAuthOptions,
+    options: ApiKeyAuthOptions
 ): Promise<Response | true> {
     const { store, driver } = options;
 
@@ -64,27 +65,31 @@ export async function validateApiKey(
 
     if (!apiKey) {
         return c.json({
-            error: { message: "Invalid API key", code: "UNAUTHORIZED" },
+            error: { message: "Invalid API key",
+code: "UNAUTHORIZED" }
         }, 401);
     }
 
     // Check revocation
     if (apiKey.revoked_at) {
         return c.json({
-            error: { message: "API key has been revoked", code: "UNAUTHORIZED" },
+            error: { message: "API key has been revoked",
+code: "UNAUTHORIZED" }
         }, 401);
     }
 
     // Check expiration
     if (apiKey.expires_at && new Date(apiKey.expires_at) < new Date()) {
         return c.json({
-            error: { message: "API key has expired", code: "UNAUTHORIZED" },
+            error: { message: "API key has expired",
+code: "UNAUTHORIZED" }
         }, 401);
     }
 
     // Set user identity — API keys represent service accounts
     const userId = `api-key:${apiKey.id}`;
-    c.set("user", { userId, roles: [] });
+    c.set("user", { userId,
+roles: [] });
 
     // Expose masked key metadata for downstream permission checks
     const masked: ApiKeyMasked = {
@@ -98,7 +103,7 @@ export async function validateApiKey(
         updated_at: apiKey.updated_at,
         last_used_at: apiKey.last_used_at,
         expires_at: apiKey.expires_at,
-        revoked_at: apiKey.revoked_at,
+        revoked_at: apiKey.revoked_at
     };
     // Store apiKey in the context for permission checking in api-generator
     c.set("apiKey", masked);
@@ -107,13 +112,14 @@ export async function validateApiKey(
     try {
         const scopedDriver = await scopeDataDriver(driver, {
             uid: userId,
-            roles: ["service"],
+            roles: ["service"]
         });
         c.set("driver", scopedDriver);
     } catch (error) {
-        console.error("[AUTH] RLS scoping failed for API key:", error);
+        logger.error("[AUTH] RLS scoping failed for API key", { error: error });
         return c.json({
-            error: { message: "Internal authentication error", code: "INTERNAL_ERROR" },
+            error: { message: "Internal authentication error",
+code: "INTERNAL_ERROR" }
         }, 500);
     }
 

package/src/auth/api-keys/api-key-permission-guard.ts

@@ -52,7 +52,7 @@ export function httpMethodToOperation(method: string): ApiKeyOperation {
 export function isOperationAllowed(
     permissions: ApiKeyPermission[],
     collection: string,
-    operation: ApiKeyOperation,
+    operation: ApiKeyOperation
 ): boolean {
     for (const perm of permissions) {
         const collectionMatch = perm.collection === "*" || perm.collection === collection;

package/src/auth/api-keys/api-key-routes.ts

@@ -68,7 +68,7 @@ export function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv> {
         if (!validatePermissions(permissions)) {
             throw ApiError.badRequest(
                 "Permissions must be an array of { collection: string, operations: ('read' | 'write' | 'delete')[] }",
-                "INVALID_INPUT",
+                "INVALID_INPUT"
             );
         }
 
@@ -97,7 +97,7 @@ export function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv> {
             name: name.trim(),
             permissions: permissions as ApiKeyPermission[],
             rate_limit: (rate_limit as number | null) ?? null,
-            expires_at: (expires_at as string | null) ?? null,
+            expires_at: (expires_at as string | null) ?? null
         };
 
         const keyWithSecret = await store.createApiKey(request, createdBy);
@@ -134,7 +134,7 @@ export function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv> {
             if (!validatePermissions(permissions)) {
                 throw ApiError.badRequest(
                     "Permissions must be an array of { collection: string, operations: ('read' | 'write' | 'delete')[] }",
-                    "INVALID_INPUT",
+                    "INVALID_INPUT"
                 );
             }
         }

package/src/auth/api-keys/api-key-store.ts

@@ -15,9 +15,10 @@ import { logger } from "../../utils/logger";
 import type {
     ApiKey,
     ApiKeyMasked,
+    ApiKeyPermission,
     ApiKeyWithSecret,
     CreateApiKeyRequest,
-    UpdateApiKeyRequest,
+    UpdateApiKeyRequest
 } from "./api-key-types";
 
 const TABLE = "rebase.api_keys";
@@ -64,7 +65,7 @@ function toMasked(row: ApiKey): ApiKeyMasked {
         updated_at: row.updated_at,
         last_used_at: row.last_used_at,
         expires_at: row.expires_at,
-        revoked_at: row.revoked_at,
+        revoked_at: row.revoked_at
     };
 }
 
@@ -72,9 +73,14 @@ function toMasked(row: ApiKey): ApiKeyMasked {
  * Parse a raw DB row into the typed `ApiKey` shape.
  */
 function rowToApiKey(row: Record<string, unknown>): ApiKey {
-    const permissions = typeof row.permissions === "string"
-        ? JSON.parse(row.permissions)
-        : (row.permissions ?? []);
+    let permissions = (row.permissions ?? []) as ApiKeyPermission[];
+    if (typeof row.permissions === "string") {
+        try {
+            permissions = JSON.parse(row.permissions) as ApiKeyPermission[];
+        } catch {
+            permissions = [];
+        }
+    }
 
     return {
         id: row.id as string,
@@ -90,7 +96,7 @@ function rowToApiKey(row: Record<string, unknown>): ApiKey {
         updated_at: new Date(row.updated_at as string).toISOString(),
         last_used_at: row.last_used_at ? new Date(row.last_used_at as string).toISOString() : null,
         expires_at: row.expires_at ? new Date(row.expires_at as string).toISOString() : null,
-        revoked_at: row.revoked_at ? new Date(row.revoked_at as string).toISOString() : null,
+        revoked_at: row.revoked_at ? new Date(row.revoked_at as string).toISOString() : null
     };
 }
 
@@ -212,7 +218,7 @@ export function createApiKeyStore(driver: DataDriver): ApiKeyStore | undefined {
             const apiKey = rowToApiKey(rows[0]);
             return {
                 ...toMasked(apiKey),
-                key: plaintext,
+                key: plaintext
             };
         },
 
@@ -312,6 +318,6 @@ export function createApiKeyStore(driver: DataDriver): ApiKeyStore | undefined {
                 // Non-blocking — don't fail requests because of a usage timestamp update
                 logger.error("[api-key-store] Failed to update last_used_at", { error: err });
             }
-        },
+        }
     };
 }

package/src/auth/api-keys/index.ts

@@ -14,7 +14,7 @@ export type {
     ApiKeyPermission,
     ApiKeyWithSecret,
     CreateApiKeyRequest,
-    UpdateApiKeyRequest,
+    UpdateApiKeyRequest
 } from "./api-key-types";
 
 // Store
@@ -28,7 +28,7 @@ export type { ApiKeyAuthOptions } from "./api-key-middleware";
 // Permission guard
 export {
     httpMethodToOperation,
-    isOperationAllowed,
+    isOperationAllowed
 } from "./api-key-permission-guard";
 export type { ApiKeyOperation } from "./api-key-permission-guard";
 

package/src/auth/apple-oauth.ts

@@ -1,6 +1,7 @@
 import type { OAuthProvider, OAuthProviderProfile } from "./interfaces";
 import { z } from "zod";
 import jwt from "jsonwebtoken";
+import { logger } from "../utils/logger";
 /**
  * Creates an Apple Sign In OAuth Provider integration.
  *
@@ -75,7 +76,7 @@ export function createAppleProvider(config: {
                 });
 
                 if (!tokenResponse.ok) {
-                    console.error("Failed to get Apple access token:", await tokenResponse.text());
+                    logger.error("Failed to get Apple access token", { detail: await tokenResponse.text() });
                     return null;
                 }
 
@@ -95,7 +96,7 @@ export function createAppleProvider(config: {
                 // the user object from the first auth for us to capture the name.
                 const email = decoded.email || payload.user?.email;
                 if (!email) {
-                    console.error("Apple user has no email");
+                    logger.error("Apple user has no email");
                     return null;
                 }
 
@@ -112,7 +113,7 @@ export function createAppleProvider(config: {
                     photoUrl: null // Apple does not provide a profile photo
                 };
             } catch (error) {
-                console.error("Apple OAuth error:", error);
+                logger.error("Apple OAuth error", { error: error });
                 return null;
             }
         }

package/src/auth/auth-hooks.ts

@@ -44,6 +44,7 @@ import {
 } from "./password";
 import type { PasswordValidationResult } from "./password";
 import type { AuthRepository, UserData, CreateUserData } from "./interfaces";
+import type { EmailService, EmailConfig } from "../email";
 
 /**
  * Authentication method identifier for lifecycle hooks.
@@ -205,28 +206,67 @@ export interface AuthHooks {
      * This is fire-and-forget — errors are logged but do not fail the request.
      */
     afterUserDelete?(userId: string): Promise<void>;
+
+    /**
+     * Optional hook to customize or override the default user creation flow via the admin panel/REST API.
+     * When provided, this replaces the built-in password generation, hashing, and invitation email logic.
+     */
+    onAdminCreateUser?(
+        values: Record<string, unknown>,
+        ctx: {
+            authRepo: AuthRepository;
+            emailService?: EmailService;
+            emailConfig?: EmailConfig;
+            hashPassword: (password: string) => Promise<string>;
+        }
+    ): Promise<{
+        values: Record<string, unknown>;
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+    }>;
+
+    /**
+     * Optional hook to customize or override the default password reset flow via the admin panel.
+     * When provided, this replaces the built-in password reset token generation, hashing, and email logic.
+     */
+    onAdminResetPassword?(
+        userId: string,
+        ctx: {
+            authRepo: AuthRepository;
+            emailService?: EmailService;
+            emailConfig?: EmailConfig;
+        }
+    ): Promise<{
+        temporaryPassword?: string;
+        invitationSent?: boolean;
+    }>;
 }
 
 /**
- * Resolved auth operations — every method is guaranteed to exist.
+ * Resolved auth hooks — password operations are guaranteed to exist,
+ * all other hooks are passed through as-is (optional).
+ *
  * Created by `resolveAuthHooks()` which merges user hooks
  * with built-in defaults.
+ *
+ * Consumers should use the resolved object exclusively —
+ * never access the raw `AuthHooks` directly.
  */
-export interface ResolvedAuthOperations {
-    hashPassword(password: string): Promise<string>;
-    verifyPassword(password: string, storedHash: string): Promise<boolean>;
-    validatePasswordStrength(password: string): PasswordValidationResult;
-}
+export type ResolvedAuthHooks =
+    Required<Pick<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">>
+    & Omit<AuthHooks, "hashPassword" | "verifyPassword" | "validatePasswordStrength">;
 
 /**
  * Merge user-provided hooks with the built-in defaults to produce
- * a complete set of resolved operations.
+ * a complete set of resolved hooks.
  *
  * This is the single point where defaults are applied — all consumers
- * call this once and use the resolved operations throughout.
+ * call this once and use the resolved hooks throughout.
  */
-export function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthOperations {
+export function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthHooks {
     return {
+        ...hooks,
+
         hashPassword: hooks?.hashPassword
             ?? defaultHashPassword,
 
@@ -234,6 +274,6 @@ export function resolveAuthHooks(hooks?: AuthHooks): ResolvedAuthOperations {
             ?? defaultVerifyPassword,
 
         validatePasswordStrength: hooks?.validatePasswordStrength
-            ?? defaultValidatePasswordStrength,
+            ?? defaultValidatePasswordStrength
     };
 }

package/src/auth/bitbucket-oauth.ts

@@ -1,5 +1,6 @@
 import type { OAuthProvider, OAuthProviderProfile } from "./interfaces";
 import { z } from "zod";
+import { logger } from "../utils/logger";
 
 /**
  * Creates a Bitbucket OAuth Provider integration (OAuth 2.0 consumer).
@@ -29,7 +30,7 @@ export function createBitbucketProvider(config: { clientId: string; clientSecret
                 });
 
                 if (!tokenResponse.ok) {
-                    console.error("Failed to get Bitbucket access token:", await tokenResponse.text());
+                    logger.error("Failed to get Bitbucket access token", { detail: await tokenResponse.text() });
                     return null;
                 }
 
@@ -41,7 +42,7 @@ export function createBitbucketProvider(config: { clientId: string; clientSecret
                 });
 
                 if (!profileResponse.ok) {
-                    console.error("Failed to get Bitbucket user info:", await profileResponse.text());
+                    logger.error("Failed to get Bitbucket user info", { detail: await profileResponse.text() });
                     return null;
                 }
 
@@ -65,7 +66,7 @@ export function createBitbucketProvider(config: { clientId: string; clientSecret
                     email = primary?.email || null;
                 }
 
-                if (!email) { console.error("Bitbucket user has no verified email"); return null; }
+                if (!email) { logger.error("Bitbucket user has no verified email"); return null; }
 
                 return {
                     providerId: p.uuid,
@@ -74,7 +75,7 @@ export function createBitbucketProvider(config: { clientId: string; clientSecret
                     photoUrl: p.links?.avatar?.href || null
                 };
             } catch (error) {
-                console.error("Bitbucket OAuth error:", error);
+                logger.error("Bitbucket OAuth error", { error: error });
                 return null;
             }
         }