@rebasepro/server-postgres 0.9.1-canary.a57c262 → 0.9.1-canary.a8dbf1c

package/README.md

@@ -76,6 +76,27 @@ process.on("SIGTERM", async () => {
 | `statementTimeout` | 30,000 |
 | `keepAlive` | true |
 
+## Testing
+
+This package runs **two test runners**, split by directory. This is deliberate — check which half you are in before running anything.
+
+| Tests | Runner | Config | Command |
+|-------|--------|--------|---------|
+| `test/*.ts` (unit) | jest | [`jest.config.cjs`](./jest.config.cjs) | `pnpm test` |
+| `test/e2e/**` (integration) | vitest | [`vitest.e2e.config.ts`](./vitest.e2e.config.ts) | `pnpm test:e2e` |
+
+The unit tests use jest's injected globals (`describe`/`it`/`expect`) and `jest.mock`. The e2e tests import explicitly from `vitest` and need Docker (testcontainers spins up a real Postgres).
+
+**Running a single unit test:**
+
+```bash
+npx jest test/auth-services.test.ts
+```
+
+Pointing `vitest` at a unit test is the easy mistake here — it produces a bare `ReferenceError: jest is not defined` and a "no tests" result, which looks exactly like a dead or broken test file rather than the wrong runner. [`vitest.config.ts`](./vitest.config.ts) exists solely to intercept that and print the command you actually wanted.
+
+`pnpm test` runs jest **without** `--passWithNoTests`: if the unit suite ever stops being collected, CI fails instead of going quietly green.
+
 ## Related Packages
 
 | Package | Role |

package/dist/PostgresBackendDriver.d.ts

@@ -114,6 +114,24 @@ export declare class PostgresBackendDriver implements DataDriver {
     }): Promise<Record<string, unknown>[]>;
     fetchAvailableDatabases(): Promise<string[]>;
     fetchAvailableRoles(): Promise<string[]>;
+    /**
+     * Application-level roles actually in use in this project.
+     *
+     * Distinct from {@link fetchAvailableRoles}, which returns native
+     * PostgreSQL roles from `pg_roles` (`postgres`, `rebase_user`, …). Those
+     * are the roles the SQL editor can `SET ROLE` to. *These* are the strings
+     * held in the users table's `roles` column, injected per-transaction as
+     * `auth.roles()` and matched by `SecurityRule.roles`. Feeding the pg roles
+     * into a `SecurityRule.roles` field produces a condition no user can ever
+     * satisfy, so the two must not be conflated.
+     *
+     * Roles have no registry table — they were migrated out of
+     * `rebase.user_roles` onto an inline `roles TEXT[]` column — so the live
+     * set is derived from what is assigned. A role that is declared in a policy
+     * but held by nobody yet cannot be discovered here; callers that need it
+     * should union in the roles they already know about.
+     */
+    fetchApplicationRoles(): Promise<string[]>;
     fetchCurrentDatabase(): Promise<string | undefined>;
     /**
      * Fetch public tables that are not yet mapped to a collection.

package/dist/PostgresBootstrapper.d.ts

@@ -4,11 +4,12 @@
  * Implements the `BackendBootstrapper` interface for PostgreSQL.
  */
 import { NodePgDatabase } from "drizzle-orm/node-postgres";
-import { BackendBootstrapper } from "@rebasepro/types";
+import { BackendBootstrapper, type RealtimeChannelsConfig } from "@rebasepro/types";
 import { PostgresBackendDriver } from "./PostgresBackendDriver";
 import { RealtimeService } from "./services/realtimeService";
 import { DatabasePoolManager } from "./databasePoolManager";
 import { PostgresCollectionRegistry } from "./collections/PostgresCollectionRegistry";
+import { type CdcTableRef } from "./services/cdc/trigger-cdc";
 export interface PostgresDriverConfig {
     connectionString?: string;
     adminConnectionString?: string;
@@ -24,6 +25,12 @@ export interface PostgresDriverConfig {
      * (BaaS mode). Defaults to `public`.
      */
     introspectionSchema?: string;
+    /**
+     * Realtime options. Currently only channel retention, which is opt-in:
+     * without rules here no channel keeps any history and broadcast stays
+     * fire-and-forget. See {@link ChannelRetentionRule}.
+     */
+    realtime?: RealtimeChannelsConfig;
 }
 /**
  * Opaque internals bag that PostgresBootstrapper stores during `initializeDriver()`
@@ -36,6 +43,15 @@ export interface PostgresDriverInternals {
     realtimeService: RealtimeService;
     driver: PostgresBackendDriver;
     poolManager?: DatabasePoolManager;
+    /**
+     * Attach CDC triggers to tables that did not exist when the driver
+     * bootstrapped. Only set when database-level capture is actually active.
+     *
+     * Auth owns its own tables and creates them later in boot, so at driver
+     * bootstrap they are legitimately missing and get skipped; without this
+     * they would stay uninstrumented until the next restart.
+     */
+    provisionCdcForTables?: (tables: CdcTableRef[]) => Promise<void>;
 }
 /**
  * Default PostgreSQL bootstrapper.

package/dist/auth/services.d.ts

@@ -19,14 +19,30 @@ export declare class UserService implements UserRepository {
     private userIdentitiesTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedUsersTableName;
+    /**
+     * Run a privileged auth write with an explicitly cleared RLS context.
+     *
+     * The auth services run on the base/owner connection, which by design
+     * carries a NULL `app.uid` so the `auth.uid() IS NULL` server-escape
+     * in the default policies applies. That NULL is normally guaranteed by
+     * `set_config(..., is_local = true)` resetting at transaction end — but a
+     * GUC that survives on a pooled connection (or a connection role that
+     * doesn't bypass RLS: FORCE ROW LEVEL SECURITY, or a non-owner role)
+     * turns the trusted write into an RLS-scoped one and denies it with
+     * SQLSTATE 42501. Clearing the GUCs here, transaction-locally at the
+     * single chokepoint, makes the server context deterministic instead of
+     * trusting whatever state the pool hands us. `auth.uid()` reads '' as
+     * NULL via NULLIF, so '' is the server context.
+     */
+    private withServerContext;
     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>;
+    getUserIdentities(uid: string): Promise<UserIdentityData[]>;
+    linkUserIdentity(uid: 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[]>;
@@ -50,23 +66,23 @@ export declare class UserService implements UserRepository {
     /**
      * Get roles for a user from database (inline TEXT[] column)
      */
-    getUserRoles(userId: string): Promise<Role[]>;
+    getUserRoles(uid: string): Promise<Role[]>;
     /**
      * Get role IDs for a user
      */
-    getUserRoleIds(userId: string): Promise<string[]>;
+    getUserRoleIds(uid: string): Promise<string[]>;
     /**
      * Set roles for a user (replaces existing roles)
      */
-    setUserRoles(userId: string, roleIds: string[]): Promise<void>;
+    setUserRoles(uid: string, roleIds: string[]): Promise<void>;
     /**
      * Assign a specific role to new user (appends if not present)
      */
-    assignDefaultRole(userId: string, roleId: string): Promise<void>;
+    assignDefaultRole(uid: string, roleId: string): Promise<void>;
     /**
      * Get user with their roles
      */
-    getUserWithRoles(userId: string): Promise<{
+    getUserWithRoles(uid: string): Promise<{
         user: UserData;
         roles: Role[];
     } | null>;
@@ -75,12 +91,12 @@ 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>;
+    createToken(uid: 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>;
+    deleteAllForUser(uid: string): Promise<void>;
+    listForUser(uid: string): Promise<RefreshTokenInfo[]>;
+    deleteById(id: string, uid: string): Promise<void>;
 }
 /**
  * Password reset token service
@@ -93,12 +109,12 @@ export declare class PasswordResetTokenService {
     /**
      * Create a password reset token
      */
-    createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     /**
      * Find a valid (not expired, not used) token by hash
      */
     findValidByHash(tokenHash: string): Promise<{
-        userId: string;
+        uid: string;
         expiresAt: Date;
     } | null>;
     /**
@@ -108,7 +124,7 @@ export declare class PasswordResetTokenService {
     /**
      * Delete all tokens for a user
      */
-    deleteAllForUser(userId: string): Promise<void>;
+    deleteAllForUser(uid: string): Promise<void>;
     /**
      * Clean up expired tokens
      */
@@ -123,7 +139,7 @@ export declare class MagicLinkTokenService {
     private magicLinkTokensTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
     private getQualifiedTableName;
-    createToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidByHash(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
     markAsUsed(tokenHash: string): Promise<void>;
 }
@@ -137,18 +153,18 @@ export declare class PostgresTokenRepository implements TokenRepository {
     private passwordResetTokenService;
     private magicLinkTokenService;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
-    createRefreshToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    createRefreshToken(uid: 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>;
+    deleteAllRefreshTokensForUser(uid: string): Promise<void>;
+    listRefreshTokensForUser(uid: string): Promise<RefreshTokenInfo[]>;
+    deleteRefreshTokenById(id: string, uid: string): Promise<void>;
+    createPasswordResetToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
     markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
-    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     deleteExpiredTokens(): Promise<void>;
-    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createMagicLinkToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidMagicLinkToken(tokenHash: string): Promise<MagicLinkTokenInfo | null>;
     markMagicLinkTokenUsed(tokenHash: string): Promise<void>;
 }
@@ -166,8 +182,8 @@ export declare class PostgresAuthRepository implements AuthRepository {
     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>;
+    getUserIdentities(uid: string): Promise<UserIdentityData[]>;
+    linkUserIdentity(uid: 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[]>;
@@ -176,11 +192,11 @@ export declare class PostgresAuthRepository implements AuthRepository {
     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<{
+    getUserRoles(uid: string): Promise<RoleData[]>;
+    getUserRoleIds(uid: string): Promise<string[]>;
+    setUserRoles(uid: string, roleIds: string[]): Promise<void>;
+    assignDefaultRole(uid: string, roleId: string): Promise<void>;
+    getUserWithRoles(uid: string): Promise<{
         user: UserData;
         roles: RoleData[];
     } | null>;
@@ -189,37 +205,37 @@ export declare class PostgresAuthRepository implements AuthRepository {
     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>;
+    createRefreshToken(uid: 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>;
+    deleteAllRefreshTokensForUser(uid: string): Promise<void>;
+    listRefreshTokensForUser(uid: string): Promise<RefreshTokenInfo[]>;
+    deleteRefreshTokenById(id: string, uid: string): Promise<void>;
+    createPasswordResetToken(uid: string, tokenHash: string, expiresAt: Date): Promise<void>;
     findValidPasswordResetToken(tokenHash: string): Promise<PasswordResetTokenInfo | null>;
     markPasswordResetTokenUsed(tokenHash: string): Promise<void>;
-    deleteAllPasswordResetTokensForUser(userId: string): Promise<void>;
+    deleteAllPasswordResetTokensForUser(uid: string): Promise<void>;
     deleteExpiredTokens(): Promise<void>;
-    createMagicLinkToken(userId: string, tokenHash: string, expiresAt: Date): Promise<void>;
+    createMagicLinkToken(uid: 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[]>;
+    createMfaFactor(uid: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    getMfaFactors(uid: string): Promise<MfaFactor[]>;
     getMfaFactorById(factorId: string): Promise<(MfaFactor & {
         secretEncrypted: string;
     }) | null>;
     verifyMfaFactor(factorId: string): Promise<void>;
-    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, uid: 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>;
+    createRecoveryCodes(uid: string, codeHashes: string[]): Promise<void>;
+    useRecoveryCode(uid: string, codeHash: string): Promise<boolean>;
+    getUnusedRecoveryCodeCount(uid: string): Promise<number>;
+    deleteAllRecoveryCodes(uid: string): Promise<void>;
+    hasVerifiedMfaFactors(uid: string): Promise<boolean>;
 }
 /**
  * PostgreSQL implementation of MfaRepository.
@@ -230,21 +246,21 @@ export declare class MfaService implements MfaRepository {
     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[]>;
+    createMfaFactor(uid: string, factorType: "totp", secretEncrypted: string, friendlyName?: string): Promise<MfaFactor>;
+    getMfaFactors(uid: string): Promise<MfaFactor[]>;
     getMfaFactorById(factorId: string): Promise<(MfaFactor & {
         secretEncrypted: string;
     }) | null>;
     verifyMfaFactor(factorId: string): Promise<void>;
-    deleteMfaFactor(factorId: string, userId: string): Promise<void>;
+    deleteMfaFactor(factorId: string, uid: 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>;
+    createRecoveryCodes(uid: string, codeHashes: string[]): Promise<void>;
+    useRecoveryCode(uid: string, codeHash: string): Promise<boolean>;
+    getUnusedRecoveryCodeCount(uid: string): Promise<number>;
+    deleteAllRecoveryCodes(uid: string): Promise<void>;
+    hasVerifiedMfaFactors(uid: string): Promise<boolean>;
 }
 /** PostgreSQL user repository implementation */
 export type PostgresUserRepository = UserService;

package/dist/connection.d.ts

@@ -19,6 +19,27 @@ export interface PostgresPoolConfig {
     /** Enable TCP keep-alive (default: true) */
     keepAlive?: boolean;
 }
+/**
+ * Destroy pool clients that are released while still inside a transaction.
+ *
+ * pg-pool returns a client to the idle list whenever `release()` is called
+ * without an error — even if the connection is still mid-transaction (status
+ * `T`/`E`). That happens in practice: drizzle's pool transaction releases in
+ * a `finally` after attempting ROLLBACK, and if the ROLLBACK itself fails
+ * (e.g. it was queued behind a statement that hit the client-side
+ * query_timeout), the client goes back dirty. The next checkout then runs
+ * its statements inside the zombie transaction — with the previous request's
+ * `app.*` RLS GUCs still applied, which turns unrelated queries into
+ * RLS-scoped ones (observed in production as registration failing with
+ * SQLSTATE 42501 under a leaked anonymous context).
+ *
+ * pg-pool emits `release` before it consults its private `_expired` set, so
+ * marking the client expired here makes `_release()` destroy it instead of
+ * pooling it. Both `client._txStatus` (pg ≥ 8.16) and `pool._expired` are
+ * private APIs — feature-detect and fall back to loud logging so an upstream
+ * change degrades to observability, never to silent corruption.
+ */
+export declare function guardPoolAgainstDirtyRelease(pool: Pool, label: string): void;
 /**
  * Create a Drizzle-backed Postgres connection with a production-grade
  * connection pool.