@rebasepro/server-core 0.7.0 → 0.8.0

package/src/auth/interfaces.ts

@@ -74,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>;
 }
 
 /**

package/src/auth/middleware.ts

@@ -37,7 +37,7 @@ export interface AuthMiddlewareOptions {
      * to Postgres Row-Level Security policies.
      */
     requireAuth?: boolean;
-    /** Optional custom validator (for non-JWT auth, e.g. Firebase Auth) */
+    /** Optional custom validator (for non-JWT auth, e.g. external auth providers) */
     validator?: (c: Context<HonoEnv>) => Promise<AuthResult>;
     /**
      * A static secret key for server-to-server / script authentication.
@@ -47,7 +47,7 @@ export interface AuthMiddlewareOptions {
      * roles: `["admin"]`) **without** JWT verification. The driver is scoped
      * via `withAuth()` with the service identity.
      *
-     * This is the Rebase equivalent of a Firebase Service Account key.
+     * This is the Rebase equivalent of a Service Account key.
      * Set via `REBASE_SERVICE_KEY` in `.env` and pass through the backend config.
      *
      * **Security:** The comparison uses constant-time equality to prevent
@@ -245,7 +245,7 @@ export function createAuthMiddleware(options: AuthMiddlewareOptions): Middleware
         // Pick the per-request delegate (multi-data-source) before scoping.
         const driver = resolveDriver ? resolveDriver(c) : baseDriver;
         if (validator) {
-            // Custom validator path (e.g., Firebase Auth, API keys)
+            // Custom validator path (e.g., API keys, external auth)
             try {
                 const authResult = await validator(c);
                 if (authResult && typeof authResult === "object") {
@@ -291,7 +291,7 @@ code: "UNAUTHORIZED" } }, 401);
 
                 // ── Service Key check ──────────────────────────────────
                 // Check BEFORE JWT verification. Service keys are static
-                // secrets (like Firebase SA keys) that grant admin access
+                // secrets (like Service Account keys) that grant admin access
                 // for scripts, cron jobs, and server-to-server calls.
                 if (serviceKey && safeCompare(token, serviceKey)) {
                     const serviceUser: AccessTokenPayload = {

package/src/auth/routes.ts

@@ -30,8 +30,7 @@ export interface AuthModuleConfig {
     /** Default role ID to assign to new users (default: none). Must NOT be "admin". */
     defaultRole?: string;
     /** Optional array of OAuth providers */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    oauthProviders?: OAuthProvider<any>[];
+    oauthProviders?: OAuthProvider<unknown>[];
     /** When true, blocks all self-registration regardless of `allowRegistration`. */
     disableSelfRegistration?: boolean;
     /**

package/src/functions/define-function.ts

@@ -0,0 +1,59 @@
+import { Hono } from "hono";
+import type { RebaseClient } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types";
+import { rebase } from "../singleton";
+
+/**
+ * Typed context injected into a function authored with {@link defineFunction}.
+ *
+ * Surfaces the app-scoped Rebase singleton so handlers don't need to reach
+ * for the global `rebase` import. Request-scoped values (the authenticated
+ * `user`, the RLS-scoped `driver`, the `apiKey`, the `requestId`) are typed
+ * on the Hono context via {@link HonoEnv} — read them with `c.get("user")`
+ * / `c.var.driver` inside a handler.
+ */
+export interface RebaseFunctionContext {
+    /**
+     * The server-side Rebase singleton (`data`, `auth`, `storage`, `email`,
+     * `sql`). `rebase.data` runs with **admin privileges** (no RLS) — use the
+     * request `driver` (`c.var.driver`) for user-scoped queries.
+     */
+    rebase: RebaseClient;
+}
+
+/**
+ * Typed authoring contract for a custom backend function.
+ *
+ * A custom function is a file in the `functionsDir` that default-exports a
+ * Hono app; the loader mounts it at `/<filename>`. `defineFunction` is the
+ * typed opt-in for that contract: it hands you a pre-typed `Hono<HonoEnv>`
+ * app (so `c.var.user` / `c.var.driver` are typed) plus a
+ * {@link RebaseFunctionContext}, and returns exactly the Hono app the loader
+ * already accepts — so it is fully interchangeable with a plain
+ * `export default new Hono()`.
+ *
+ * @example
+ * ```ts
+ * import { defineFunction, requireAuth } from "@rebasepro/server-core";
+ *
+ * export default defineFunction((app, { rebase }) => {
+ *     app.use("/*", requireAuth);
+ *     app.get("/home", async (c) => {
+ *         const [stats] = await rebase.sql!(`SELECT count(*) AS n FROM orders`);
+ *         return c.json({ orders: Number(stats.n) });
+ *     });
+ * });
+ * ```
+ *
+ * @param definition Receives the function's Hono app and the typed context.
+ *   Register routes on the provided `app` and return nothing, or return your
+ *   own `Hono<HonoEnv>` app to use instead.
+ * @returns The Hono app to default-export from the function file.
+ */
+export function defineFunction(
+    definition: (app: Hono<HonoEnv>, ctx: RebaseFunctionContext) => void | Hono<HonoEnv>
+): Hono<HonoEnv> {
+    const app = new Hono<HonoEnv>();
+    const returned = definition(app, { rebase });
+    return returned instanceof Hono ? returned : app;
+}

