@rebasepro/server-postgres 0.0.1-canary.4829d6e

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Rebase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,86 @@
+# @rebasepro/server-postgres
+
+PostgreSQL database driver for Rebase, built on Drizzle ORM.
+
+## Installation
+
+```bash
+pnpm add @rebasepro/server-postgres
+```
+
+## What This Package Does
+
+Implements the Rebase `DatabaseAdapter` / `BackendBootstrapper` interfaces for PostgreSQL. It provides connection pooling, a Drizzle-based data driver, Postgres LISTEN/NOTIFY realtime, auth table management, snapshot history, schema generation, branching, read replicas, and WebSocket support. Plug it into `@rebasepro/server` via `createPostgresAdapter()` or `createPostgresBootstrapper()`.
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `createPostgresAdapter(config)` | Creates a `DatabaseAdapter` for use with `initializeRebaseBackend({ database: ... })`. Recommended API. |
+| `createPostgresBootstrapper(config)` | Lower-level `BackendBootstrapper` factory. Used internally by the adapter. |
+| `createPostgresDatabaseConnection(url, schema?, poolConfig?)` | Creates a production-grade pooled Drizzle connection. Returns `{ db, pool, connectionString }`. |
+| `createDirectDatabaseConnection(url, schema?, poolConfig?)` | Non-pooled connection for LISTEN/NOTIFY and advisory locks (bypasses PgBouncer). |
+| `createReadReplicaConnection(url, schema?, poolConfig?)` | Read-only connection for routing reads to replicas. |
+| `PostgresBackendDriver` | The `DataDriver` implementation — CRUD, filtering, RLS, subcollections, admin SQL. |
+| `RealtimeService` | Postgres LISTEN/NOTIFY-based `RealtimeProvider`. |
+| `DatabasePoolManager` | Per-branch/per-tenant dynamic pool management (used with `ADMIN_CONNECTION_STRING`). |
+| `PostgresCollectionRegistry` | Collection → Drizzle table registry with enum and relation tracking. |
+| `BranchService` | Database branching (schema-level isolation). |
+| `generateDrizzleSchema(collections)` | Generates Drizzle schema code from collection definitions. |
+| `createAuthSchema(schemaName?)` | Generates Drizzle tables for the auth system (`users`, `roles`, `user_roles`). |
+
+## Quick Start
+
+```typescript
+import { createPostgresDatabaseConnection } from "@rebasepro/server-postgres";
+import { createPostgresAdapter } from "@rebasepro/server-postgres";
+import { initializeRebaseBackend } from "@rebasepro/server";
+import * as schema from "./generated/schema";
+
+// Create connection
+const { db, pool } = createPostgresDatabaseConnection(
+  process.env.DATABASE_URL,
+  schema
+);
+
+// Create adapter and pass to server
+const database = createPostgresAdapter({
+  connection: db,
+  connectionString: process.env.DATABASE_URL,
+  schema: { tables: schema },
+});
+
+const backend = await initializeRebaseBackend({
+  app,
+  server,
+  database,
+  collections,
+  auth: { /* ... */ },
+});
+
+// Graceful shutdown
+process.on("SIGTERM", async () => {
+  await backend.shutdown();
+  await pool.end();
+});
+```
+
+## Connection Pool Defaults
+
+| Option | Default |
+|--------|---------|
+| `max` | 20 |
+| `idleTimeoutMillis` | 30,000 |
+| `connectionTimeoutMillis` | 10,000 |
+| `queryTimeout` | 30,000 |
+| `statementTimeout` | 30,000 |
+| `keepAlive` | true |
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| `@rebasepro/server` | Backend orchestrator that consumes this adapter |
+| `@rebasepro/types` | Shared interfaces (`DatabaseAdapter`, `BackendBootstrapper`, `DataDriver`) |
+| `@rebasepro/codegen` | Generates typed SDKs from collections |
+| `@rebasepro/common` | Default collections and shared utilities |

