@rebasepro/server-core 0.0.1-canary.4d4fb3e

package/dist/server-core/src/auth/middleware.d.ts

@@ -0,0 +1,56 @@
+import { MiddlewareHandler, Context } from "hono";
+import { DataDriver } from "@rebasepro/types";
+import { AccessTokenPayload } from "./jwt";
+import { HonoEnv } from "../api/types";
+/**
+ * Result from a custom auth validator.
+ * - `false`/`null`/`undefined` = not authenticated
+ * - `true` = authenticated as default user
+ * - object with `userId` or `uid` = authenticated with user info
+ */
+export type AuthResult = boolean | null | undefined | {
+    userId?: string;
+    uid?: string;
+    roles?: string[];
+    [key: string]: unknown;
+};
+/**
+ * Options for creating an auth middleware via createAuthMiddleware()
+ */
+export interface AuthMiddlewareOptions {
+    /** DataDriver to scope via withAuth() for RLS */
+    driver: DataDriver;
+    /** If true, return 401 when no valid token is present (default: false) */
+    requireAuth?: boolean;
+    /** Optional custom validator (for non-JWT auth, e.g. Firebase Auth) */
+    validator?: (c: Context<HonoEnv>) => Promise<AuthResult>;
+}
+/**
+ * Express middleware that requires a valid JWT token
+ * Returns 401 if token is missing or invalid
+ */
+export declare const requireAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that requires the user to have an admin or schema-admin role.
+ * Must be used AFTER requireAuth or on a route where user is guaranteed.
+ */
+export declare const requireAdmin: MiddlewareHandler<HonoEnv>;
+/**
+ * Middleware that optionally extracts user from JWT
+ * Does not return 401 if token is missing - allows anonymous access
+ */
+export declare const optionalAuth: MiddlewareHandler<HonoEnv>;
+/**
+ * Extract user from token - for WebSocket authentication
+ */
+export declare function extractUserFromToken(token: string): AccessTokenPayload | null;
+/**
+ * Create a configurable auth middleware that handles:
+ * 1. Token extraction (via custom validator or JWT Bearer token)
+ * 2. RLS-scoped DataDriver via withAuth()
+ * 3. Optional enforcement (401 when requireAuth is true and no user)
+ *
+ * This is the single source of truth for HTTP auth in Rebase.
+ * Use this instead of manually parsing tokens in route handlers.
+ */
+export declare function createAuthMiddleware(options: AuthMiddlewareOptions): MiddlewareHandler<HonoEnv>;

package/dist/server-core/src/auth/password.d.ts

@@ -0,0 +1,22 @@
+export interface PasswordValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Password requirements:
+ * - Minimum 8 characters
+ * - At least 1 uppercase letter
+ * - At least 1 lowercase letter
+ * - At least 1 number
+ */
+export declare function validatePasswordStrength(password: string): PasswordValidationResult;
+/**
+ * Hash a password using Node's built-in scrypt
+ * Returns format: salt:hash (both hex encoded)
+ */
+export declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify a password against a scrypt hash
+ * Expects format: salt:hash (both hex encoded)
+ */
+export declare function verifyPassword(password: string, storedHash: string): Promise<boolean>;

package/dist/server-core/src/auth/rate-limiter.d.ts

@@ -0,0 +1,31 @@
+import { MiddlewareHandler } from "hono";
+import { HonoEnv } from "../api/types";
+interface RateLimiterOptions {
+    /** Time window in milliseconds (default: 15 minutes) */
+    windowMs?: number;
+    /** Maximum requests per window (default: 100) */
+    limit?: number;
+    /** Key generator function. Defaults to IP-based keying. */
+    keyGenerator?: (c: Parameters<MiddlewareHandler<HonoEnv>>[0]) => string;
+    /** Custom message for rate limit responses */
+    message?: string;
+}
+/**
+ * Create a rate-limiting middleware.
+ *
+ * Uses a sliding window algorithm: only timestamps within the last
+ * `windowMs` milliseconds are counted. Old entries are garbage-collected
+ * every `windowMs` to prevent unbounded memory growth.
+ */
+export declare function createRateLimiter(options?: RateLimiterOptions): MiddlewareHandler<HonoEnv>;
+/**
+ * Pre-configured rate limiter for general auth endpoints (login, register).
+ * 20 requests per 15 minutes per IP.
+ */
+export declare const defaultAuthLimiter: MiddlewareHandler<HonoEnv>;
+/**
+ * Pre-configured strict rate limiter for sensitive endpoints (password reset, verification).
+ * 5 requests per 15 minutes per IP.
+ */
+export declare const strictAuthLimiter: MiddlewareHandler<HonoEnv>;
+export {};

