@rebasepro/server-core 0.6.1 → 0.8.0

package/dist/storage/GCSStorageController.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Google Cloud Storage controller (works with GCS and Firebase Storage)
+ *
+ * The `@google-cloud/storage` package is loaded lazily so it remains an
+ * optional peer dependency — users who don't need GCS never pay for the
+ * import cost or need it installed.
+ */
+import { StorageController, GCSStorageConfig } from "./types";
+import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
+/**
+ * Google Cloud Storage implementation of `StorageController`.
+ *
+ * Works with standard GCS buckets **and** Firebase Storage buckets
+ * (e.g. `"my-project.appspot.com"`).
+ */
+export declare class GCSStorageController implements StorageController {
+    private config;
+    private client;
+    constructor(config: GCSStorageConfig);
+    private getClient;
+    getType(): "gcs";
+    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    getObject(key: string, bucket?: string): Promise<File | null>;
+    deleteObject(key: string, bucket?: string): Promise<void>;
+    listObjects(prefix: string, options?: {
+        bucket?: string;
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<StorageListResult>;
+    /**
+     * Validate file before upload
+     */
+    private validateFile;
+    /**
+     * Get the bucket name — either from parameter or config.
+     */
+    private getBucket;
+    /**
+     * Flatten nested metadata to string values (GCS custom metadata requirement)
+     */
+    private flattenMetadata;
+}

package/dist/storage/index.d.ts

@@ -1,17 +1,20 @@
 /**
  * Storage module for Rebase backend
  *
- * Provides pluggable file storage with two built-in providers:
+ * Provides pluggable file storage with three built-in providers:
  * - **Local filesystem** — zero config, great for dev and single-server deployments.
  * - **S3-compatible** — works with AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,
  *   Backblaze B2, DigitalOcean Spaces, and GCS (via S3 interop).
+ * - **Google Cloud Storage / Firebase Storage** — native GCS support via `@google-cloud/storage`
+ *   (optional peer dependency, lazily loaded).
  *
- * For other providers (native GCS SDK, Azure Blob, etc.), implement the
+ * For other providers (Azure Blob, etc.), implement the
  * `StorageController` interface and pass the instance directly to the `storage` config.
  */
 export * from "./types";
 export { LocalStorageController } from "./LocalStorageController";
 export { S3StorageController } from "./S3StorageController";
+export { GCSStorageController } from "./GCSStorageController";
 export { createStorageRoutes } from "./routes";
 export type { StorageRoutesConfig } from "./routes";
 export * from "./storage-registry";

package/dist/storage/routes.d.ts

@@ -1,11 +1,36 @@
 /**
  * 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 { StorageController } from "./types";
+import type { StorageRegistry } from "./storage-registry";
+import { type StorageSourceDefinition, type AuthAdapter } from "@rebasepro/types";
 import { HonoEnv } from "../api/types";
 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) */
@@ -13,6 +38,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;
 }
 /**
  * Extract the wildcard portion of a route path from the full request path.

package/dist/storage/tus-handler.d.ts

@@ -9,6 +9,7 @@
  */
 import type { Context } from "hono";
 import type { StorageController } from "./types";
+import type { StorageRegistry } from "./storage-registry";
 /**
  * TUS resumable upload handler.
  *
@@ -18,10 +19,11 @@ import type { StorageController } from "./types";
  */
 export declare class TusHandler {
     private storageController?;
+    private storageRegistry?;
     private uploads;
     private tusDir;
     private cleanupTimer?;
-    constructor(storageBaseDir: string, storageController?: StorageController | undefined);
+    constructor(storageBaseDir: string, storageController?: StorageController | undefined, storageRegistry?: StorageRegistry | undefined);
     /** Ensure the temp directory exists. */
     private ensureDir;
     /** Start periodic cleanup of stale uploads. */

package/dist/storage/types.d.ts

@@ -41,18 +41,43 @@ export interface S3StorageConfig {
     signedUrlExpiration?: number;
 }
 /**
- * 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/dist/utils/dev-port.d.ts

@@ -28,6 +28,8 @@ export declare function listenWithPortRetry(server: Server, startPort: number, o
     maxAttempts?: number;
     /** Absolute path to write the resolved port file into.  Defaults to `process.cwd()`. */
     portFileDir?: string;
+    /** Service key to include in the state file for MCP server auto-discovery. */
+    serviceKey?: string;
 }): Promise<number>;
 /**
  * Clean up the dev port file and state file (call on graceful shutdown).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-core",
   "type": "module",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Database-Agnostic Backend Core for Rebase",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -54,10 +54,10 @@
     "ts-morph": "28.0.0",
     "ws": "^8.21.0",
     "zod": "^4.4.3",
-    "@rebasepro/client": "0.6.1",
-    "@rebasepro/types": "0.6.1",
-    "@rebasepro/utils": "0.6.1",
-    "@rebasepro/common": "0.6.1"
+    "@rebasepro/client": "0.8.0",
+    "@rebasepro/common": "0.8.0",
+    "@rebasepro/types": "0.8.0",
+    "@rebasepro/utils": "0.8.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
@@ -74,6 +74,14 @@
     "typescript": "^6.0.3",
     "vite": "^8.0.16"
   },
+  "peerDependencies": {
+    "@google-cloud/storage": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/storage": {
+      "optional": true
+    }
+  },
   "gitHead": "d935eefa5aa8d1009a2398cfac2c1e4ee9aeb6b6",
   "publishConfig": {
     "access": "public"

package/src/api/errors.ts

@@ -145,12 +145,26 @@ export const errorHandler: ErrorHandler<HonoEnv> = (err, c) => {
 
     // Handle DB connection and specific system errors for better logging
     let logMessage = error.message;
+
+    // Resolve the actual cause — Node's net module wraps dual-stack failures
+    // in an AggregateError whose inner errors carry the real address/port.
+    let resolvedCause: PgLikeError | undefined;
     if (error.cause && typeof error.cause === "object" && error.cause !== null && "code" in error.cause) {
-        const cause = error.cause as PgLikeError;
+        const cause = error.cause as PgLikeError & { errors?: PgLikeError[] };
+        if (cause.code === "ECONNREFUSED" && !cause.address && Array.isArray(cause.errors)) {
+            // AggregateError — pick the first inner error that has address info
+            resolvedCause = cause.errors.find(e => e.address) || cause;
+        } else {
+            resolvedCause = cause;
+        }
+    }
+
+    if (resolvedCause) {
+        const cause = resolvedCause;
         if (cause.code === "ENETUNREACH") {
             logMessage = `Network unreachable. Cannot connect to database at ${cause.address}:${cause.port}.`;
         } else if (cause.code === "ECONNREFUSED") {
-            logMessage = `Connection refused to database at ${cause.address}:${cause.port}.`;
+            logMessage = `Connection refused to database at ${cause.address}:${cause.port}. Is PostgreSQL running?`;
         } else if (cause.code === "42703" || cause.code === "42P01") {
             code = "SCHEMA_DRIFT";
             const issue = cause.code === "42703" ? "column" : "table";

package/src/api/graphql/graphql-schema-generator.ts

@@ -11,7 +11,15 @@ import {
     GraphQLInputObjectType,
     GraphQLInputFieldConfig
 } from "graphql";
-import { DataDriver, EntityCollection, FetchCollectionProps, Property, Entity } from "@rebasepro/types";
+import { DataDriver, EntityCollection, FetchCollectionProps, Property, Entity, getCollectionDataPath } from "@rebasepro/types";
+import { isOperationAllowed, type ApiKeyOperation } from "../../auth/api-keys/api-key-permission-guard";
+import type { ApiKeyMasked } from "../../auth/api-keys/api-key-types";
+
+/** Context shape provided by @hono/graphql-server (Hono's Context object). */
+type GraphQLResolverContext = {
+    get?: (key: string) => unknown;
+    driver?: DataDriver;
+};
 
 /**
  * Lightweight GraphQL schema generator that leverages existing DataDriver
@@ -28,6 +36,28 @@ export class GraphQLSchemaGenerator {
         this.driver = driver;
     }
 
+    /**
+     * Enforce API key permission scoping for a GraphQL resolver.
+     *
+     * Extracts the `apiKey` from the Hono context passed by `@hono/graphql-server`.
+     * If the request was made with an API key and the key does not have the
+     * required permission for the target collection/operation, an error is thrown.
+     * Non-API-key requests (e.g. session auth) are allowed through.
+     */
+    private enforceApiKeyPermission(
+        context: GraphQLResolverContext | undefined,
+        collectionSlug: string,
+        operation: ApiKeyOperation
+    ): void {
+        const apiKey = context?.get?.("apiKey") as ApiKeyMasked | undefined;
+        if (!apiKey) return;
+        if (!isOperationAllowed(apiKey.permissions, collectionSlug, operation)) {
+            throw new Error(
+                `API key does not have "${operation}" permission for collection "${collectionSlug}"`
+            );
+        }
+    }
+
     /**
      * Generate complete GraphQL schema using existing DataDriver
      */