package/src/functions/function-loader.ts

@@ -24,6 +24,10 @@ export async function loadFunctionsFromDirectory(
     directory: string
 ): Promise<LoadedFunction[]> {
     const functions: LoadedFunction[] = [];
+    // Aggregate problem files so a broken function surfaces as one loud
+    // summary line, not just a warning buried per-file. We still don't throw:
+    // a single malformed function must not crash server boot.
+    const problems: string[] = [];
 
     if (!fs.existsSync(directory)) {
         return functions;
@@ -51,6 +55,7 @@ export async function loadFunctionsFromDirectory(
 
                 if (!exported) {
                     logger.warn(`[functions] ${file}: no default export. Skipping.`);
+                    problems.push(`${file} (no default export)`);
                     continue;
                 }
 
@@ -86,16 +91,27 @@ app: result as Hono });
                     `  export type: ${exportType}${exported?.constructor?.name ? ` (${exported.constructor.name})` : ""}\n` +
                     `  prototype methods: ${keys}\n` +
                     "  Hint: ensure the function exports a Hono app created with the same hono version as the server.\n" +
+                    "  Author with `defineFunction(...)` from @rebasepro/server-core for a typed, checked contract.\n" +
                     "  The loader checks for .fetch() and .routes — any Hono-compatible app will work."
                 );
+                problems.push(`${file} (not a Hono app or factory)`);
             } catch (err: unknown) {
                 const message =
                     err instanceof Error ? err.message : String(err);
                 logger.error(`[functions] Failed to load ${file}: ${message}`);
+                problems.push(`${file} (threw: ${message})`);
             }
         }
     }
 
+    if (problems.length > 0) {
+        logger.warn(
+            `[functions] ${problems.length} function file(s) were skipped and will NOT be served:\n` +
+            problems.map((p) => `  - ${p}`).join("\n") + "\n" +
+            "  Fix these or author them with `defineFunction(...)` for a typed, compile-checked contract."
+        );
+    }
+
     return functions;
 }
 

package/src/functions/index.ts

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

package/src/index.ts

@@ -8,63 +8,96 @@
  */
 
 // =============================================================================
-// Abstract Interfaces (for database abstraction)
+// Core Initialization
 // =============================================================================
-export * from "./db/interfaces";
-export * from "./auth/interfaces";
-
-// Core functionality
-export * from "./init";
+export {
+    initializeRebaseBackend,
+    isAuthAdapter,
+    isDatabaseAdapter
+} from "./init";
+export type {
+    RebaseBackendConfig,
+    RebaseBackendInstance,
+    RebaseAuthConfig
+} from "./init";
 
+// =============================================================================
 // Server-side singleton (import { rebase } from "@rebasepro/server-core")
+// =============================================================================
 export { rebase, _setRebaseMock, _resetRebaseMock } from "./singleton";
 
-// Services
-export * from "./services/driver-registry";
+// =============================================================================
+// DB Abstractions (for database driver implementations)
+// =============================================================================
+export * from "./db/interfaces";
 
-// API types (HonoEnv, ApiConfig, etc.)
-export * from "./api/types";
+// =============================================================================
+// Auth
+// =============================================================================
+export * from "./auth";
 
-// API Generation
+// =============================================================================
+// API Layer
+// =============================================================================
 export * from "./api";
 
-// Types
-export * from "./types";
-export * from "./types/index";
-
-// Auth module
-export * from "./auth";
-
-// Email module
+// =============================================================================
+// Email
+// =============================================================================
 export * from "./email";
 
-// Storage module
+// =============================================================================
+// Storage
+// =============================================================================
 export * from "./storage";
 
-export * from "./utils/logging";
-export * from "./utils/logger";
-export * from "./utils/request-logger";
-export * from "./utils/request-id";
-export * from "./utils/sql";
-
-// Entity history
-export * from "./history";
+// =============================================================================
+// Entity History
+// =============================================================================
+export { createHistoryRoutes } from "./history";
 
+// =============================================================================
 // Custom Functions (auto-discovered Hono routes)