package/dist/server-core/src/auth/routes.d.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+import type { AuthRepository } from "./interfaces";
+import { EmailService, EmailConfig } from "../email";
+import { HonoEnv } from "../api/types";
+/**
+ * Shared configuration for auth and admin route factories.
+ */
+export interface AuthModuleConfig {
+    authRepo: AuthRepository;
+    emailService?: EmailService;
+    emailConfig?: EmailConfig;
+    /** Allow new user registration (default: false). First user can always register for bootstrap. */
+    allowRegistration?: boolean;
+    /** Default role ID to assign to new users (default: none). The first user always gets "admin". */
+    defaultRole?: string;
+}
+export declare function createAuthRoutes(config: AuthModuleConfig): Hono<HonoEnv>;

package/dist/server-core/src/collections/BackendCollectionRegistry.d.ts

@@ -0,0 +1,13 @@
+import { CollectionRegistry } from "@rebasepro/common";
+import { CollectionRegistryInterface } from "../db/interfaces";
+/**
+ * Backend-agnostic collection registry.
+ * Satisfies CollectionRegistryInterface through inheritance from CollectionRegistry.
+ */
+export declare class BackendCollectionRegistry extends CollectionRegistry implements CollectionRegistryInterface {
+    /**
+     * Get the available relation keys for a given collection path.
+     * Maps from the collection's relation property names to the relation names.
+     */
+    getRelationKeysForCollection(collectionPath: string): string[];
+}

package/dist/server-core/src/collections/loader.d.ts

@@ -0,0 +1,5 @@
+import { EntityCollection } from "@rebasepro/types";
+/**
+ * Asynchronously load collection files from a directory for backend initialization
+ */
+export declare function loadCollectionsFromDirectory(directory: string): Promise<EntityCollection[]>;

package/dist/server-core/src/db/interfaces.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Database Abstraction Interfaces
+ *
+ * These interfaces define the contracts that any database backend must implement
+ * to be used with Rebase. This allows for pluggable database backends like
+ * PostgreSQL, MongoDB, MySQL, etc.
+ */
+import { DatabaseConnection, QueryFilter, FetchCollectionOptions, SearchOptions, CountOptions, ConditionBuilder, ConditionBuilderStatic, EntityRepository, CollectionSubscriptionConfig, EntitySubscriptionConfig, RealtimeProvider, CollectionRegistryInterface, DataTransformer, BackendConfig, BackendInstance, BackendFactory } from "@rebasepro/types";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { PgTransaction } from "drizzle-orm/pg-core";
+/**
+ * Type representing either a direct database connection or a transaction.
+ * Used to allow services to operate within a transaction context.
+ * Note: `any` is intentional here — it represents a Drizzle client with
+ * a dynamic schema, enabling `db.query[tableName]` access without casts.
+ */
+export type DrizzleClient = NodePgDatabase<Record<string, unknown>> | PgTransaction<any, any, any>;
+export type { DatabaseConnection, QueryFilter, FetchCollectionOptions, SearchOptions, CountOptions, ConditionBuilder, ConditionBuilderStatic, EntityRepository, CollectionSubscriptionConfig, EntitySubscriptionConfig, RealtimeProvider, CollectionRegistryInterface, DataTransformer, BackendConfig, BackendInstance, BackendFactory };

package/dist/server-core/src/email/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Email module exports
+ */
+export type { EmailService, EmailSendOptions, SMTPConfig, EmailConfig, PasswordResetTemplateFunction, EmailVerificationTemplateFunction, UserInvitationTemplateFunction } from "./types";
+export { SMTPEmailService, createEmailService } from "./smtp-email-service";
+export { getPasswordResetTemplate, getEmailVerificationTemplate, getUserInvitationTemplate } from "./templates";

package/dist/server-core/src/email/smtp-email-service.d.ts

@@ -0,0 +1,25 @@
+import { EmailService, EmailSendOptions, EmailConfig } from "./types";
+/**
+ * SMTP Email Service implementation using Nodemailer
+ */
+export declare class SMTPEmailService implements EmailService {
+    private transporter;
+    private config;
+    constructor(config: EmailConfig);
+    /**
+     * Check if the email service is properly configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Send an email using SMTP or custom send function
+     */
+    send(options: EmailSendOptions): Promise<void>;
+    /**
+     * Verify SMTP connection (useful for startup checks)
+     */
+    verifyConnection(): Promise<boolean>;
+}
+/**
+ * Create an email service from configuration
+ */
+export declare function createEmailService(config: EmailConfig): EmailService;