@@ -184,11 +214,12 @@ export class GraphQLSchemaGenerator {
                     id: { type: new GraphQLNonNull(GraphQLString) }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "read");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     const entity = await ds.fetchEntity({
-                        path: collection.slug,
+                        path: getCollectionDataPath(collection),
                         entityId: args.id,
                         collection
                     });
@@ -208,8 +239,9 @@ defaultValue: 0 },
                     orderBy: { type: GraphQLString }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "read");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     let filter: FetchCollectionProps["filter"] | undefined;
                     if (args.where) {
@@ -224,7 +256,7 @@ defaultValue: 0 },
                         }
                     }
                     const entities = await ds.fetchCollection({
-                        path: collection.slug,
+                        path: getCollectionDataPath(collection),
                         collection,
                         filter,
                         limit: args.limit,
@@ -261,8 +293,9 @@ defaultValue: 0 },
                     input: { type: new GraphQLNonNull(inputType) }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "write");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     const path = collection.slug;
                     const entity = await ds.saveEntity({
@@ -283,11 +316,12 @@ defaultValue: 0 },
                     input: { type: new GraphQLNonNull(inputType) }
                 },
                 resolve: async (_, args, context: unknown) => {
-                    const ctx = context as { driver?: DataDriver } | undefined;
-                    const ds = ctx?.driver;
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "write");
+                    const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                     if (!ds) throw new Error("Scoped driver not available");
                     const entity = await ds.saveEntity({
-                        path: collection.slug,
+                        path: getCollectionDataPath(collection),
                         entityId: args.id,
                         values: args.input,
                         collection,
@@ -304,12 +338,13 @@ defaultValue: 0 },
                     id: { type: new GraphQLNonNull(GraphQLString) }
                 },
                 resolve: async (_, args, context: unknown) => {
+                    const ctx = context as GraphQLResolverContext | undefined;
+                    this.enforceApiKeyPermission(ctx, collection.slug, "delete");
                     try {
-                        const ctx = context as { driver?: DataDriver } | undefined;
-                        const ds = ctx?.driver;
+                        const ds = ctx?.get?.("driver") as DataDriver | undefined ?? (ctx as Record<string, unknown> | undefined)?.driver as DataDriver | undefined;
                         if (!ds) throw new Error("Scoped driver not available");
                         const existingEntity = await ds.fetchEntity({
-                            path: collection.slug,
+                            path: getCollectionDataPath(collection),
                             entityId: args.id,
                             collection
                         });

package/src/api/openapi-generator.ts

@@ -491,9 +491,9 @@ function convertPropertyToSchema(property: Property): Record<string, unknown> {
             }
 
             if (sp.email) base.format = "email";
-            if (sp.url) base.format = "uri";
+            if (sp.ui?.url) base.format = "uri";
             if (sp.storage) base.format = "uri";
-            if (sp.markdown) base.description = (base.description || "") + " (Markdown)";
+            if (sp.ui?.markdown) base.description = (base.description || "") + " (Markdown)";
 
             return base;
         }