@rebasepro/server-core 0.7.0 → 0.8.0

package/src/storage/routes.ts

@@ -1,13 +1,20 @@
 /**
  * Storage REST API routes using Hono
+ *
+ * Supports multi-backend routing via `StorageRegistry`. Each endpoint
+ * accepts an optional `storageId` parameter (query string or form field)
+ * to target a named storage backend. When omitted, the default backend
+ * is used.
  */
 
-import { Hono } from "hono";
+import { Hono, type MiddlewareHandler } from "hono";
 import fs from "node:fs";
 import fsp from "node:fs/promises";
 import { StorageController } from "./types";
 import { LocalStorageController } from "./LocalStorageController";
-import { requireAuth as jwtRequireAuth, optionalAuth } from "../auth/middleware";
+import type { StorageRegistry } from "./storage-registry";
+import { DEFAULT_STORAGE_SOURCE_KEY, type StorageSourceDefinition, type AuthAdapter } from "@rebasepro/types";
+import { requireAuth as jwtRequireAuth, optionalAuth as jwtOptionalAuth } from "../auth/middleware";
 import { ApiError, errorHandler } from "../api/errors";
 import { HonoEnv } from "../api/types";
 import { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform";
@@ -17,7 +24,25 @@ import { TusHandler } from "./tus-handler";
 const transformCache = new TransformCache();
 
 export interface StorageRoutesConfig {
-    controller: StorageController;
+    /**
+     * Single storage controller (backward-compatible).
+     * Used as fallback when no `registry` is provided.
+     */
+    controller?: StorageController;
+    /**
+     * Full storage registry for multi-backend routing.
+     * When provided, endpoints resolve the controller from `storageId`
+     * parameter. Takes precedence over `controller`.
+     */
+    registry?: StorageRegistry;
+    /**
+     * Declared storage sources, surfaced by `GET /sources` so the client can
+     * bootstrap its registry. Carries the frontend `transport` (server vs
+     * direct) and human-readable labels. Server-transport sources are also
+     * derived from the registry; `direct` sources (e.g. Firebase Storage) only
+     * exist here since the backend does not proxy them.
+     */
+    sources?: StorageSourceDefinition[];
     /** Base path for storage routes (default: '/api/storage') */
     basePath?: string;
     /** Require authentication for write operations (default: true) */
@@ -25,6 +50,13 @@ export interface StorageRoutesConfig {
     /** Allow unauthenticated read access to stored files (default: false).
      *  When false and requireAuth is true, reads also require authentication. */
     publicRead?: boolean;
+    /**
+     * When provided, storage routes delegate auth to this adapter instead
+     * of the built-in JWT module. This mirrors how data routes use
+     * `createAdapterAuthMiddleware()` and avoids the "JWT secret not
+     * configured" crash when `configureJwt()` was never called.
+     */
+    authAdapter?: AuthAdapter;
 }
 
 /**
@@ -66,19 +98,98 @@ function sanitizeStorageKey(key: string): string {
     return sanitized;
 }
 
+/**
+ * Build adapter-aware auth middleware for storage routes.
+ *
+ * When an `AuthAdapter` is provided, token verification is delegated to the
+ * adapter instead of the built-in JWT module. This mirrors how data routes
+ * use `createAdapterAuthMiddleware()`, but without RLS driver scoping (storage
+ * routes don't interact with the DataDriver).
+ *
+ * Returns both a "write" middleware (enforces auth when `requireAuth` is true)
+ * and a "read" middleware (enforces auth unless `publicRead` is set).
+ */
+function buildAdapterAuthMiddleware(
+    adapter: AuthAdapter,
+    requireAuth: boolean,
+    publicRead: boolean
+): { writeAuthMiddleware: MiddlewareHandler<HonoEnv>; readAuthMiddleware: MiddlewareHandler<HonoEnv> } {
+    /**
+     * Core middleware: verifies the request via the adapter. When `enforce`
+     * is true, returns 401 if no authenticated user is resolved.
+     */
+    const createMiddleware = (enforce: boolean): MiddlewareHandler<HonoEnv> => {
+        return async (c, next) => {
+            let authenticatedUser = null;
+            try {
+                authenticatedUser = await adapter.verifyRequest(c.req.raw);
+            } catch {
+                return c.json({ error: { message: "Unauthorized", code: "UNAUTHORIZED" } }, 401);
+            }
+
+            if (authenticatedUser) {
+                c.set("user", {
+                    userId: authenticatedUser.uid,
+                    email: authenticatedUser.email,
+                    roles: authenticatedUser.roles
+                });
+            }
+
+            if (enforce && !authenticatedUser) {
+                return c.json({ error: { message: "Unauthorized: Authentication required", code: "UNAUTHORIZED" } }, 401);
+            }
+
+            return next();
+        };
+    };
+
+    return {
+        writeAuthMiddleware: createMiddleware(requireAuth),
+        readAuthMiddleware: createMiddleware(!publicRead && requireAuth)
+    };
+}
+
 /**
  * Create storage REST API routes
  */
 export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv> {
     const router = new Hono<HonoEnv>();
     router.onError(errorHandler);
-    const { controller, requireAuth = true, publicRead = false } = config;
+    const { controller, registry, sources: declaredSources, requireAuth = true, publicRead = false, authAdapter } = config;
 
-    // Use actual JWT auth middleware from auth module
-    const writeAuthMiddleware = requireAuth ? jwtRequireAuth : optionalAuth;
+    /**
+     * Resolve the storage controller for a request.
+     * Looks up by `storageId` in the registry, falls back to the single
+     * controller, and finally to the registry default.
+     */
+    const resolveController = (storageId?: string | null): StorageController => {
+        if (registry) {
+            return registry.getOrDefault(storageId);
+        }
+        if (controller) {
+            return controller;
+        }
+        throw new Error("No storage controller or registry available");
+    };
+
+    /** Get the default controller (used for TUS and base-path derivation). */
+    const getDefaultController = (): StorageController => {
+        if (registry) return registry.getDefault();
+        if (controller) return controller;
+        throw new Error("No storage controller or registry available");
+    };
 
-    // For read operations: respect publicRead config.
-    const readAuthMiddleware = (publicRead || !requireAuth) ? optionalAuth : jwtRequireAuth;
+    // ── Auth middleware selection ────────────────────────────────────────
+    // When an AuthAdapter is available, delegate token verification to it
+    // (mirroring the data-routes pattern). This avoids calling the JWT
+    // module which may not have been configured (e.g. custom auth).
+    // When no adapter is present, fall back to the built-in JWT middleware.
+    const { writeAuthMiddleware, readAuthMiddleware } = authAdapter
+        ? buildAdapterAuthMiddleware(authAdapter, requireAuth, publicRead)
+        : {
+            writeAuthMiddleware: requireAuth ? jwtRequireAuth : jwtOptionalAuth,
+            readAuthMiddleware: (publicRead || !requireAuth) ? jwtOptionalAuth : jwtRequireAuth
+        };
 
     /**
      * Parse bucket and path from a combined file path.
@@ -116,6 +227,7 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
 
         const key = typeof body["key"] === "string" ? body["key"] : "";
         const bucket = typeof body["bucket"] === "string" ? body["bucket"] : undefined;
+        const storageId = typeof body["storageId"] === "string" ? body["storageId"] : c.req.query("storageId");
 
         const finalKey = sanitizeStorageKey(key || uploadedFile.name || "unnamed");
 
@@ -127,7 +239,8 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
             }
         }
 
-        const result = await controller.putObject({
+        const resolved = resolveController(storageId);
+        const result = await resolved.putObject({
             file: uploadedFile,
             key: finalKey,
             metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
@@ -155,13 +268,15 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
         }
 
         const filePath = decodeURIComponent(rawPath);
+        const storageId = c.req.query("storageId");
+        const resolved = resolveController(storageId);
 
         // Parse image transform query params (e.g. ?width=300&format=webp)
         const transformOpts = parseTransformOptions(c.req.query() as Record<string, string>);
 
         // For local storage, serve the file directly from disk
-        if (controller.getType() === "local") {
-            const localController = controller as LocalStorageController;
+        if (resolved.getType() === "local") {
+            const localController = resolved as LocalStorageController;
             const { bucket, resolvedPath } = parseBucketAndPath(filePath);
 
             const absolutePath = localController.getAbsolutePath(resolvedPath, bucket);
@@ -208,7 +323,7 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
         //  1. Mixed-content (HTTPS page → HTTP MinIO) is blocked by browsers
         //  2. Internal IPs / VPC endpoints are unreachable from the browser
         const { bucket: parsedBucket, resolvedPath: parsedPath } = parseBucketAndPath(filePath);
-        const fileObject = await controller.getObject(parsedPath, parsedBucket);
+        const fileObject = await resolved.getObject(parsedPath, parsedBucket);
         if (!fileObject) {
             throw ApiError.notFound("File not found");
         }
@@ -249,9 +364,11 @@ export function createStorageRoutes(config: StorageRoutesConfig): Hono<HonoEnv>
         }
 
         const filePath = decodeURIComponent(rawPath);
+        const storageId = c.req.query("storageId");
+        const resolved = resolveController(storageId);
         const { bucket, resolvedPath } = parseBucketAndPath(filePath);
 
-        const downloadConfig = await controller.getSignedUrl(resolvedPath, bucket);
+        const downloadConfig = await resolved.getSignedUrl(resolvedPath, bucket);
 
         if (downloadConfig.fileNotFound) {
             throw ApiError.notFound("File not found");
@@ -274,9 +391,11 @@ message: "No file to delete" });
         }
 
         const filePath = decodeURIComponent(rawPath);
+        const storageId = c.req.query("storageId");
+        const resolved = resolveController(storageId);
         const { bucket, resolvedPath } = parseBucketAndPath(filePath);
 
-        await controller.deleteObject(resolvedPath, bucket);
+        await resolved.deleteObject(resolvedPath, bucket);
 
         return c.json({
             success: true,
@@ -293,11 +412,13 @@ message: "No file to delete" });
         const bucket = c.req.query("bucket");
         const maxResults = c.req.query("maxResults");
         const pageToken = c.req.query("pageToken");
+        const storageId = c.req.query("storageId");
+        const resolved = resolveController(storageId);
 
-        const result = await controller.listObjects(
+        const result = await resolved.listObjects(
             storagePrefix,
             {
-                bucket: bucket ?? (controller.getType() === "local" ? "default" : undefined),
+                bucket: bucket ?? (resolved.getType() === "local" ? "default" : undefined),
                 maxResults: maxResults ? parseInt(maxResults, 10) : undefined,
                 pageToken
             }
@@ -316,27 +437,29 @@ message: "No file to delete" });
     router.post("/folder", writeAuthMiddleware, async (c) => {
         const body = await c.req.json();
         const folderPath = body.path;
+        const storageId = typeof body.storageId === "string" ? body.storageId : c.req.query("storageId");
 
         if (!folderPath || typeof folderPath !== "string") {
             throw ApiError.badRequest("Folder path is required");
         }
 
+        const resolved = resolveController(storageId);
         const { bucket, resolvedPath } = parseBucketAndPath(folderPath);
 
         if (!resolvedPath || resolvedPath.trim() === "") {
             throw ApiError.badRequest("Invalid folder path");
         }
 
-        if (controller.getType() === "local") {
+        if (resolved.getType() === "local") {
             // For local storage, create the directory
-            const localController = controller as LocalStorageController;
+            const localController = resolved as LocalStorageController;
             const absolutePath = localController.getAbsolutePath(resolvedPath, bucket);
             fs.mkdirSync(absolutePath, { recursive: true });
         } else {
-            // For S3-compatible storage, create a zero-byte marker object with trailing slash
+            // For S3/GCS-compatible storage, create a zero-byte marker object with trailing slash
             const key = resolvedPath.endsWith("/") ? resolvedPath : resolvedPath + "/";
             const emptyFile = new File([], key, { type: "application/x-directory" });
-            await controller.putObject({
+            await resolved.putObject({
                 file: emptyFile,
                 key
             });
@@ -352,10 +475,11 @@ message: "No file to delete" });
     // TUS Resumable Uploads
     // -----------------------------------------------------------------------
 
-    const tusBaseDir = controller.getType() === "local"
-        ? (controller as LocalStorageController).getBasePath()
+    const defaultCtrl = getDefaultController();
+    const tusBaseDir = defaultCtrl.getType() === "local"
+        ? (defaultCtrl as LocalStorageController).getBasePath()
         : (process.env.STORAGE_PATH || "./uploads");
-    const tusHandler = new TusHandler(tusBaseDir, controller);
+    const tusHandler = new TusHandler(tusBaseDir, defaultCtrl, registry);
     tusHandler.startCleanup();
 
     router.options("/tus", (_c) => tusHandler.options());
@@ -364,5 +488,49 @@ message: "No file to delete" });
     router.patch("/tus/:id", writeAuthMiddleware, async (c) => tusHandler.patch(c, c.req.param("id")));
     router.delete("/tus/:id", writeAuthMiddleware, async (c) => tusHandler.delete(c, c.req.param("id")));
 
+    // -----------------------------------------------------------------------
+    // Storage Sources Discovery
+    // -----------------------------------------------------------------------
+
+    /**
+     * GET /sources — list all registered storage backends.
+     * The client can bootstrap its StorageSourceRegistry from this endpoint.
+     */
+    router.get("/sources", (c) => {
+        const byKey = new Map<string, { key: string; engine: string; transport: "server" | "direct"; label?: string }>();
+
+        // 1. Server-backed sources derived from the registry (source of truth
+        //    for the actual engine type), or the single controller.
+        if (registry) {
+            for (const key of registry.list()) {
+                byKey.set(key, {
+                    key,
+                    engine: registry.get(key)?.getType() ?? "unknown",
+                    transport: "server",
+                });
+            }
+        } else {
+            byKey.set(DEFAULT_STORAGE_SOURCE_KEY, {
+                key: DEFAULT_STORAGE_SOURCE_KEY,
+                engine: defaultCtrl.getType(),
+                transport: "server",
+            });
+        }
+
+        // 2. Overlay declared definitions: adds `direct` sources the backend
+        //    does not proxy, plus labels and explicit transport/engine.
+        for (const def of declaredSources ?? []) {
+            const existing = byKey.get(def.key);
+            byKey.set(def.key, {
+                key: def.key,
+                engine: def.engine ?? existing?.engine ?? "unknown",
+                transport: def.transport ?? existing?.transport ?? "server",
+                label: def.label ?? existing?.label,
+            });
+        }
+
+        return c.json({ success: true, data: Array.from(byKey.values()) });
+    });
+
     return router;
 }

package/src/storage/tus-handler.ts

@@ -14,6 +14,7 @@ import { existsSync } from "fs";
 import { join } from "path";
 import type { Context } from "hono";
 import type { StorageController } from "./types";
+import type { StorageRegistry } from "./storage-registry";
 import { logger } from "../utils/logger.js";
 
 /** Metadata for an in-progress resumable upload. */
@@ -57,7 +58,8 @@ export class TusHandler {
 
     constructor(
         storageBaseDir: string,
-        private storageController?: StorageController
+        private storageController?: StorageController,
+        private storageRegistry?: StorageRegistry
     ) {
         this.tusDir = join(storageBaseDir, ".tus-uploads");
     }
@@ -283,7 +285,17 @@ export class TusHandler {
     private async finalize(upload: TusUpload): Promise<void> {
         upload.completed = true;
 
-        if (!this.storageController) {
+        // Resolve the target controller: prefer storageId from TUS metadata,
+        // then fall back to the registry default, then the single controller.
+        const storageId = upload.metadata.storageId;
+        let targetController = this.storageController;
+        if (this.storageRegistry) {
+            targetController = storageId
+                ? this.storageRegistry.getOrDefault(storageId)
+                : this.storageRegistry.getDefault();
+        }
+
+        if (!targetController) {
             // No controller — leave temp file in place
             logger.warn("[TUS] Upload completed but no StorageController configured. Temp file remains:", { filePath: upload.filePath });
             return;
@@ -297,7 +309,7 @@ export class TusHandler {
 
             const file = new File([data], fileName, { type: mimeType });
 
-            await this.storageController.putObject({
+            await targetController.putObject({
                 file,
                 key: fileName,
                 bucket: upload.bucket
@@ -307,7 +319,7 @@ export class TusHandler {
             try { await unlink(upload.filePath); } catch { /* ok */ }
             this.uploads.delete(upload.id);
 
-            logger.info(`[TUS] Upload ${upload.id} finalized → ${fileName}`);
+            logger.info(`[TUS] Upload ${upload.id} finalized → ${fileName}`, storageId ? { storageId } : {});
         } catch (err) {
             logger.error(`[TUS] Failed to finalize upload ${upload.id}`, { error: err });
         }

package/src/storage/types.ts

@@ -45,18 +45,40 @@ export interface S3StorageConfig {
 }
 
 /**
- * Storage configuration — local filesystem or S3-compatible.
+ * Google Cloud Storage configuration (works with GCS and Firebase Storage)
+ */
+export interface GCSStorageConfig {
+    type: "gcs";
+    /** GCS bucket name (e.g. "my-project.appspot.com" for Firebase Storage) */
+    bucket: string;
+    /** GCP project ID (optional, auto-detected from credentials) */
+    projectId?: string;
+    /** Path to service account JSON key file */
+    keyFilename?: string;
+    /** Service account credentials object (alternative to keyFilename) */
+    credentials?: { client_email: string; private_key: string; project_id?: string };
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Allowed MIME types */
+    allowedMimeTypes?: string[];
+    /** Signed URL expiration in seconds (default: 3600) */
+    signedUrlExpiration?: number;
+}
+
+/**
+ * Storage configuration — local filesystem, S3-compatible, or Google Cloud Storage.
  *
  * **Built-in providers:**
  * - `local` — Zero-config filesystem storage. Great for dev and single-server deployments (Hetzner, bare metal).
  * - `s3` — Any S3-compatible provider. AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,
  *           Backblaze B2, DigitalOcean Spaces, and even GCS (via its S3-compatible interoperability API).
+ * - `gcs` — Native Google Cloud Storage / Firebase Storage via `@google-cloud/storage`.
  *
  * **Custom providers:**
- * For cloud-native storage (GCS, Azure Blob, etc.), implement the `StorageController`
+ * For other cloud storage (Azure Blob, etc.), implement the `StorageController`
  * interface and pass the instance directly to the `storage` config.
  */
-export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig;
+export type BackendStorageConfig = LocalStorageConfig | S3StorageConfig | GCSStorageConfig;
 
 /**
  * Storage controller interface for backend implementations

package/test/api-generator.test.ts

@@ -545,7 +545,7 @@ passwordHash: "custom-hash" },
                 } as any
             ];
 
-            const generator = new RestApiGenerator(authCollections, mockDriver, undefined, mockAuthAdapter as any);
+            const generator = new RestApiGenerator(authCollections, mockDriver, mockAuthAdapter as any);
             app.route("/api", generator.generateRoutes());
 
             mockDriver.saveEntity.mockResolvedValue({

package/test/auth-config-types.test.ts

@@ -0,0 +1,40 @@
+/**
+ * Compile-time tests for `RebaseAuthConfig`.
+ *
+ * The Jest assertions are trivial (always true) — the real value is that
+ * `tsc` validates the `@ts-expect-error` annotations: if a line compiles
+ * when it shouldn't, tsc reports an error. This guards against a
+ * regression of the `[key: string]: unknown` catch-all that used to make
+ * every key (including typos) compile silently.
+ */
+import type { RebaseAuthConfig } from "../src/init";
+
+describe("RebaseAuthConfig", () => {
+
+    it("accepts known top-level keys", () => {
+        const config: RebaseAuthConfig = {
+            jwtSecret: "secret",
+            allowRegistration: true,
+            defaultRole: "viewer",
+            google: { clientId: "id" }
+        };
+        expect(config.jwtSecret).toBe("secret");
+    });
+
+    it("rejects a misspelled top-level key (compile-time)", () => {
+        const config: RebaseAuthConfig = {
+            jwtSecret: "secret",
+            // @ts-expect-error — "jwtSecrt" is a typo, not a real RebaseAuthConfig key
+            jwtSecrt: "secret"
+        };
+        expect(config).toBeDefined();
+    });
+
+    it("rejects an unknown provider-shaped key (compile-time)", () => {
+        const config: RebaseAuthConfig = {
+            // @ts-expect-error — "seedDefaultRoles" is not a supported option
+            seedDefaultRoles: true
+        };
+        expect(config).toBeDefined();
+    });
+});

package/test/define-function.test.ts

@@ -0,0 +1,45 @@
+import { Hono } from "hono";
+import { defineFunction } from "../src/functions/define-function";
+
+describe("defineFunction", () => {
+    it("returns a loader-compatible Hono app (has .fetch and .routes)", () => {
+        const app = defineFunction((a) => {
+            a.get("/ping", (c) => c.text("pong"));
+        });
+
+        // These are exactly the properties the loader duck-types on.
+        expect(typeof app.fetch).toBe("function");
+        expect(Array.isArray(app.routes)).toBe(true);
+    });
+
+    it("registers routes on the provided app", async () => {
+        const app = defineFunction((a) => {
+            a.get("/hello", (c) => c.text("hi"));
+        });
+
+        const res = await app.request("/hello");
+        expect(res.status).toBe(200);
+        expect(await res.text()).toBe("hi");
+    });
+
+    it("exposes the rebase singleton via the injected context", () => {
+        let received: unknown;
+        defineFunction((_a, ctx) => {
+            received = ctx.rebase;
+        });
+        // The singleton reference is passed without being dereferenced,
+        // so no "not initialized" error is thrown at define time.
+        expect(received).toBeDefined();
+    });
+
+    it("uses a returned Hono app when the definition returns one", async () => {
+        const custom = new Hono();
+        custom.get("/custom", (c) => c.text("custom"));
+
+        const app = defineFunction(() => custom);
+
+        const res = await app.request("/custom");
+        expect(res.status).toBe(200);
+        expect(await res.text()).toBe("custom");
+    });
+});