@rebasepro/types 0.1.2 → 0.2.3

package/dist/types/properties.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentRef } from "./component_ref";
-import type { EntityReference, EntityRelation, EntityValues, GeoPoint, Entity } from "./entities";
+import type { EntityReference, EntityRelation, EntityValues, GeoPoint, Entity, Vector } from "./entities";
 import type { Relation, JoinStep, OnAction } from "./relations";
 import type { EntityCollection, FilterValues } from "./collections";
 import type { ColorKey, ColorScheme } from "./chips";
@@ -31,8 +31,8 @@ export type PropertyCallbacks<T = unknown, M extends Record<string, unknown> = R
 /**
  * @group Entity properties
  */
-export type DataType = "string" | "number" | "boolean" | "date" | "geopoint" | "reference" | "relation" | "array" | "map";
-export type Property = StringProperty | NumberProperty | BooleanProperty | DateProperty | GeopointProperty | ReferenceProperty | RelationProperty | ArrayProperty | MapProperty;
+export type DataType = "string" | "number" | "boolean" | "date" | "geopoint" | "reference" | "relation" | "array" | "map" | "vector" | "binary";
+export type Property = StringProperty | NumberProperty | BooleanProperty | DateProperty | GeopointProperty | ReferenceProperty | RelationProperty | ArrayProperty | MapProperty | VectorProperty | BinaryProperty;
 export type Properties = {
     [key: string]: Property;
 };
@@ -48,7 +48,7 @@ export type FirebaseProperties = {
  * A helper type to infer the underlying data type from a Property definition.
  * This is the core of the type inference system.
  */
-export type InferPropertyType<P extends Property> = P extends StringProperty ? string : P extends NumberProperty ? number : P extends BooleanProperty ? boolean : P extends DateProperty ? Date : P extends GeopointProperty ? GeoPoint : P extends ReferenceProperty ? EntityReference : P extends RelationProperty ? EntityRelation | EntityRelation[] : P extends ArrayProperty ? (P["of"] extends Property ? InferPropertyType<P["of"]>[] : unknown[]) : P extends MapProperty ? (P["properties"] extends Properties ? InferEntityType<P["properties"]> : Record<string, unknown>) : never;
+export type InferPropertyType<P extends Property> = P extends StringProperty ? string : P extends NumberProperty ? number : P extends BooleanProperty ? boolean : P extends DateProperty ? Date : P extends GeopointProperty ? GeoPoint : P extends ReferenceProperty ? EntityReference : P extends RelationProperty ? EntityRelation | EntityRelation[] : P extends ArrayProperty ? (P["of"] extends Property ? InferPropertyType<P["of"]>[] : unknown[]) : P extends MapProperty ? (P["properties"] extends Properties ? InferEntityType<P["properties"]> : Record<string, unknown>) : P extends VectorProperty ? Vector : P extends BinaryProperty ? string : never;
 /**
  * Helper type that determines whether a property is required.
  * Uses direct structural matching against `{ validation: { required: true } }`
@@ -309,6 +309,25 @@ export interface BooleanProperty extends BaseProperty {
      */
     validation?: PropertyValidationSchema;
 }
+/**
+ * @group Entity properties
+ */
+export interface VectorUIConfig extends BaseUIConfig {
+    clearable?: boolean;
+}
+export interface VectorProperty extends BaseProperty {
+    ui?: VectorUIConfig;
+    type: "vector";
+    dimensions: number;
+    validation?: PropertyValidationSchema;
+}
+/**
+ * @group Entity properties
+ */
+export interface BinaryProperty extends BaseProperty {
+    type: "binary";
+    validation?: PropertyValidationSchema;
+}
 /**
  * @group Entity properties
  */
