@rebasepro/server-postgres 0.9.1-canary.ff338b5 → 0.10.1-canary.18115ba

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,7 +4,7 @@
  * 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";
@@ -25,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()`

package/dist/auth/services.d.ts

@@ -1,6 +1,6 @@
 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";
+import { UserRepository, TokenRepository, MfaRepository, AuthRepository, UserData, CreateUserData, RoleData, CreateRoleData, RefreshTokenInfo, RefreshTokenSession, PasswordResetTokenInfo, MagicLinkTokenInfo, UserIdentityData, ListUsersOptions, PaginatedUsersResult, MfaFactor, MfaChallengeInfo, RoleData as Role } from "@rebasepro/server";
 export type { Role };
 export interface AuthSchemaTables {
     users: RebasePgTable;
@@ -23,7 +23,7 @@ export declare class UserService implements UserRepository {
      * 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.user_id` so the `auth.uid() IS NULL` server-escape
+     * 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
@@ -41,8 +41,8 @@ export declare class UserService implements UserRepository {
     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[]>;
@@ -66,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>;
@@ -90,13 +90,42 @@ export declare class UserService implements UserRepository {
 export declare class RefreshTokenService {
     private db;
     private refreshTokensTable;
+    private usersTable;
     constructor(db: NodePgDatabase, tableOrTables?: RebasePgTable | Partial<AuthSchemaTables>);
-    createToken(userId: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void>;
+    /**
+     * Whether the table actually carries a column, so a host application that
+     * supplied its own `refresh_tokens` table — one that predates session
+     * grouping — degrades instead of throwing on every sign-in.
+     */
+    private has;
+    private col;
+    /** The columns to read back, narrowed to the ones this table has. */
+    private selection;
+    createToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void>;
     findByHash(tokenHash: string): Promise<RefreshTokenInfo | null>;
+    /**
+     * Record that a token was rotated away, keeping the row.
+     *
+     * The row is what lets `/auth/refresh` distinguish "you already used this,
+     * here is a fresh one" from "no idea what this is". Deleting it — which is
+     * what this used to do — collapsed both into a 401 and signed the user out
+     * for the crime of losing a response.
+     */
+    markRotated(tokenHash: string): Promise<void>;
+    /** Final kill of one sign-in: logout, or revoking a device remotely. */
+    revokeSession(sessionId: string): Promise<void>;
+    /**
+     * Housekeeping: rotation would otherwise leave a row per refresh forever.
+     * Superseded rows are only needed for as long as a straggler might still
+     * present them, and expired ones are dead weight everywhere.
+     */
+    prune(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
+    getTokensValidAfter(uid: string): Promise<Date | null>;
+    setTokensValidAfter(uid: string, at: Date): Promise<void>;
     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
@@ -109,12 +138,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>;
     /**
@@ -124,7 +153,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
      */
@@ -139,7 +168,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>;
 }
@@ -153,18 +182,23 @@ 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, session?: RefreshTokenSession): Promise<void>;
+    markRefreshTokenRotated(tokenHash: string): Promise<void>;
+    revokeRefreshTokenSession(sessionId: string): Promise<void>;
+    pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
+    getTokensValidAfter(uid: string): Promise<Date | null>;
+    setTokensValidAfter(uid: string, at: Date): 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>;
 }
@@ -182,8 +216,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[]>;
@@ -192,11 +226,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>;
@@ -205,37 +239,42 @@ 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, session?: RefreshTokenSession): Promise<void>;
+    markRefreshTokenRotated(tokenHash: string): Promise<void>;
+    revokeRefreshTokenSession(sessionId: string): Promise<void>;
+    pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void>;
+    getTokensValidAfter(uid: string): Promise<Date | null>;
+    setTokensValidAfter(uid: string, at: Date): 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.
@@ -246,21 +285,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;