@rebasepro/server-core 0.4.0 → 0.5.0

package/dist/server-core/src/api/errors.d.ts

@@ -28,6 +28,21 @@ export interface ErrorResponse {
         details?: unknown;
     };
 }
+/**
+ * General shape of errors that flow through the API error handler.
+ * Extends Error with optional HTTP status, error code, and details.
+ */
+export interface RebaseApiError extends Error {
+    statusCode?: number;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * Type guard for errors that carry optional API metadata (statusCode, code, details).
+ * Returns true for any Error instance — the optional properties are then
+ * checked via normal property access.
+ */
+export declare function isRebaseApiError(error: unknown): error is RebaseApiError;
 /**
  * Hono error-handling middleware (`app.onError`).
  * Converts any error into the canonical `{ error: { message, code } }` shape.

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

@@ -9,6 +9,16 @@ export interface AccessTokenPayload {
     uid?: string;
     /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
     aal?: "aal1" | "aal2";
+    /** Email claim from the JWT, if present */
+    email?: string;
+    /** Display name claim from the JWT, if present */
+    displayName?: string;
+    /** Photo URL claim from the JWT, if present */
+    photoURL?: string;
+    /** Whether MFA has been verified for this session */
+    mfa_verified?: boolean;
+    /** Authentication Methods Reference — list of methods used (e.g. 'pwd', 'otp') */
+    amr?: string[];
 }
 /**
  * Configure JWT settings - call this during initialization.

package/dist/types/src/types/backend.d.ts

@@ -1,5 +1,6 @@
 import type { Entity } from "./entities";
 import type { EntityCollection, FilterValues, WhereFilterOp } from "./collections";
+import type { AuthAdapter } from "./auth_adapter";
 /**
  * Abstract database connection interface.
  * Represents a connection to any database system.
@@ -182,6 +183,24 @@ export interface RealtimeProvider {
      * Notify all relevant subscribers of an entity update
      */
     notifyEntityUpdate(path: string, entityId: string, entity: Entity | null, databaseId?: string): Promise<void>;
+    /**
+     * Called when the HTTP server is ready and listening.
+     * Useful for providers that need the server address for callbacks.
+     */
+    onServerReady?(serverInfo: {
+        port: number;
+        hostname?: string;
+    }): void;
+    /**
+     * Gracefully shut down the realtime provider.
+     * Called during server shutdown to clean up resources.
+     */
+    destroy?(): Promise<void>;
+    /**
+     * Stop the internal LISTEN client (e.g., PostgreSQL LISTEN/NOTIFY).
+     * Called during graceful shutdown before closing database connections.
+     */
+    stopListening?(): Promise<void>;
 }
 /**
  * Abstract collection registry interface.
@@ -464,6 +483,22 @@ export interface BackendBootstrapper {
      * (e.g., `"postgres"`, `"mongodb"`, `"mysql"`).
      */
     type: string;
+    /**
+     * Unique identifier for this bootstrapper instance.
+     * Used to register the driver in the driver registry.
+     * Defaults to `type` if not set.
+     */
+    id?: string;
+    /**
+     * Whether this bootstrapper provides the default driver.
+     * When true, the coordinator uses this driver as the primary one.
+     */
+    isDefault?: boolean;
+    /**
+     * Run database migrations for this driver.
+     * Called by the coordinator after all drivers are initialized.
+     */
+    runMigrations?(config: unknown, driverResult: InitializedDriver): Promise<void>;
     /**
      * Create a DataDriver from the given config.
      * This is the only **required** method.
@@ -498,7 +533,7 @@ export interface BackendBootstrapper {
     /**
      * Initialize WebSocket server for realtime operations.
      */
-    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown): Promise<void> | void;
+    initializeWebsockets?(server: unknown, realtimeService: RealtimeProvider, driver: import("../controllers/data_driver").DataDriver, config?: unknown, authAdapter?: AuthAdapter): Promise<void> | void;
 }
 /**
  * Result of `BackendBootstrapper.initializeDriver()`.

package/dist/types/src/types/collections.d.ts

@@ -343,6 +343,23 @@ export interface BaseEntityCollection<M extends Record<string, unknown> = Record
      * Builder for the collection actions rendered in the toolbar
      */
     Actions?: ComponentRef<CollectionActionsProps>[];