-export * from "./functions";
+// =============================================================================
+export { loadFunctionsFromDirectory, createFunctionRoutes, defineFunction } from "./functions";
+export type { LoadedFunction, RebaseFunctionContext } from "./functions";
 
+// =============================================================================
 // Cron Jobs (auto-discovered scheduled tasks)
-export * from "./cron";
-
+// =============================================================================
+export { loadCronJobsFromDirectory, CronScheduler, validateCronExpression, createCronRoutes, createCronStore } from "./cron";
+export type { LoadedCronJob, CronStore } from "./cron";
 
-// SPA serving helper
-export * from "./serve-spa";
+// =============================================================================
+// SQL Helpers (for RLS policies)
+// =============================================================================
+export { authUid, authRoles, authJwt } from "./utils/sql";
 
-// Dev-mode port resolution (retry on EADDRINUSE)
-export * from "./utils/dev-port";
+// =============================================================================
+// Logger
+// =============================================================================
+export { logger } from "./utils/logger";
+export type { Logger } from "./utils/logger";
 
-// Environment validation
+// =============================================================================
+// Environment Validation
+// =============================================================================
 export { loadEnv } from "./env";
 export type { RebaseEnv } from "./env";
-export { z } from "zod";
 
+// =============================================================================
+// Server-core specific types (subscription types)
+// =============================================================================
+export * from "./types";
+
+// =============================================================================
+// Driver Registry
+// =============================================================================
+export * from "./services/driver-registry";
+
+// =============================================================================
+// Internal plumbing exported for the official app/backend
+// =============================================================================
+export { cleanupDevPortFile, listenWithPortRetry } from "./utils/dev-port";
+export { serveSPA } from "./serve-spa";
+export { z } from "zod";

package/src/init.ts