@@ -421,7 +440,7 @@ export interface RelationProperty extends BaseProperty {
      * When set, the framework treats this property as a self-contained relation
      * definition and no separate `relations[]` entry is needed.
      */
-    target?: () => EntityCollection;
+    target?: string | (() => EntityCollection | string);
     /**
      * Whether this property references one or many records.
      * Defaults to `"one"`.

package/dist/types/property_config.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import { ArrayProperty, MapProperty, StringProperty, NumberProperty, BooleanProperty, DateProperty, GeopointProperty, ReferenceProperty, RelationProperty } from "./properties";
+import { ArrayProperty, MapProperty, StringProperty, NumberProperty, BooleanProperty, DateProperty, GeopointProperty, ReferenceProperty, RelationProperty, VectorProperty, BinaryProperty } from "./properties";
 import { BaseProperty } from "./properties";
 type CMSBasePropertyNoName = Omit<BaseProperty, "name">;
 export type ConfigProperty = (Omit<StringProperty, "name"> & {
@@ -28,6 +28,10 @@ export type ConfigProperty = (Omit<StringProperty, "name"> & {
 } & CMSBasePropertyNoName) | (Omit<MapProperty, "name" | "properties"> & {
     name?: string;
     properties?: Record<string, ConfigProperty>;
+} & CMSBasePropertyNoName) | (Omit<VectorProperty, "name"> & {
+    name?: string;
+} & CMSBasePropertyNoName) | (Omit<BinaryProperty, "name"> & {
+    name?: string;
 } & CMSBasePropertyNoName);
 /**
  * This is the configuration object for a property.
@@ -66,5 +70,5 @@ export type PropertyConfig = {
      */
     description?: string;
 };
-export type PropertyConfigId = "text_field" | "multiline" | "markdown" | "url" | "email" | "user_select" | "select" | "multi_select" | "number_input" | "number_select" | "multi_number_select" | "file_upload" | "multi_file_upload" | "group" | "key_value" | "reference" | "reference_as_string" | "multi_references" | "relation" | "switch" | "date_time" | "repeat" | "custom_array" | "block";
+export type PropertyConfigId = "text_field" | "multiline" | "markdown" | "url" | "email" | "user_select" | "select" | "multi_select" | "number_input" | "number_select" | "multi_number_select" | "file_upload" | "multi_file_upload" | "group" | "key_value" | "reference" | "reference_as_string" | "multi_references" | "relation" | "switch" | "date_time" | "repeat" | "custom_array" | "block" | "vector_input";
 export {};

package/dist/types/relations.d.ts