+    /**
+     * The database table name for this collection.
+     * Automatically set for PostgreSQL collections.
+     * For non-SQL backends, this may be undefined.
+     */
+    table?: string;
+    /**
+     * Relations defined for this collection.
+     * Populated at normalization time from inline relation properties
+     * or explicit relation definitions.
+     */
+    relations?: Relation[];
+    /**
+     * Security rules for this collection (Row Level Security).
+     * When defined, the backend enforces access control policies.
+     */
+    securityRules?: SecurityRule[];
 }
 /**
  * A collection backed by PostgreSQL (or any SQL database).
@@ -436,7 +453,10 @@ export interface MongoDBCollection<M extends Record<string, unknown> = Record<st
  * @group Models
  */
 export type EntityCollection<M extends Record<string, unknown> = Record<string, unknown>, USER extends User = User> = PostgresCollection<M, USER> | FirebaseCollection<M, USER> | MongoDBCollection<M, USER>;
-/** An EntityCollection that supports SQL-style relations (e.g. Postgres). */
+/**
+ * An EntityCollection that supports SQL-style relations (e.g. Postgres).
+ * @deprecated Use `EntityCollection` directly — `table`, `relations`, and `securityRules` are now on `BaseEntityCollection`.
+ */
 export type CollectionWithRelations<M extends Record<string, unknown> = Record<string, unknown>> = EntityCollection<M> & {
     table?: string;
     relations?: Relation[];

package/dist/types/src/types/properties.d.ts

@@ -641,14 +641,6 @@ export interface MapProperty extends BaseProperty {
      * Properties that are displayed when rendered as a preview
      */
     previewProperties?: string[];
-    /**
-     * Allow the user to add only some keys in this map.
-     * By default, all properties of the map have the corresponding field in
-     * the form view. Setting this flag to true allows to pick only some.
-     * Useful for map that can have a lot of sub-properties that may not be
-     * needed
-     */
-    pickOnlySomeKeys?: boolean;
     /**
      * Render this map as a key-value table that allows to use
      * arbitrary keys. You don't need to define the properties in this case.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/server-core",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Database-Agnostic Backend Core for Rebase",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -54,10 +54,10 @@
     "ts-morph": "27.0.2",
     "ws": "^8.20.1",
     "zod": "^3.25.76",
-    "@rebasepro/client": "0.4.0",
-    "@rebasepro/common": "0.4.0",
-    "@rebasepro/utils": "0.4.0",
-    "@rebasepro/types": "0.4.0"
+    "@rebasepro/common": "0.5.0",
+    "@rebasepro/client": "0.5.0",
+    "@rebasepro/types": "0.5.0",
+    "@rebasepro/utils": "0.5.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/api/errors.ts

@@ -70,13 +70,32 @@ export interface ErrorResponse {
     };
 }
 
+/**
+ * General shape of errors that flow through the API error handler.
+ * Extends Error with optional HTTP status, error code, and details.
+ */
+export interface RebaseApiError extends Error {
+    statusCode?: number;
+    code?: string;
+    details?: unknown;
+}
+
+/**
+ * Type guard for errors that carry optional API metadata (statusCode, code, details).
+ * Returns true for any Error instance — the optional properties are then
+ * checked via normal property access.
+ */
+export function isRebaseApiError(error: unknown): error is RebaseApiError {
+    return error instanceof Error;
+}
+
 /**
  * Hono error-handling middleware (`app.onError`).
  * Converts any error into the canonical `{ error: { message, code } }` shape.
  */
 export const errorHandler: ErrorHandler = (err, c) => {
     // Typecast custom error properties
-    const error = err as Error & { statusCode?: number; code?: string; details?: unknown, name?: string };
+    const error: RebaseApiError = err;
 
     if (error instanceof ApiError || error.name === "ApiError") {
         // Operational errors — log at warn level

package/src/api/openapi-generator.ts

@@ -314,7 +314,7 @@ content: { "application/json": { schema: { $ref: "#/components/schemas/ErrorResp
         };
 
         // ── Subcollection routes ──────────────────────────────────────
-        const relations = (collection as EntityCollection & { relations?: Relation[] }).relations;
+        const relations = collection.relations;
         if (relations && relations.length > 0) {
             for (const relation of relations) {
                 const relationName = relation.relationName;

package/src/api/rest/api-generator.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import { DataDriver, Entity, EntityCollection, FetchCollectionProps, DataHooks, BackendHookContext, RestFetchService } from "@rebasepro/types";
 import { QueryOptions, HonoEnv } from "../types";
-import { ApiError } from "../errors";
+import { ApiError, isRebaseApiError } from "../errors";
 import { parseQueryOptions } from "./query-parser";
 import { httpMethodToOperation, isOperationAllowed } from "../../auth/api-keys/api-key-permission-guard";
 import type { ApiKeyMasked } from "../../auth/api-keys/api-key-types";
@@ -234,9 +234,10 @@ export class RestApiGenerator {
 
                 return c.json(response, 201);
             } catch (error) {
-                const err = error as Error & { code?: string };
-                err.code = err.code || "BAD_REQUEST";
-                throw err;
+                if (isRebaseApiError(error) && !error.code) {
+                    error.code = "BAD_REQUEST";
+                }
+                throw error;
             }
         });
 
@@ -282,9 +283,10 @@ export class RestApiGenerator {
 
                 return c.json(response);
             } catch (error) {
-                const err = error as Error & { code?: string };
-                err.code = err.code || "BAD_REQUEST";
-                throw err;
+                if (isRebaseApiError(error) && !error.code) {
+                    error.code = "BAD_REQUEST";
+                }
+                throw error;
             }
         });
 
@@ -386,6 +388,8 @@ entityId };
 
             this.enforceApiKeyPermission(c, c.req.param("parent"));
 
+            const hookCtx = this.buildHookContext(c, "GET");
+
             if (parsed.entityId === "count") {
                 // GET /parent/:parentId/child/count — count child entities
                 const queryDict = c.req.queries();
@@ -406,7 +410,12 @@ entityId };
                     entityId: parsed.entityId
                 });
                 if (!entity) throw ApiError.notFound("Entity not found");
-                return c.json(this.flattenEntity(entity));
+
+                const flatResult = this.flattenEntity(entity);
+                const hookResult = await this.applyAfterRead(c.req.param("parent"), flatResult, hookCtx);
+                if (!hookResult) throw ApiError.notFound("Entity not found");
+
+                return c.json(hookResult);
             } else {
                 // GET /parent/:parentId/child — list entities
                 const queryDict = c.req.queries();
@@ -420,13 +429,23 @@ entityId };
                     order: queryOptions.orderBy?.[0]?.direction === "desc" ? "desc" : "asc",
                     searchString
                 });