package/dist/server-core/src/email/templates.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Default email templates for authentication emails
+ */
+interface TemplateUser {
+    email: string;
+    displayName?: string | null;
+}
+/**
+ * Default password reset email template
+ */
+export declare function getPasswordResetTemplate(resetUrl: string, user: TemplateUser, appName?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+/**
+ * Default email verification template
+ */
+export declare function getEmailVerificationTemplate(verifyUrl: string, user: TemplateUser, appName?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+/**
+ * Default user invitation email template
+ * Sent when an admin creates a new user account
+ */
+export declare function getUserInvitationTemplate(setPasswordUrl: string, user: TemplateUser, appName?: string): {
+    subject: string;
+    html: string;
+    text: string;
+};
+export {};

package/dist/server-core/src/email/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Email service types and interfaces
+ */
+/**
+ * Options for sending an email
+ */
+export interface EmailSendOptions {
+    to: string;
+    subject: string;
+    html: string;
+    text?: string;
+}
+/**
+ * Email service interface - abstraction for sending emails
+ */
+export interface EmailService {
+    /**
+     * Send an email
+     */
+    send(options: EmailSendOptions): Promise<void>;
+    /**
+     * Check if the email service is properly configured
+     */
+    isConfigured(): boolean;
+}
+/**
+ * SMTP server configuration
+ */
+export interface SMTPConfig {
+    host: string;
+    port: number;
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+}
+/**
+ * Template function for password reset emails
+ */
+export type PasswordResetTemplateFunction = (resetUrl: string, user: {
+    email: string;
+    displayName?: string | null;
+}) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Template function for email verification emails
+ */
+export type EmailVerificationTemplateFunction = (verifyUrl: string, user: {
+    email: string;
+    displayName?: string | null;
+}) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Template function for user invitation emails
+ */
+export type UserInvitationTemplateFunction = (setPasswordUrl: string, user: {
+    email: string;
+    displayName?: string | null;
+}) => {
+    subject: string;
+    html: string;
+    text?: string;
+};
+/**
+ * Complete email configuration
+ */
+export interface EmailConfig {
+    /**
+     * From address for all emails (e.g., "noreply@example.com" or "MyApp <noreply@example.com>")
+     */
+    from: string;
+    /**
+     * SMTP configuration for sending emails via SMTP server
+     */
+    smtp?: SMTPConfig;
+    /**
+     * Alternative: custom function to send emails
+     * Use this for custom email providers (AWS SES SDK, Resend, etc.)
+     */
+    sendEmail?: (options: EmailSendOptions) => Promise<void>;
+    /**
+     * Base URL for password reset links (e.g., "https://myapp.com")
+     * The reset link will be: {baseUrl}/reset-password?token={token}
+     */
+    resetPasswordUrl?: string;
+    /**
+     * Base URL for email verification links (e.g., "https://myapp.com")
+     * The verification link will be: {baseUrl}/verify-email?token={token}
+     */
+    verifyEmailUrl?: string;
+    /**
+     * Application name to use in email templates
+     */
+    appName?: string;
+    /**
+     * Custom email templates (optional - defaults are provided)
+     */
+    templates?: {
+        passwordReset?: PasswordResetTemplateFunction;
+        emailVerification?: EmailVerificationTemplateFunction;
+        userInvitation?: UserInvitationTemplateFunction;
+    };
+}

package/dist/server-core/src/functions/function-loader.d.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono";
+export interface LoadedFunction {
+    /** Endpoint name derived from filename (e.g., "send-invoice") */
+    name: string;
+    /** The Hono sub-app to mount */
+    app: Hono<import("hono").Env>;
+}
+/**
+ * Auto-discover Hono route files from a directory.
+ *
+ * Each file should default-export a Hono app (or router).
+ * The filename (without extension) becomes the mount path:
+ *   `functions/send-invoice.ts` → mounted at `/send-invoice`
+ *
+ * This mirrors how `loadCollectionsFromDirectory` works for collections.
+ */
+export declare function loadFunctionsFromDirectory(directory: string): Promise<LoadedFunction[]>;

package/dist/server-core/src/functions/function-routes.d.ts

@@ -0,0 +1,10 @@
+import { Hono } from "hono";
+import { HonoEnv } from "../api/types";
+import { LoadedFunction } from "./function-loader";
+/**
+ * Mount all loaded function routes under a single Hono router.
+ *
+ * Each function is mounted at `/<function-name>`, preserving
+ * whatever HTTP methods and middleware the Hono sub-app defines.
+ */
+export declare function createFunctionRoutes(functions: LoadedFunction[]): Hono<HonoEnv>;

package/dist/server-core/src/functions/index.d.ts

@@ -0,0 +1,3 @@
+export { loadFunctionsFromDirectory } from "./function-loader";
+export type { LoadedFunction } from "./function-loader";
+export { createFunctionRoutes } from "./function-routes";

package/dist/server-core/src/history/history-routes.d.ts

@@ -0,0 +1,23 @@
+import { Hono } from "hono";
+import { HonoEnv } from "../api/types";
+import { BackendCollectionRegistry } from "../collections/BackendCollectionRegistry";
+import { DataDriver } from "@rebasepro/types";
+/**
+ * Create Hono routes for entity history.
+ * Mounted at `{basePath}/data/:slug/:entityId/history`.
+ */
+export interface HistoryService {
+    fetchHistory(tableName: string, entityId: string, options: {
+        limit: number;
+        offset: number;
+    }): Promise<{
+        data: any[];
+        total: number;
+    }>;
+    fetchHistoryEntry(historyId: string): Promise<any>;
+}
+export declare function createHistoryRoutes(params: {
+    historyService: HistoryService;
+    registry: BackendCollectionRegistry;
+    driver: DataDriver;
+}): Hono<HonoEnv>;

package/dist/server-core/src/history/index.d.ts

@@ -0,0 +1 @@
+export { createHistoryRoutes } from "./history-routes";

package/dist/server-core/src/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @rebasepro/server-core
+ *
+ * Database-Agnostic Backend Core for Rebase.
+ * This package provides the core backend services, generic driver routing,
+ * and API layers. Database implementations (e.g., PostgreSQL) are provided
+ * by specialized driver packages like `@rebasepro/server-postgresql`.
+ */
+export * from "./db/interfaces";
+export * from "./auth/interfaces";
+export * from "./init";
+export * from "./services/driver-registry";
+export * from "./api/types";
+export * from "./api";
+export * from "./types";
+export * from "./types/index";
+export * from "./auth";
+export * from "./email";
+export * from "./storage";
+export * from "./utils/logging";
+export * from "./utils/sql";
+export * from "./history";
+export * from "./functions";
+export * from "./serve-spa";

package/dist/server-core/src/init.d.ts

@@ -0,0 +1,49 @@
+import { DataDriver, EntityCollection, BackendBootstrapper, BootstrappedAuth, RealtimeProvider } from "@rebasepro/types";
+import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
+import { DriverRegistry } from "./services/driver-registry";
+import { Server } from "http";
+import { Hono } from "hono";
+import { HonoEnv } from "./api/types";
+import { BackendStorageConfig, StorageController, StorageRegistry } from "./storage";
+import { EmailConfig } from "./email";
+export interface RebaseAuthConfig {
+    jwtSecret?: string;
+    accessExpiresIn?: string;
+    refreshExpiresIn?: string;
+    requireAuth?: boolean;
+    allowRegistration?: boolean;
+    email?: EmailConfig;
+    google?: {
+        clientId: string;
+    };
+    defaultRole?: string;
+    [key: string]: unknown;
+}
+export interface RebaseBackendConfig {
+    collections?: EntityCollection[];
+    collectionsDir?: string;
+    server: Server;
+    app: Hono<HonoEnv>;
+    basePath?: string;
+    bootstrappers: BackendBootstrapper[];
+    logging?: {
+        level?: "error" | "warn" | "info" | "debug";
+    };
+    auth?: RebaseAuthConfig;
+    storage?: BackendStorageConfig | Record<string, BackendStorageConfig>;
+    history?: unknown;
+    enableSwagger?: boolean;
+    functionsDir?: string;
+}
+export interface RebaseBackendInstance {
+    driverRegistry: DriverRegistry;
+    driver: DataDriver;
+    realtimeServices: Record<string, RealtimeProvider>;
+    realtimeService: RealtimeProvider;
+    auth?: BootstrappedAuth;
+    history?: unknown;
+    storageRegistry?: StorageRegistry;
+    storageController?: StorageController;
+    collectionRegistry: BackendCollectionRegistry;
+}
+export declare function initializeRebaseBackend(config: RebaseBackendConfig): Promise<RebaseBackendInstance>;

package/dist/server-core/src/serve-spa.d.ts

@@ -0,0 +1,30 @@
+import { Hono } from "hono";
+/**
+ * Configuration for serving a Single Page Application
+ */
+export interface ServeSPAConfig {
+    /**
+     * Absolute path to the frontend build directory
+     * @example path.join(__dirname, "../../frontend/dist")
+     */
+    frontendPath: string;
+    /**
+     * Base path for API routes (default: "/api")
+     * Requests to this path will be passed through to API handlers
+     */
+    apiBasePath?: string;
+    /**
+     * Additional paths to exclude from SPA handling
+     * These paths will be passed through to other handlers
+     * @example ["/health", "/ws", "/metrics"]
+     */
+    excludePaths?: string[];
+    /**
+     * Index file to serve for SPA routes (default: "index.html")
+     */
+    indexFile?: string;
+}
+/**
+ * Serve a Single Page Application from an Hono app.
+ */
+export declare function serveSPA<E extends import("hono").Env>(app: Hono<E>, config: ServeSPAConfig): void;

package/dist/server-core/src/services/driver-registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Driver Registry
+ *
+ * Manages multiple driver delegates for Rebase backend.
+ * Allows different databases for different collections.
+ *
+ * Usage:
+ * - Single DB: Pass a single DataDriver → maps to "(default)"
+ * - Multiple DBs: Pass a map of { dbId: DataDriver }
+ * - Collections use `databaseId` property to specify which driver to use
+ * - Collections without `databaseId` fallback to "(default)"
+ */
+import { DataDriver } from "@rebasepro/types";
+/**
+ * The default driver identifier used when:
+ * - A single driver is provided (not a map)
+ * - A collection doesn't specify a databaseId
+ */
+export declare const DEFAULT_DRIVER_ID = "(default)";
+/**
+ * Registry for managing multiple driver delegates
+ */
+export interface DriverRegistry {
+    /**
+     * Register a driver delegate with an ID
+     * @param id - Unique identifier for this driver (e.g., "analytics", "users")
+     * @param delegate - The DataDriver instance
+     */
+    register(id: string, delegate: DataDriver): void;
+    /**
+     * Get the default driver delegate (id = "(default)")
+     * @throws Error if no default driver is registered
+     */
+    getDefault(): DataDriver;
+    /**
+     * Get a driver delegate by ID
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver, or undefined if not found
+     */
+    get(id: string | undefined | null): DataDriver | undefined;
+    /**
+     * Get a driver delegate by ID, with fallback to default
+     * @param id - Driver identifier, or undefined/null for default
+     * @returns The DataDriver (falls back to default if id not found)
+     * @throws Error if neither the specified nor default driver exists
+     */
+    getOrDefault(id: string | undefined | null): DataDriver;
+    /**
+     * Check if a driver with the given ID exists
+     */
+    has(id: string): boolean;
+    /**
+     * List all registered driver IDs
+     */
+    list(): string[];
+    /**
+     * Get the number of registered drivers
+     */
+    size(): number;
+}
+/**
+ * Default implementation of DriverRegistry
+ */
+export declare class DefaultDriverRegistry implements DriverRegistry {
+    private delegates;
+    /**
+     * Create a DriverRegistry from either a single delegate or a map
+     * @param input - Single DataDriver (maps to "(default)") or Record<string, DataDriver>
+     */
+    static create(input: DataDriver | Record<string, DataDriver>): DefaultDriverRegistry;
+    register(id: string, delegate: DataDriver): void;
+    getDefault(): DataDriver;
+    get(id: string | undefined | null): DataDriver | undefined;
+    getOrDefault(id: string | undefined | null): DataDriver;
+    has(id: string): boolean;
+    list(): string[];
+    size(): number;
+}

package/dist/server-core/src/storage/LocalStorageController.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Local filesystem storage controller
+ */
+import { StorageController, LocalStorageConfig } from './types';
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from '@rebasepro/types';
+/**
+ * Local filesystem storage implementation
+ * Stores files in a directory structure: {basePath}/{bucket}/{path}
+ */
+export declare class LocalStorageController implements StorageController {
+    private config;
+    private basePath;
+    constructor(config: LocalStorageConfig);
+    getType(): 'local';
+    /**
+     * Ensure directory exists, creating it if necessary
+     */
+    private ensureDir;
+    /**
+     * Get the full filesystem path for a storage path.
+     * Includes a path traversal guard to prevent escaping the base directory.
+     */
+    private getFullPath;
+    /**
+     * Validate file before upload
+     */
+    private validateFile;
+    uploadFile({ file, fileName, path: storagePath, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    getDownloadURL(storagePath: string, bucket?: string): Promise<DownloadConfig>;
+    getFile(storagePath: string, bucket?: string): Promise<File | null>;
+    deleteFile(storagePath: string, bucket?: string): Promise<void>;
+    list(storagePath: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<StorageListResult>;
+    /**
+     * Get the absolute filesystem path for serving files
+     * Used by the storage routes to serve files directly
+     */
+    getAbsolutePath(storagePath: string, bucket?: string): string;
+    /**
+     * Get the base path for the storage
+     */
+    getBasePath(): string;
+}