@@ -17,7 +17,7 @@ export interface Relation {
     /**
      * The final collection you want to retrieve records from.
      */
-    target: () => EntityCollection;
+    target: (() => EntityCollection) | any;
     /**
      * The nature of the relationship, determining if one or many records are returned.
      */

package/dist/types/translations.d.ts

@@ -30,6 +30,8 @@ export interface RebaseTranslations {
     copy: string;
     delete: string;
     delete_not_allowed: string;
+    edit_entity?: string;
+    back_to_detail?: string;
     delete_confirmation_title: string;
     delete_confirmation_body: string;
     delete_multiple_confirmation_body: string;
@@ -392,6 +394,12 @@ export interface RebaseTranslations {
     submit: string;
     no_filterable_properties: string;
     apply_filters: string;
+    /** Label shown on the filter presets dropdown trigger */
+    filter_presets?: string;
+    /** Tooltip shown when hovering over a preset entry */
+    filter_preset_apply?: string;
+    /** Shown when a preset is active, with {{label}} interpolation */
+    filter_preset_active?: string;
     list: string;
     table_view_mode: string;
     cards: string;

package/dist/users/user.d.ts

@@ -42,5 +42,10 @@ export type User = {
      * The date and time when the user was created.
      */
     createdAt?: Date | string | null;
+    /**
+     * Additional metadata/custom claims associated with the user.
+     * Accessible by the frontend, but only writable by the backend.
+     */
+    readonly metadata?: Record<string, any>;
     getIdToken?: (forceRefresh?: boolean) => Promise<string>;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/types",
   "type": "module",
-  "version": "0.1.2",
+  "version": "0.2.3",
   "description": "Rebase type definitions — shared interfaces and controller types",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -32,7 +32,7 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "development": "./src/index.ts",
+      "development": "./dist/index.es.js",
       "import": "./dist/index.es.js",
       "require": "./dist/index.umd.js"
     },
@@ -40,17 +40,20 @@
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",
-    "@types/node": "^20.17.14",
+    "@types/node": "^20.19.41",
     "@types/object-hash": "^3.0.6",
-    "@types/react": "^19.0.8",
-    "@types/react-dom": "^19.0.3",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
     "@types/react-measure": "^2.0.12",
-    "@vitejs/plugin-react": "^4.3.4",
-    "eslint-plugin-react-compiler": "beta",
+    "@vitejs/plugin-react": "^4.7.0",
+    "hono": "^4.12.21",
     "jest": "^29.7.0",
-    "ts-jest": "^29.3.1",
-    "typescript": "^5.8.3",
-    "vite": "^5.4.17"
+    "ts-jest": "^29.4.10",
+    "typescript": "^5.9.3",
+    "vite": "^5.4.21"
+  },
+  "peerDependencies": {
+    "hono": "^4.12.21"
   },
   "files": [
     "dist",

package/src/controllers/auth.tsx

@@ -98,11 +98,8 @@ export type AuthController<USER extends User = User, ExtraData = unknown> = {
 export interface AuthControllerExtended<USER extends User = User, ExtraData = unknown> extends AuthController<USER, ExtraData> {
     /** Login with email and password */
     emailPasswordLogin?(email: string, password: string): Promise<void>;
-    /** Login with a Google token or authorization code */
-    googleLogin?: {
-        (token: string, tokenType?: "idToken" | "accessToken"): Promise<void>;
-        (payload: { code: string; redirectUri: string }): Promise<void>;
-    };
+    /** Login with Google — accepts an ID token, access token, or authorization code payload */
+    googleLogin?: (payload: { idToken: string } | { accessToken: string } | { code: string; redirectUri: string }) => Promise<void>;
     /** Register a new user */
     register?(email: string, password: string, displayName?: string): Promise<void>;
     /** Skip login (for anonymous access if enabled) */

package/src/controllers/client.ts

@@ -61,6 +61,7 @@ export interface AdminUser {
     photoURL: string | null;
     provider: string;
     roles: string[];
+    metadata?: Record<string, any>;
     createdAt: string;
     updatedAt: string;
 }
@@ -92,8 +93,8 @@ export interface AdminAPI {
         orderDir?: "asc" | "desc";
     }): Promise<{ users: AdminUser[]; total: number; limit: number; offset: number }>;
     getUser(userId: string): Promise<{ user: AdminUser }>;
-    createUser(data: { email: string; displayName?: string; password?: string; roles?: string[] }): Promise<{ user: AdminUser }>;
-    updateUser(userId: string, data: { email?: string; displayName?: string; password?: string; roles?: string[] }): Promise<{ user: AdminUser }>;
+    createUser(data: { email: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
+    updateUser(userId: string, data: { email?: string; displayName?: string; password?: string; roles?: string[]; metadata?: Record<string, any> }): Promise<{ user: AdminUser }>;
     deleteUser(userId: string): Promise<{ success: boolean }>;
     listRoles(): Promise<{ roles: AdminRole[] }>;
     getRole(roleId: string): Promise<{ role: AdminRole }>;

package/src/controllers/data.ts

@@ -90,6 +90,23 @@ export interface FindResponse<M extends Record<string, unknown> = Record<string,
     };
 }
 
+export type FilterOperator = WhereFilterOpShort;
+
+/**
+ * Fluent Query Builder Interface supported on both client and server accessors.
+ * @group Data
+ */
+export interface QueryBuilderInterface<M extends Record<string, unknown> = Record<string, unknown>> {
+    where(column: keyof M & string, operator: FilterOperator, value: unknown): this;
+    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): this;
+    limit(count: number): this;
+    offset(count: number): this;
+    search(searchString: string): this;
+    include(...relations: string[]): this;
+    find(): Promise<FindResponse<M>>;
+    listen(onUpdate: (data: FindResponse<M>) => void, onError?: (error: Error) => void): () => void;
+}
+
 /**
  * A single collection's CRUD accessor.
  *
@@ -145,6 +162,14 @@ export interface CollectionAccessor<M extends Record<string, unknown> = Record<s
      * Count the number of records matching the given filter.
      */
     count?(params?: FindParams): Promise<number>;
+
+    // Fluent Query Builder
+    where(column: keyof M & string, operator: FilterOperator, value: unknown): QueryBuilderInterface<M>;
+    orderBy(column: keyof M & string, ascending?: "asc" | "desc"): QueryBuilderInterface<M>;
+    limit(count: number): QueryBuilderInterface<M>;
+    offset(count: number): QueryBuilderInterface<M>;
+    search(searchString: string): QueryBuilderInterface<M>;
+    include(...relations: string[]): QueryBuilderInterface<M>;
 }
 
 /**

package/src/types/auth_adapter.ts

@@ -0,0 +1,410 @@
+/**
+ * @module AuthAdapter
+ *
+ * Pluggable authentication abstraction for Rebase.
+ *
+ * An `AuthAdapter` decouples authentication from the database layer,
+ * allowing users to bring their own auth system (Clerk, Auth0, Firebase Auth,
+ * custom JWT, etc.) while keeping the Rebase admin frontend fully functional.
+ *
+ * @example Built-in auth (default — zero config change)
+ * ```ts
+ * initializeRebaseBackend({
+ *   auth: { jwtSecret: "...", google: { clientId: "..." } },
+ *   database: createPostgresAdapter({ ... }),
+ * });
+ * ```
+ *
+ * @example Custom auth
+ * ```ts
+ * import { createCustomAuthAdapter } from "@rebasepro/server-core";
+ *
+ * initializeRebaseBackend({
+ *   auth: createCustomAuthAdapter({
+ *     verifyRequest: async (req) => { ... },
+ *   }),
+ *   database: createPostgresAdapter({ ... }),
+ * });
+ * ```
+ *
+ * @group Auth
+ */
+
+import type { Hono } from "hono";
+
+// ─── Authenticated User ──────────────────────────────────────────────────────
+
+/**
+ * The normalized user object returned by `AuthAdapter.verifyRequest()`.
+ *
+ * Regardless of the auth provider, every request is resolved to this shape
+ * so that downstream middleware (RLS scoping, route guards) can work uniformly.
+ *
+ * @group Auth
+ */
+export interface AuthenticatedUser {
+    /** Unique user identifier (provider-specific). */
+    uid: string;
+    /** Primary email address. */
+    email: string;
+    /** Human-readable display name. */
+    displayName?: string | null;
+    /** Avatar URL. */
+    photoUrl?: string | null;
+    /** Role identifiers the user holds. */
+    roles: string[];
+    /** Whether the user has admin privileges. */
+    isAdmin: boolean;
+    /** Raw bearer token from the request (for forwarding). */
+    rawToken?: string;
+    /** Extra claims/metadata from the auth provider. */
+    claims?: Record<string, unknown>;
+}
+
+// ─── Capabilities ────────────────────────────────────────────────────────────
+
+/**
+ * Feature flags advertised by an auth adapter.
+ *
+ * The frontend reads these from `GET /api/auth/config` to dynamically
+ * show/hide UI elements (login form, registration, password reset, etc.).
+ *
+ * @group Auth
+ */
+export interface AuthAdapterCapabilities {
+    /**
+     * Whether this adapter mounts its own `/auth/*` routes.
+     *
+     * - `true` for the built-in Rebase auth (login, register, refresh, etc.)
+     * - `false` for external providers like Clerk or Auth0 that handle
+     *   auth flows outside of the Rebase backend.
+     */
+    hasBuiltInAuthRoutes: boolean;
+
+    /** Supports email/password login. */
+    emailPasswordLogin: boolean;
+    /** Supports new user registration. */
+    registration: boolean;
+    /** Supports password reset flow. */
+    passwordReset: boolean;
+    /** Supports session listing/revocation. */
+    sessionManagement: boolean;
+    /** Supports profile updates (display name, photo). */
+    profileUpdate: boolean;
+    /** Supports email verification. */
+    emailVerification: boolean;
+    /** List of enabled OAuth provider IDs (e.g. `["google", "github"]`). */
+    enabledProviders: string[];
+
+    /**
+     * For external auth (Clerk, Auth0, etc.): the URL where the user should
+     * be redirected for login. The Rebase frontend will navigate here instead
+     * of showing its own login form.
+     */
+    externalLoginUrl?: string;
+
+    /**
+     * True when no users exist yet — first-user bootstrap mode.
+     * Only applicable for built-in auth.
+     */
+    needsSetup?: boolean;
+
+    /** Whether new user registration is enabled (may differ from `registration` capability at runtime). */
+    registrationEnabled?: boolean;
+}
+
+// ─── User & Role Management ─────────────────────────────────────────────────
+
+/**
+ * Options for paginated user listing.
+ * @group Auth
+ */
+export interface AuthUserListOptions {
+    limit?: number;
+    offset?: number;
+    search?: string;
+    orderBy?: string;
+    orderDir?: "asc" | "desc";
+    roleId?: string;
+}
+
+/**
+ * Paginated user listing result.
+ * @group Auth
+ */
+export interface AuthUserListResult {
+    users: AuthUserData[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/**
+ * User data exposed by the auth adapter.
+ * @group Auth
+ */
+export interface AuthUserData {
+    id: string;
+    email: string;
+    displayName?: string | null;
+    photoUrl?: string | null;
+    emailVerified?: boolean;
+    metadata?: Record<string, any>;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
+/**
+ * Data for creating a user.
+ * @group Auth
+ */
+export interface AuthCreateUserData {
+    email: string;
+    password?: string;
+    displayName?: string;
+    photoUrl?: string;
+    metadata?: Record<string, any>;
+}
+
+/**
+ * Role data exposed by the auth adapter.
+ * @group Auth
+ */
+export interface AuthRoleData {
+    id: string;
+    name: string;
+    isAdmin: boolean;
+    defaultPermissions?: {
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    } | null;
+    collectionPermissions?: Record<string, {
+        read?: boolean;
+        create?: boolean;
+        edit?: boolean;
+        delete?: boolean;
+    }> | null;
+    config?: Record<string, unknown> | null;
+}
+
+/**
+ * Data for creating a role.
+ * @group Auth
+ */
+export interface AuthCreateRoleData {
+    id: string;
+    name: string;
+    isAdmin?: boolean;
+    defaultPermissions?: AuthRoleData["defaultPermissions"];
+    collectionPermissions?: AuthRoleData["collectionPermissions"];
+    config?: AuthRoleData["config"];
+}
+
+/**
+ * User management operations for the admin panel.
+ *
+ * Optional — if not provided by the adapter, the user management UI is hidden.
+ *
+ * @group Auth
+ */
+export interface UserManagementAdapter {
+    listUsers(options?: AuthUserListOptions): Promise<AuthUserListResult>;
+    getUserById(id: string): Promise<AuthUserData | null>;
+    createUser(data: AuthCreateUserData): Promise<AuthUserData>;
+    updateUser(id: string, data: Partial<AuthCreateUserData>): Promise<AuthUserData | null>;
+    deleteUser(id: string): Promise<void>;
+    getUserRoles(userId: string): Promise<AuthRoleData[]>;
+    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+}
+
+/**
+ * Role management operations for the admin panel.
+ *
+ * Optional — if not provided by the adapter, role management is disabled.
+ *
+ * @group Auth
+ */
+export interface RoleManagementAdapter {
+    listRoles(): Promise<AuthRoleData[]>;
+    getRoleById(id: string): Promise<AuthRoleData | null>;
+    createRole(data: AuthCreateRoleData): Promise<AuthRoleData>;
+    updateRole(id: string, data: Partial<AuthRoleData>): Promise<AuthRoleData | null>;
+    deleteRole(id: string): Promise<void>;
+}
+
+// ─── Auth Adapter ────────────────────────────────────────────────────────────
+
+/**
+ * Pluggable authentication adapter for Rebase.
+ *
+ * This is the **key interface** that decouples authentication from the
+ * database layer. Each auth adapter knows how to:
+ *
+ * 1. Verify incoming HTTP requests (`verifyRequest`)
+ * 2. Optionally manage users and roles (for the admin panel)
+ * 3. Optionally mount auth-specific routes (login, register, etc.)
+ * 4. Advertise its capabilities so the frontend can adapt
+ *
+ * The built-in Rebase auth implements this interface internally.
+ * External providers (Clerk, Auth0, Firebase Auth) provide their own adapters.
+ * Users with custom auth can use `createCustomAuthAdapter()` for a minimal setup.
+ *
+ * @group Auth
+ */
+export interface AuthAdapter {
+    /**
+     * Unique identifier for this auth adapter.
+     *
+     * @example "rebase-builtin", "clerk", "auth0", "firebase", "custom"
+     */
+    readonly id: string;
+
+    // ── Request Authentication ──────────────────────────────────────────
+
+    /**
+     * Verify an incoming request and extract the authenticated user.
+     *
+     * This replaces the hardcoded JWT verification in server-core's middleware.
+     * Each adapter implements its own token verification strategy:
+     * - Built-in: verify Rebase JWT
+     * - Clerk: call Clerk's `verifyToken()`
+     * - Auth0: validate Auth0 JWT with JWKS
+     * - Custom: whatever logic the user provides
+     *
+     * @param request - The raw `Request` object (portable across Hono, Express, Fastify)
+     * @returns The authenticated user, or `null` for unauthenticated requests.
+     *          Throw an error to reject the request with 401.
+     */
+    verifyRequest(request: Request): Promise<AuthenticatedUser | null>;
+
+    /**
+     * Verify a raw bearer token and extract the authenticated user.
+     *
+     * Used for **WebSocket authentication**, where there is no HTTP `Request`
+     * object — only a token string sent over the socket.
+     *
+     * If not implemented, the default behavior synthesizes a minimal `Request`
+     * with an `Authorization: Bearer <token>` header and delegates to
+     * `verifyRequest()`. Adapters should override this if their token
+     * verification logic doesn't depend on request headers/cookies.
+     *
+     * @param token - The raw bearer token string.
+     * @returns The authenticated user, or `null` if the token is invalid.
+     */
+    verifyToken?(token: string): Promise<AuthenticatedUser | null>;
+
+    // ── User & Role Management (for admin panel) ────────────────────────
+
+    /**
+     * User CRUD for the admin panel's user management UI.
+     * Optional — if not provided, user management UI is hidden.
+     */
+    userManagement?: UserManagementAdapter;
+
+    /**
+     * Role CRUD for the admin panel.
+     * Optional — if not provided, role management is disabled.
+     */
+    roleManagement?: RoleManagementAdapter;
+
+    // ── Auth Routes ─────────────────────────────────────────────────────
+
+    /**
+     * Mount adapter-specific auth routes (login, register, refresh, etc.).
+     *
+     * - Built-in adapter: mounts `/auth/login`, `/auth/register`, etc.
+     * - External adapter: typically returns `undefined` (auth is handled externally).
+     * - Custom adapter: user mounts their own routes.
+     *
+     * The return type uses `Hono<any, any, any>` because this sub-app will be
+     * mounted into a parent app via `.route()`, which accepts any Hono env type.
+     * Adapter implementations are free to use their own env (e.g. `Hono<HonoEnv>`).
+     *
+     * @returns A Hono sub-app with auth routes, or `undefined` to skip route mounting.
+     */
+    createAuthRoutes?(): Hono<any, any, any> | undefined;
+
+    /**
+     * Mount admin routes for user/role management.
+     *
+     * Same typing rationale as `createAuthRoutes` — the sub-app env is
+     * unconstrained to support arbitrary adapter implementations.
+     *
+     * @returns A Hono sub-app with admin routes, or `undefined` to skip.
+     */
+    createAdminRoutes?(): Hono<any, any, any> | undefined;
+
+    // ── Feature Detection ───────────────────────────────────────────────
+
+    /**
+     * Advertise what this auth adapter supports.
+     *
+     * The frontend reads this from `GET /api/auth/config` to dynamically
+     * show/hide UI elements. This is the bridge between backend capabilities
+     * and the frontend's `AuthCapabilities` type.
+     */
+    getCapabilities(): AuthAdapterCapabilities | Promise<AuthAdapterCapabilities>;
+
+    // ── Lifecycle ───────────────────────────────────────────────────────
+
+    /**
+     * Called during backend initialization.
+     * Use for running migrations, creating tables, seeding initial data, etc.
+     */
+    initialize?(): Promise<void>;
+
+    /**
+     * Called during graceful shutdown.
+     * Use for closing connections, flushing caches, etc.
+     */
+    destroy?(): Promise<void>;
+
+    // ── Service Key (optional) ──────────────────────────────────────────
+
+    /**
+     * A static secret key for server-to-server / script authentication.
+     *
+     * When set, requests with `Authorization: Bearer <serviceKey>` bypass
+     * normal token verification and are granted admin-level access.
+     */
+    serviceKey?: string;
+}
+
+// ─── Custom Auth Adapter Options ─────────────────────────────────────────────
+
+/**
+ * Options for creating a minimal custom auth adapter via `createCustomAuthAdapter()`.
+ *
+ * This is the simplest way to plug an existing auth system into Rebase.
+ * Only `verifyRequest` is required — everything else is optional.
+ *
+ * @group Auth
+ */
+export interface CustomAuthAdapterOptions {
+    /**
+     * Verify an incoming request and return the authenticated user.
+     * This is the only required method.
+     */
+    verifyRequest: (request: Request) => Promise<AuthenticatedUser | null>;
+
+    /**
+     * Verify a raw bearer token for WebSocket authentication.
+     * Optional — if omitted, a synthetic `Request` is constructed and passed
+     * to `verifyRequest`.
+     */
+    verifyToken?: (token: string) => Promise<AuthenticatedUser | null>;
+
+    /** Optional user management for the admin panel. */
+    userManagement?: UserManagementAdapter;
+
+    /** Optional role management for the admin panel. */
+    roleManagement?: RoleManagementAdapter;
+
+    /** Static service key for server-to-server auth. */
+    serviceKey?: string;
+
+    /** Override default capabilities. */
+    capabilities?: Partial<AuthAdapterCapabilities>;
+}