+
+                let flatEntities = entities.map(e => this.flattenEntity(e));
+                flatEntities = await this.applyAfterReadBatch(c.req.param("parent"), flatEntities, hookCtx);
+
+                const total = driver.countEntities ? await driver.countEntities({
+                    path: parsed.collectionPath,
+                    filter: queryOptions.where as FetchCollectionProps["filter"],
+                    searchString
+                }) : flatEntities.length;
+
                 return c.json({
-                    data: entities.map(e => this.flattenEntity(e)),
+                    data: flatEntities,
                     meta: {
-                        total: entities.length,
+                        total,
                         limit: queryOptions.limit,
                         offset: queryOptions.offset,
-                        hasMore: false
+                        hasMore: (queryOptions.offset || 0) + flatEntities.length < total
                     }
                 });
             }
@@ -441,9 +460,14 @@ entityId };
             if (!parsed || parsed.entityId) return next();
 
             const driver = c.get("driver") || this.driver;
+            const hookCtx = this.buildHookContext(c, "POST");
 
             this.enforceApiKeyPermission(c, c.req.param("parent"));
-            const body = await c.req.json().catch(() => ({}));
+            let body = await c.req.json().catch(() => ({}));
+
+            if (this.dataHooks?.beforeSave) {
+                body = await this.dataHooks.beforeSave(parsed.collectionPath, body, undefined, hookCtx);
+            }
 
             const entity = await driver.saveEntity({
                 path: parsed.collectionPath,
@@ -451,7 +475,15 @@ entityId };
                 status: "new"
             });
 
-            return c.json(this.formatResponse(entity), 201);
+            const response = this.formatResponse(entity);
+
+            if (this.dataHooks?.afterSave) {
+                Promise.resolve(this.dataHooks.afterSave(parsed.collectionPath, response as Record<string, unknown>, hookCtx)).catch(err => {
+                    console.error("[BackendHooks] data.afterSave error:", err instanceof Error ? err.message : err);
+                });
+            }
+
+            return c.json(response, 201);
         });
 
         // PUT /<subcollection-path>/:id — update entity
@@ -463,10 +495,15 @@ entityId };
             if (!parsed || !parsed.entityId) return next();
 
             const driver = c.get("driver") || this.driver;
+            const hookCtx = this.buildHookContext(c, "PUT");
 
             this.enforceApiKeyPermission(c, c.req.param("parent"));
 
-            const body = await c.req.json().catch(() => ({}));
+            let body = await c.req.json().catch(() => ({}));
+
+            if (this.dataHooks?.beforeSave) {
+                body = await this.dataHooks.beforeSave(parsed.collectionPath, body, parsed.entityId, hookCtx);
+            }
 
             const entity = await driver.saveEntity({
                 path: parsed.collectionPath,
@@ -475,7 +512,15 @@ entityId };
                 status: "existing"
             });
 