package/dist/PostgresAdapter.d.ts

@@ -0,0 +1,6 @@
+import { DatabaseAdapter } from "@rebasepro/types";
+import type { PostgresDriverConfig } from "./PostgresBootstrapper";
+/**
+ * Creates a Postgres database adapter for Rebase.
+ */
+export declare function createPostgresAdapter(pgConfig: PostgresDriverConfig): DatabaseAdapter;

package/dist/PostgresBackendDriver.d.ts

@@ -0,0 +1,150 @@
+import { DataService } from "./services/dataService";
+import { BranchService } from "./services/BranchService";
+import { RealtimeService } from "./services/realtimeService";
+import { DatabasePoolManager } from "./databasePoolManager";
+import { DrizzleClient } from "./interfaces";
+import { DatabaseAdmin, DataDriver, DeleteProps, CollectionConfig, FetchCollectionProps, FetchOneProps, ListenCollectionProps, ListenOneProps, RebaseClient, RebaseSdkData, RestFetchService, SaveProps, TableMetadata, User } from "@rebasepro/types";
+import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
+import { HistoryService } from "./history/HistoryService";
+export declare class PostgresBackendDriver implements DataDriver {
+    db: DrizzleClient;
+    readonly registry: PostgresCollectionRegistry;
+    poolManager?: DatabasePoolManager | undefined;
+    key: string;
+    initialised: boolean;
+    dataService: DataService;
+    realtimeService: RealtimeService;
+    historyService?: HistoryService;
+    branchService?: BranchService;
+    user?: User;
+    data: RebaseSdkData;
+    client?: RebaseClient;
+    /**
+     * Auto-set to `true` when a SET LOCAL ROLE fails with insufficient
+     * privileges, so subsequent queries skip the doomed attempt.
+     * Mirrors the static `DISABLE_DB_ROLE_SWITCHING` env var but is
+     * learned at runtime.
+     */
+    private _roleSwitchingDisabled;
+    /**
+     * Restricted role that authenticated (user-context) requests run as (via
+     * `SET LOCAL ROLE`) so RLS binds every statement — reads *and* writes. Set
+     * by the bootstrapper after posture detection: defined when the connection
+     * would otherwise bypass RLS (superuser / BYPASSRLS / table owner),
+     * undefined when RLS already applies natively. The base (server-context)
+     * driver never switches — it is the trusted owner plane (auth flows,
+     * migrations, `dataAsAdmin`).
+     */
+    rlsUserRole?: string;
+    /**
+     * When true, realtime notifications are deferred until after the
+     * wrapping transaction commits.  Set by `withAuth` → `withTransaction`.
+     */
+    _deferNotifications: boolean;
+    _pendingNotifications: Array<{
+        path: string;
+        id: string;
+        row: Record<string, unknown> | null;
+        databaseId?: string;
+    }>;
+    constructor(db: DrizzleClient, realtimeService: RealtimeService, registry: PostgresCollectionRegistry, user?: User, poolManager?: DatabasePoolManager | undefined, historyService?: HistoryService);
+    /**
+     * Typed admin capabilities (SQLAdmin + SchemaAdmin + BranchAdmin).
+     * Implemented as a getter so method references are resolved at call-time,
+     * allowing test spies applied after construction to take effect.
+     */
+    get admin(): DatabaseAdmin;
+    /**
+     * REST-optimised fetch service (include-aware eager-loading).
+     * Delegates to the underlying FetchService (include-aware eager loading),
+     * then runs the afterRead pipeline on the results. The raw FetchService does
+     * NOT run callbacks, so masking must be applied here — otherwise every
+     * REST/SDK read leaks unmasked data (see {@link applyAfterReadForRest}).
+     */
+    get restFetchService(): RestFetchService;
+    private buildCallContext;
+    private resolveCollectionCallbacks;
+    /**
+     * Run the three-tier afterRead pipeline (global → collection → property) on a
+     * single row for a collection whose callbacks have already been resolved.
+     */
+    private applyAfterReadToRow;
+    private static hasAfterRead;
+    /**
+     * Apply afterRead to REST/SDK read results.
+     *
+     * The REST / `include` path fetches rows through the raw fetch service, which
+     * does NOT run callbacks — so without this, `afterRead` transforms (e.g. PII
+     * masking) are silently skipped on every SDK/REST read, leaking raw data.
+     * This choke point guarantees afterRead runs there too, matching the driver's
+     * fetchCollection/fetchOne paths.
+     *
+     * It also masks embedded relation data one level deep by running the TARGET
+     * collection's afterRead (so `post.author.email` is masked by the authors
+     * collection, not left raw).
+     */
+    applyAfterReadForRest(rows: Record<string, unknown>[], path: string): Promise<Record<string, unknown>[]>;
+    fetchCollection<M extends Record<string, unknown>>({ path, collection, filter, limit, offset, startAfter, orderBy, searchString, order, vectorSearch }: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
+    listenCollection<M extends Record<string, unknown>>({ path, collection, filter, limit, offset, startAfter, orderBy, searchString, order, onUpdate, onError }: ListenCollectionProps<M>): () => void;
+    fetchOne<M extends Record<string, unknown>>({ path, id, databaseId, collection }: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
+    listenOne<M extends Record<string, unknown>>({ path, id, collection, onUpdate, onError }: ListenOneProps<M>): () => void;
+    save<M extends Record<string, unknown>>({ path, id, values, collection, status }: SaveProps<M>): Promise<Record<string, unknown>>;
+    delete<M extends Record<string, unknown>>({ row, collection }: DeleteProps<M>): Promise<void>;
+    deleteAll(path: string): Promise<void>;
+    checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
+    count<M extends Record<string, unknown>>({ path, collection, filter, searchString }: FetchCollectionProps<M>): Promise<number>;
+    private getTargetDb;
+    executeSql(sqlText: string, options?: {
+        database?: string;
+        role?: string;
+        params?: unknown[];
+    }): Promise<Record<string, unknown>[]>;
+    fetchAvailableDatabases(): Promise<string[]>;
+    fetchAvailableRoles(): Promise<string[]>;
+    fetchCurrentDatabase(): Promise<string | undefined>;
+    /**
+     * Fetch public tables that are not yet mapped to a collection.
+     * Excludes internal tables (_rebase_*, _auth_*, auth tables, etc.)
+     * and junction/connection tables used for many-to-many relations.
+     */
+    fetchUnmappedTables(mappedPaths?: string[]): Promise<string[]>;
+    /**
+     * Fetch metadata for a given table from information_schema (columns, policies, constraints).
+     */
+    fetchTableMetadata(tableName: string): Promise<TableMetadata>;
+    private generateSubscriptionId;
+    /**
+     * Create a new delegate instance with authenticated context.
+     * Starts a transaction and sets the current_user_id and current_user_roles
+     * configuration parameters for PostgreSQL Row Level Security.
+     */
+    withAuth(user: User): Promise<DataDriver>;
+}
+export declare class AuthenticatedPostgresBackendDriver implements DataDriver {
+    delegate: PostgresBackendDriver;
+    key: string;
+    initialised: boolean;
+    user: User;
+    data: RebaseSdkData;
+    constructor(delegate: PostgresBackendDriver, user: User);
+    /**
+     * Typed admin capabilities — delegates to the base driver.
+     */
+    admin: DatabaseAdmin;
+    get restFetchService(): RestFetchService;
+    private withTransaction;
+    fetchCollection<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<Record<string, unknown>[]>;
+    /**
+     * Injects the authenticated user's context into the most recently
+     * registered realtime subscription so RLS-aware polling can apply.
+     */
+    private injectAuthContext;
+    listenCollection<M extends Record<string, unknown>>(props: ListenCollectionProps<M>): () => void;
+    fetchOne<M extends Record<string, unknown>>(props: FetchOneProps<M>): Promise<Record<string, unknown> | undefined>;
+    listenOne<M extends Record<string, unknown>>(props: ListenOneProps<M>): () => void;
+    save<M extends Record<string, unknown>>(props: SaveProps<M>): Promise<Record<string, unknown>>;
+    delete<M extends Record<string, unknown>>(props: DeleteProps<M>): Promise<void>;
+    deleteAll(path: string): Promise<void>;
+    checkUniqueField(path: string, name: string, value: unknown, id?: string, collection?: CollectionConfig): Promise<boolean>;
+    count<M extends Record<string, unknown>>(props: FetchCollectionProps<M>): Promise<number>;
+}

package/dist/PostgresBootstrapper.d.ts

@@ -0,0 +1,51 @@
+/**
+ * PostgresBootstrapper
+ *
+ * Implements the `BackendBootstrapper` interface for PostgreSQL.
+ */
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { BackendBootstrapper } from "@rebasepro/types";
+import { PostgresBackendDriver } from "./PostgresBackendDriver";
+import { RealtimeService } from "./services/realtimeService";
+import { DatabasePoolManager } from "./databasePoolManager";
+import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
+export interface PostgresDriverConfig {
+    connectionString?: string;
+    adminConnectionString?: string;
+    readConnectionString?: string;
+    connection?: unknown;
+    schema?: {
+        tables?: Record<string, unknown>;
+        enums?: Record<string, unknown>;
+        relations?: Record<string, unknown>;
+    };
+    /**
+     * PostgreSQL schema to read when deriving collections from the database
+     * (BaaS mode). Defaults to `public`.
+     */
+    introspectionSchema?: string;
+}
+/**
+ * Opaque internals bag that PostgresBootstrapper stores during `initializeDriver()`
+ * and re-uses in subsequent lifecycle hooks.
+ */
+export interface PostgresDriverInternals {
+    db: NodePgDatabase<any>;
+    readDb?: NodePgDatabase<any>;
+    registry: PostgresCollectionRegistry;
+    realtimeService: RealtimeService;
+    driver: PostgresBackendDriver;
+    poolManager?: DatabasePoolManager;
+}
+/**
+ * Default PostgreSQL bootstrapper.
+ *
+ * Use it to register Postgres with `initializeRebaseBackend()`:
+ * ```typescript
+ * initializeRebaseBackend({
+ *   ...config,
+ *   bootstrappers: [postgresBootstrapper()]
+ * });
+ * ```
+ */
+export declare function createPostgresBootstrapper(pgConfig: PostgresDriverConfig): BackendBootstrapper;

package/dist/auth/ensure-tables.d.ts

@@ -0,0 +1,10 @@
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { CollectionConfig } from "@rebasepro/types";
+/**
+ * Auto-create auth tables if they don't exist.
+ *
+ * @param db         — Drizzle database instance
+ * @param collection — The collection that represents auth users.
+ *                     When omitted, a default `rebase.users` table is created.
+ */
+export declare function ensureAuthTablesExist(db: NodePgDatabase, collection?: CollectionConfig): Promise<void>;

package/dist/auth/services.d.ts

@@ -0,0 +1,250 @@
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { RebasePgTable } from "../types";
+import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RoleData, CreateRoleData, RefreshTokenInfo, PasswordResetTokenInfo, MagicLinkTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, RoleData as Role } from "@rebasepro/server";
+export type { Role };
+export interface AuthSchemaTables {
+    users: RebasePgTable;
+    refreshTokens: RebasePgTable;
+    passwordResetTokens: RebasePgTable;
+    appConfig: RebasePgTable;
+    userIdentities: RebasePgTable;
+}
+/**
+ * PostgreSQL implementation of UserRepository.
+ * Handles all user-related database operations using Drizzle ORM.
+ */
+export declare class UserService implements UserRepository {
+    private db;
+    private usersTable;
+    private userIdentitiesTable;
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
+    private getQualifiedUsersTableName;
+    private mapRowToUser;
+    private mapPayload;
+    createUser(data: CreateUserData): Promise<UserData>;
+    getUserById(id: string): Promise<UserData | null>;
+    getUserByEmail(email: string): Promise<UserData | null>;
+    getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
+    getUserIdentities(userId: string): Promise<UserIdentityData[]>;
+    linkUserIdentity(userId: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
+    deleteUser(id: string): Promise<void>;
+    listUsers(): Promise<UserData[]>;
+    listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
+    /**
+     * Update user's password hash
+     */
+    updatePassword(id: string, passwordHash: string): Promise<void>;
+    /**
+     * Set email verification status
+     */
+    setEmailVerified(id: string, verified: boolean): Promise<void>;
+    /**
+     * Set email verification token
+     */
+    setVerificationToken(id: string, token: string | null): Promise<void>;
+    /**
+     * Find user by email verification token
+     */
+    getUserByVerificationToken(token: string): Promise<UserData | null>;
+    /**
+     * Get roles for a user from database (inline TEXT[] column)
+     */
+    getUserRoles(userId: string): Promise<Role[]>;
+    /**
+     * Get role IDs for a user
+     */
+    getUserRoleIds(userId: string): Promise<string[]>;
+    /**
+     * Set roles for a user (replaces existing roles)
+     */
+    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+    /**
+     * Assign a specific role to new user (appends if not present)
+     */
+    assignDefaultRole(userId: string, roleId: string): Promise<void>;
+    /**
+     * Get user with their roles
+     */
+    getUserWithRoles(userId: string): Promise<{
+        user: UserData;
+        roles: Role[];
+    } | null>;
+}
+export declare class RefreshTokenService {
+    private db;
+    private refreshTokensTable;
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
+    createToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    findByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
+    deleteByHash(tokenHash: string): Promise<void>;
+    deleteAllForUser(userId: string): Promise<void>;
+    listForUser(userId: string): Promise<RefreshTokenInfo[]>;
+    deleteById(id: string, userId: string): Promise<void>;
+}
+/**
+ * Password reset token service
+ */
+export declare class PasswordResetTokenService {
+    private db;
+    private passwordResetTokensTable;
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
+    private getQualifiedPasswordResetTokensTableName;
+    /**
+     * Create a password reset token
+     */
+    createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    /**
+     * Find a valid (not expired, not used) token by hash
+     */
+    findValidByHash(tokenHash: string): Promise<{
+        userId: string;
+        expiresAt: Date;
+    } | null>;
+    /**
+     * Mark token as used
+     */
+    markAsUsed(tokenHash: string): Promise<void>;
+    /**
+     * Delete all tokens for a user
+     */
+    deleteAllForUser(userId: string): Promise<void>;
+    /**
+     * Clean up expired tokens
+     */
+    deleteExpired(): Promise<void>;
+}
+/**
+ * Magic link token service.
+ * Handles magic link token storage for passwordless email login.
+ */
+export declare class MagicLinkTokenService {
+    private db;
+    private magicLinkTokensTable;
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
+    private getQualifiedTableName;
+    createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findValidByHash(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
+    markAsUsed(tokenHash: string): Promise<void>;
+}
+/**
+ * PostgreSQL implementation of TokenRepository.
+ * Combines refresh token and password reset token operations.
+ */
+export declare class PostgresTokenRepository implements TokenRepository {
+    private db;
+    private refreshTokenService;
+    private passwordResetTokenService;
+    private magicLinkTokenService;
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
+    createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
+    deleteRefreshToken(tokenHash: string): Promise<void>;
+    deleteAllRefreshTokensForUser(userId: string): Promise<void>;
+    listRefreshTokensForUser(userId: string): Promise<RefreshTokenInfo[]>;
+    deleteRefreshTokenById(id: string, userId: string): Promise<void>;
+    createPasswordResetToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
+    markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteExpiredTokens(): Promise<void>;
+    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
+    markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
+}
+/**
+ * PostgreSQL implementation of AuthRepository.
+ * Combines user, role, and token repository operations.
+ * This provides a convenient single-class interface for all auth operations.
+ */
+export declare class PostgresAuthRepository implements AuthRepository {
+    private db;
+    private userService;
+    private tokenRepository;
+    constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
+    createUser(data: CreateUserData): Promise<UserData>;
+    getUserById(id: string): Promise<UserData | null>;
+    getUserByEmail(email: string): Promise<UserData | null>;
+    getUserByIdentity(provider: string, providerId: string): Promise<UserData | null>;
+    getUserIdentities(userId: string): Promise<UserIdentityData[]>;
+    linkUserIdentity(userId: string, provider: string, providerId: string, profileData?: Record<string, unknown>): Promise<void>;
+    updateUser(id: string, data: Partial<Omit<CreateUserData, "id">>): Promise<UserData | null>;
+    deleteUser(id: string): Promise<void>;
+    listUsers(): Promise<UserData[]>;
+    listUsersPaginated(options?: ListUsersOptions): Promise<PaginatedUsersResult>;
+    updatePassword(id: string, passwordHash: string): Promise<void>;
+    setEmailVerified(id: string, verified: boolean): Promise<void>;
+    setVerificationToken(id: string, token: string | null): Promise<void>;
+    getUserByVerificationToken(token: string): Promise<UserData | null>;
+    getUserRoles(userId: string): Promise<RoleData[]>;
+    getUserRoleIds(userId: string): Promise<string[]>;
+    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+    assignDefaultRole(userId: string, roleId: string): Promise<void>;
+    getUserWithRoles(userId: string): Promise<{
+        user: UserData;
+        roles: RoleData[];
+    } | null>;
+    getRoleById(id: string): Promise<RoleData | null>;
+    listRoles(): Promise<RoleData[]>;
+    createRole(_data: CreateRoleData): Promise<RoleData>;
+    updateRole(id: string, data: Partial<Omit<RoleData, "id">>): Promise<RoleData | null>;
+    deleteRole(_id: string): Promise<void>;
+    createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
+    deleteRefreshToken(tokenHash: string): Promise<void>;
+    deleteAllRefreshTokensForUser(userId: string): Promise<void>;
+    listRefreshTokensForUser(userId: string): Promise<RefreshTokenInfo[]>;
+    deleteRefreshTokenById(id: string, userId: string): Promise<void>;
+    createPasswordResetToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
+    markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteExpiredTokens(): Promise<void>;
+    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
+    markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
+    private _mfaService;
+    private getMfaService;
+    createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    getMfaFactors(userId: string): Promise<MfaFactor[]>;
+    getMfaFactorById(factorId: string): Promise<(MfaFactor & {
+        secretEncrypted: string;
+    }) | null>;
+    verifyMfaFactor(factorId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
+    getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
+    verifyMfaChallenge(challengeId: string): Promise<void>;
+    createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
+    useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
+    getUnusedRecoveryCodeCount(userId: string): Promise<number>;
+    deleteAllRecoveryCodes(userId: string): Promise<void>;
+    hasVerifiedMfaFactors(userId: string): Promise<boolean>;
+}
+/**
+ * PostgreSQL implementation of MfaRepository.
+ * Handles all MFA-related database operations.
+ */
+export declare class MfaService implements MfaRepository {
+    private db;
+    private schemaName;
+    constructor(db: NodePgDatabase, schemaName?: string);
+    private qualify;
+    createMfaFactor(userId: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    getMfaFactors(userId: string): Promise<MfaFactor[]>;
+    getMfaFactorById(factorId: string): Promise<(MfaFactor & {
+        secretEncrypted: string;
+    }) | null>;
+    verifyMfaFactor(factorId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    createMfaChallenge(factorId: string, ipAddress?: string): Promise<MfaChallengeInfo>;
+    getMfaChallengeById(challengeId: string): Promise<MfaChallengeInfo | null>;
+    verifyMfaChallenge(challengeId: string): Promise<void>;
+    createRecoveryCodes(userId: string, codeHashes: string[]): Promise<void>;
+    useRecoveryCode(userId: string, codeHash: string): Promise<boolean>;
+    getUnusedRecoveryCodeCount(userId: string): Promise<number>;
+    deleteAllRecoveryCodes(userId: string): Promise<void>;
+    hasVerifiedMfaFactors(userId: string): Promise<boolean>;
+}
+/** PostgreSQL user repository implementation */
+export type PostgresUserRepository = UserService;

package/dist/backup/backup-cli.d.ts

@@ -0,0 +1,3 @@
+export declare function backupCommand(rawArgs: string[]): Promise<void>;
+export declare function restoreCommand(rawArgs: string[]): Promise<void>;
+export declare function backupsCommand(rawArgs: string[]): Promise<void>;

package/dist/backup/backup-cron.d.ts

@@ -0,0 +1,53 @@
+import type { CronJobDefinition } from "@rebasepro/types";
+import type { StorageController } from "@rebasepro/server";
+import { BackupDestination } from "./pg-tools";
+export interface BackupCronConfig {
+    /** Cron expression, e.g. `"0 3 * * *"` for 03:00 daily. */
+    schedule: string;
+    /** Postgres connection string. Defaults to `DATABASE_URL`. */
+    connectionString: string;
+    /** Where backups are written: a local path or an `s3://` / `gs://` URL. */
+    destination: BackupDestination;
+    /**
+     * Storage controller used for `s3`/`gcs` destinations. Reuse the one the
+     * backend already configured (S3/GCS/Local StorageController). Not needed
+     * for local destinations.
+     */
+    storage?: StorageController;
+    /** Delete backups older than this many days. `0` disables pruning. */
+    retentionDays?: number;
+    /** Always keep at least this many recent backups regardless of age. */
+    keepMinimum?: number;
+    /** Schemas to exclude from the dump (defaults to Atlas revision schema). */
+    excludeSchemas?: string[];
+    /** Cron job display name. */
+    name?: string;
+    /** Whether the job is enabled. */
+    enabled?: boolean;
+}
+export interface EnvResolution {
+    /** Resolved config, present when a schedule is configured. */
+    config?: Omit<BackupCronConfig, "storage">;
+    /** True when `BACKUP_SCHEDULE` is unset — the cron should be a no-op. */
+    disabled?: boolean;
+    /** Human-readable reason the config could not be built. */
+    error?: string;
+}
+/**
+ * Build backup-cron config purely from environment variables.
+ * Recognised keys:
+ *   - `BACKUP_SCHEDULE`        cron expression (required to enable)
+ *   - `BACKUP_DESTINATION`     local path or `s3://` / `gs://` URL (required)
+ *   - `BACKUP_RETENTION_DAYS`  integer days (optional)
+ *   - `BACKUP_KEEP_MINIMUM`    integer count (optional)
+ *   - `DATABASE_URL`           connection string
+ *
+ * Pure and side-effect free so it can be unit-tested without a database.
+ */
+export declare function backupCronConfigFromEnv(env: Record<string, string | undefined>): EnvResolution;
+/**
+ * Create a {@link CronJobDefinition} that dumps the database, uploads the
+ * result to the configured destination, and prunes old backups. Object
+ * destinations require {@link BackupCronConfig.storage}.
+ */
+export declare function createBackupCron(config: BackupCronConfig): CronJobDefinition;