@@ -1,11 +1,11 @@
 import {
     AuthAdapter,
     BackendBootstrapper,
-    BackendHooks,
     BootstrappedAuth,
     DatabaseAdapter,
     DataDriver,
     DataSourceDefinition,
+    EntityCallbacks,
     EntityCollection,
     HealthCheckResult,
     InitializedDriver,
@@ -83,7 +83,7 @@ export interface RebaseAuthConfig {
      *
      * When a request includes `Authorization: Bearer <serviceKey>`, it is
      * granted admin-level access without JWT verification. This is the
-     * Rebase equivalent of a Firebase Service Account key.
+     * Rebase equivalent of a Service Account key.
      *
      * Generate with: `node -e "logger.info(require('crypto').randomBytes(48).toString('base64'))"`
      *
@@ -92,6 +92,14 @@ export interface RebaseAuthConfig {
      */
     serviceKey?: string;
     email?: EmailConfig;
+    // ── Convenience shortcuts ─────────────────────────────────────────
+    // Each named field below is syntactic sugar that internally resolves
+    // to an `OAuthProvider` via the corresponding `create*Provider`
+    // factory at startup. They are equivalent to constructing the
+    // provider manually and passing it in the `providers` array.
+    //
+    // For providers not listed here, or for full control over the
+    // provider configuration, use the `providers` array directly.
     google?: { clientId: string; clientSecret?: string };
     linkedin?: { clientId: string; clientSecret: string };
     github?: { clientId: string; clientSecret: string };
@@ -105,8 +113,31 @@ export interface RebaseAuthConfig {
     slack?: { clientId: string; clientSecret: string };
     spotify?: { clientId: string; clientSecret: string };
     defaultRole?: string;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    providers?: OAuthProvider<any>[];
+    /**
+     * Canonical array of OAuth providers.
+     *
+     * This is the primary extension point for **all** OAuth integrations.
+     * Each entry is an `OAuthProvider<unknown>` constructed via one of
+     * the `create*Provider` factories exported from `@rebasepro/server-core`
+     * (e.g. `createGoogleProvider`, `createGitHubProvider`).
+     *
+     * The named convenience fields above (`google`, `github`, etc.) are
+     * automatically resolved into this array at startup. You can mix both
+     * approaches; named fields and explicit entries are merged (named
+     * fields are appended after explicit entries).
+     *
+     * @example
+     * ```ts
+     * import { createGoogleProvider } from "@rebasepro/server-core";
+     *
+     * auth: {
+     *   providers: [
+     *     createGoogleProvider({ clientId: "…", clientSecret: "…" }),
+     *   ],
+     * }
+     * ```
+     */
+    providers?: OAuthProvider<unknown>[];
     /**
      * Override specific parts of the built-in auth implementation.
      *
@@ -131,8 +162,6 @@ export interface RebaseAuthConfig {
      * Requires email to be configured.
      */
     magicLink?: boolean;
-
-    [key: string]: unknown;
 }
 
 export interface RebaseBackendConfig {
@@ -188,11 +217,22 @@ export interface RebaseBackendConfig {
     /**
      * Storage configuration. Accepts:
      *
-     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3', ... }`)
-     * - A `StorageController` instance (for custom providers like GCS, Azure, etc.)
+     * - A `BackendStorageConfig` object (`{ type: 'local' | 's3' | 'gcs', ... }`)
+     * - A `StorageController` instance (for custom providers like Azure, etc.)
      * - A `Record<string, ...>` of either, for multi-backend setups
      */
     storage?: BackendStorageConfig | StorageController | Record<string, BackendStorageConfig | StorageController>;
+
+    /**
+     * Declared storage sources. Drives the client-side StorageSourceRegistry
+     * and the transport distinction (server vs direct).
+     *
+     * Server-backed sources are auto-derived from the `storage` map — you
+     * only need explicit entries for "direct" transport sources (e.g.
+     * external storage) that the backend does not proxy.
+     */
+    storageSources?: import("@rebasepro/types").StorageSourceDefinition[];
+
     history?: unknown;
     /**
      * Default security rules applied to any collection that does not define
@@ -242,14 +282,24 @@ export interface RebaseBackendConfig {
         origin: string | string[] | ((origin: string) => boolean);
     };
     /**
-     * Backend-level hooks for intercepting collection entity data
-     * at the REST API boundary. These run server-side after database
-     * operations and before API responses are sent.
+     * Global lifecycle callbacks applied to every collection.
      *
-     * Complement the per-collection `EntityCallbacks` system which
-     * handles collection CRUD operations.
+     * Same type as per-collection `callbacks` — fires on **every** data path
+     * (REST API, WebSocket / realtime, server-side `rebase.data`).
+     *
+     * Execution order: global callbacks → collection callbacks → property callbacks.
+     *
+     * @example
+     * ```ts
+     * callbacks: {
+     *     afterRead({ entity, collection }) {
+     *         console.log(`Read ${collection.slug}/${entity.id}`);
+     *         return entity;
+     *     }
+     * }
+     * ```
      */
-    hooks?: BackendHooks;
+    callbacks?: EntityCallbacks;
 }
 
 /**
@@ -337,6 +387,11 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     // so normalization can resolve each collection's engine.
     const dataSourceRegistry = createDataSourceRegistry(config.dataSources);
     collectionRegistry.setDataSources(dataSourceRegistry);
+
+    // Global lifecycle callbacks — applied to every collection, on all data paths.
+    if (config.callbacks) {
+        collectionRegistry.setGlobalCallbacks(config.callbacks);
+    }
     let activeCollections = config.collections || [];
     if (config.collectionsDir && activeCollections.length === 0) {
         activeCollections = await loadCollectionsFromDirectory(config.collectionsDir);
@@ -607,8 +662,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
         if (!isAuthAdapter(config.auth)) {
             const safeAuthConfig = config.auth as RebaseAuthConfig;
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const oauthProviders: OAuthProvider<any>[] = [...(safeAuthConfig.providers || [])];
+            const oauthProviders: OAuthProvider<unknown>[] = [...(safeAuthConfig.providers || [])];
 
             // Resolve configured OAuth providers via data-driven registration.
             // Each entry maps a config key to its factory function name and required fields.
@@ -723,7 +777,10 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
         const storageRoutes = createStorageRoutes({
             controller: storageController,
-            requireAuth: resolveRequireAuth(config.auth)
+            registry: storageRegistry,
+            sources: config.storageSources,
+            requireAuth: resolveRequireAuth(config.auth),
+            authAdapter
         });
 
         // Apply a permissive body limit specifically for the upload endpoint
@@ -825,7 +882,6 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         const restGenerator = new RestApiGenerator(
             serverCollections,
             defaultDriver,
-            config.hooks?.data,
             authAdapter
         );
         dataRouter.route("/", restGenerator.generateRoutes());
@@ -913,9 +969,10 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
             const functionsRouter = new Hono<HonoEnv>();
             functionsRouter.onError(errorHandler);
 
-            // Custom functions follow the same auth policy as data routes.
-            // Per-route auth can be further refined inside individual functions.
-            const functionsRequireAuth = resolveRequireAuth(config.auth);
+            // Custom functions do NOT require authentication at the global level by default.
+            // This allows custom functions to define public endpoints (like webhooks).
+            // Per-route auth can be further refined inside individual functions using `requireAuth`.
+            const functionsRequireAuth = false;
 
             // Use adapter middleware when available, fallback to built-in
             if (authAdapter) {