-            return c.json(this.formatResponse(entity));
+            const response = this.formatResponse(entity);
+
+            if (this.dataHooks?.afterSave) {
+                Promise.resolve(this.dataHooks.afterSave(parsed.collectionPath, response as Record<string, unknown>, hookCtx)).catch(err => {
+                    console.error("[BackendHooks] data.afterSave error:", err instanceof Error ? err.message : err);
+                });
+            }
+
+            return c.json(response);
         });
 
         // DELETE /<subcollection-path>/:id — delete entity
@@ -487,6 +532,7 @@ entityId };
             if (!parsed || !parsed.entityId) return next();
 
             const driver = c.get("driver") || this.driver;
+            const hookCtx = this.buildHookContext(c, "DELETE");
 
             this.enforceApiKeyPermission(c, c.req.param("parent"));
 
@@ -497,8 +543,18 @@ entityId };
 
             if (!existingEntity) throw ApiError.notFound("Entity not found");
 
+            if (this.dataHooks?.beforeDelete) {
+                await this.dataHooks.beforeDelete(parsed.collectionPath, parsed.entityId, hookCtx);
+            }
+
             await driver.deleteEntity({ entity: existingEntity });
 
+            if (this.dataHooks?.afterDelete) {
+                Promise.resolve(this.dataHooks.afterDelete(parsed.collectionPath, parsed.entityId, hookCtx)).catch(err => {
+                    console.error("[BackendHooks] data.afterDelete error:", err instanceof Error ? err.message : err);
+                });
+            }
+
             return new Response(null, { status: 204 });
         });
     }

package/src/api/server.ts

@@ -120,7 +120,7 @@ export class RebaseApiServer {
                 singularName: col.singularName,
                 description: col.description,
                 properties: Object.keys(col.properties),
-                relations: (col as EntityCollection & { relations?: Relation[] }).relations?.map((r: Relation) => ({
+                relations: col.relations?.map((r: Relation) => ({
                     relationName: r.relationName,
                     target: typeof r.target === "function" ? r.target().slug : r.target,
                     cardinality: r.cardinality,

package/src/auth/builtin-auth-adapter.ts

@@ -119,12 +119,6 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
                 return null;
             }
 
-            // The decoded JWT may contain additional claims beyond the typed payload
-            const extendedPayload = payload as AccessTokenPayload & {
-                email?: string;
-                displayName?: string;
-            };
-
             // Resolve roles from the repository
             let roles: string[] = payload.roles || [];
             try {
@@ -137,8 +131,8 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
 
             return {
                 uid: payload.userId,
-                email: extendedPayload.email ?? "",
-                displayName: extendedPayload.displayName ?? null,
+                email: payload.email ?? "",
+                displayName: payload.displayName ?? null,
                 roles,
                 isAdmin,
                 rawToken: token,
@@ -163,11 +157,6 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
                 return null;
             }
 
-            const extendedPayload = payload as AccessTokenPayload & {
-                email?: string;
-                displayName?: string;
-            };
-
             let roles: string[] = payload.roles || [];
             try {
                 roles = await authRepository.getUserRoleIds(payload.userId);
@@ -179,8 +168,8 @@ export function createBuiltinAuthAdapter(config: BuiltinAuthAdapterConfig): Auth
 
             return {
                 uid: payload.userId,
-                email: extendedPayload.email ?? "",
-                displayName: extendedPayload.displayName ?? null,
+                email: payload.email ?? "",
+                displayName: payload.displayName ?? null,
                 roles,
                 isAdmin,
                 rawToken: token,

package/src/auth/jwt.ts

@@ -13,6 +13,16 @@ export interface AccessTokenPayload {
     uid?: string;
     /** Authentication Assurance Level: aal1 = password/oauth, aal2 = MFA verified */
     aal?: "aal1" | "aal2";
+    /** Email claim from the JWT, if present */
+    email?: string;
+    /** Display name claim from the JWT, if present */
+    displayName?: string;
+    /** Photo URL claim from the JWT, if present */
+    photoURL?: string;
+    /** Whether MFA has been verified for this session */
+    mfa_verified?: boolean;
+    /** Authentication Methods Reference — list of methods used (e.g. 'pwd', 'otp') */
+    amr?: string[];
 }
 
 let jwtConfig: JwtConfig = {

package/src/auth/routes.ts

@@ -1171,18 +1171,14 @@ message: "Session revoked successfully" });
             throw ApiError.notFound("MFA factor not found");
         }
 
-        // Check if this is a recovery code (10 chars with hyphen) or TOTP (6 digits)
-        const isRecoveryCode = code.length > 6;
-        let isValid = false;
+        // Try TOTP verification first (standard 6-digit codes)
+        const secretBuffer = base32Decode(factor.secretEncrypted);
+        let isValid = verifyTotp(secretBuffer, code);
 
-        if (isRecoveryCode) {
-            // Try recovery code
+        // Fall back to recovery code verification if TOTP didn't match
+        if (!isValid) {
             const codeHash = hashRecoveryCode(code);
             isValid = await authRepo.useRecoveryCode(userCtx.userId, codeHash);
-        } else {
-            // Verify TOTP
-            const secretBuffer = base32Decode(factor.secretEncrypted);
-            isValid = verifyTotp(secretBuffer, code);
         }
 
         if (!isValid) {

package/src/init.ts

@@ -395,7 +395,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
     // 1. Initialize all drivers
     for (const bootstrapper of bootstrappers) {
-        const b = bootstrapper as BackendBootstrapper & { id?: string; isDefault?: boolean };
+        const b = bootstrapper;
         logger.info("Running bootstrapper for driver", { driverId: b.id || bootstrapper.type });
         if (b.isDefault) {
             defaultDriverId = b.id || bootstrapper.type;
@@ -413,7 +413,9 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
 
         if (bootstrapper.initializeRealtime) {
             const realtime = await bootstrapper.initializeRealtime({}, driverResult);
-            realtimeServices[b.id || bootstrapper.type] = realtime as RealtimeProvider;
+            if (realtime) {
+                realtimeServices[b.id || bootstrapper.type] = realtime;
+            }
         }
     }
 
@@ -424,9 +426,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
     if (!defaultDriver || !defaultDriverResult) {
         throw new Error("Default driver not initialized by bootstrappers");
     }
-    const defaultBootstrapper = bootstrappers.find(b => (b as BackendBootstrapper & {
-        id?: string
-    }).id === defaultDriverId || b.type === defaultDriverId) || bootstrappers[0];
+    const defaultBootstrapper = bootstrappers.find(b => b.id === defaultDriverId || b.type === defaultDriverId) || bootstrappers[0];
     const defaultRealtimeService = defaultDriverResult.realtimeProvider;
 
     // 2. Initialize Auth & History via the default driver's bootstrapper
@@ -721,7 +721,7 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         // maxFileSize (default 50MB), which overrides the global API body limit.
         const storageMaxSize = (
             config.storage && typeof config.storage === "object" && "type" in config.storage
-                ? (config.storage as BackendStorageConfig & { maxFileSize?: number }).maxFileSize
+                ? (config.storage as BackendStorageConfig).maxFileSize
                 : undefined
         ) ?? 50 * 1024 * 1024;
 
@@ -998,12 +998,8 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
         }
     }
 
-    if ((defaultBootstrapper as BackendBootstrapper & {
-        initializeWebsockets?: (...args: unknown[]) => unknown
-    }).initializeWebsockets) {
-        await (defaultBootstrapper as BackendBootstrapper & {
-            initializeWebsockets: (...args: unknown[]) => unknown
-        }).initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
+    if (defaultBootstrapper.initializeWebsockets && defaultRealtimeService) {
+        await defaultBootstrapper.initializeWebsockets(config.server, defaultRealtimeService, defaultDriver, config.auth, authAdapter);
     }
 
     logger.info("Rebase Backend Initialized");
@@ -1061,15 +1057,11 @@ async function _initializeRebaseBackend(config: RebaseBackendConfig): Promise<Re
                 //    timer callbacks don't fire against a closed pool.
                 for (const [key, rt] of Object.entries(realtimeServices)) {
                     try {
-                        const rtWithLifecycle = rt as RealtimeProvider & {
-                            destroy?: () => Promise<void>;
-                            stopListening?: () => Promise<void>
-                        };
-                        if (typeof rtWithLifecycle.destroy === "function") {
-                            await rtWithLifecycle.destroy();
+                        if (typeof rt.destroy === "function") {
+                            await rt.destroy();
                             logger.info(`Realtime service "${key}" destroyed`);
-                        } else if (typeof rtWithLifecycle.stopListening === "function") {
-                            await rtWithLifecycle.stopListening();
+                        } else if (typeof rt.stopListening === "function") {
+                            await rt.stopListening();
                             logger.info(`Realtime service "${key}" LISTEN client stopped`);
                         }
                     } catch (err) {

package/test.ts

@@ -1,6 +0,0 @@
-interface I {
-    verify: (payload: any) => void;
-}
-const obj: I = {
-    verify: (payload: { code: string }) => {}
-};