@rebasepro/server-postgres 0.10.1-canary.31c773c → 0.10.1-canary.6f89f77

package/src/auth/services.ts

@@ -14,6 +14,7 @@ import {
     RoleData,
     CreateRoleData,
     RefreshTokenInfo,
+    RefreshTokenSession,
     PasswordResetTokenInfo,
     MagicLinkTokenInfo,
     UserIdentityData,
@@ -529,6 +530,7 @@ export class UserService implements UserRepository {
 
 export class RefreshTokenService {
     private refreshTokensTable: RebasePgTable;
+    private usersTable: RebasePgTable | null;
 
     constructor(
         private db: NodePgDatabase,
@@ -536,55 +538,159 @@ export class RefreshTokenService {
     ) {
         if (tableOrTables && ((tableOrTables as Partial<AuthSchemaTables>).refreshTokens || (tableOrTables as Partial<AuthSchemaTables>).users)) {
             this.refreshTokensTable = ((tableOrTables as Partial<AuthSchemaTables>).refreshTokens || refreshTokens) as RebasePgTable;
+            this.usersTable = ((tableOrTables as Partial<AuthSchemaTables>).users || users) as RebasePgTable;
         } else {
             this.refreshTokensTable = (tableOrTables as RebasePgTable) || (refreshTokens as unknown as RebasePgTable);
+            this.usersTable = users as unknown as RebasePgTable;
         }
     }
 
-    async createToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void> {
-        // Fallback to empty string because UNIQUE constraints treat NULLs as strictly distinct in standard Postgres.
-        // We want (uid, NULL, NULL) to collide and overwrite, so we map undefined/null to empty strings.
+    /**
+     * 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(column: string): boolean {
+        return Boolean((this.refreshTokensTable as unknown as Record<string, unknown>)[column]);
+    }
+
+    private col(column: string) {
+        return (this.refreshTokensTable as unknown as Record<string, never>)[column];
+    }
+
+    /** The columns to read back, narrowed to the ones this table has. */
+    private selection() {
+        const selection: Record<string, never> = {
+            id: this.refreshTokensTable.id,
+            uid: this.refreshTokensTable.uid,
+            tokenHash: this.refreshTokensTable.tokenHash,
+            expiresAt: this.refreshTokensTable.expiresAt,
+            createdAt: this.refreshTokensTable.createdAt,
+            userAgent: this.refreshTokensTable.userAgent,
+            ipAddress: this.refreshTokensTable.ipAddress
+        } as unknown as Record<string, never>;
+        for (const optional of ["sessionId", "rotatedAt", "revoked", "sessionStartedAt"]) {
+            if (this.has(optional)) selection[optional] = this.col(optional);
+        }
+        return selection;
+    }
+
+    async createToken(
+        uid: string,
+        tokenHash: string,
+        expiresAt: Date,
+        userAgent?: string,
+        ipAddress?: string,
+        session?: RefreshTokenSession
+    ): Promise<void> {
+        // Empty strings rather than NULLs: the device-session UNIQUE constraint
+        // that needed them is gone, but sessions-list UIs already render "" as
+        // "unknown device" and would start showing blanks otherwise.
         const safeUserAgent = userAgent || "";
         const safeIpAddress = ipAddress || "";
 
-        // Atomic upsert keyed on the device session (uid, user_agent, ip_address).
-        // A DELETE-then-INSERT races under concurrent refreshes — cookie-mode boot can
-        // fire two /refresh calls at once (both carrying the same refresh cookie): both
-        // DELETE, then the second INSERT violates `unique_device_session` and 500s.
-        // A single INSERT ... ON CONFLICT DO UPDATE rotates the token atomically.
-        await this.db.insert(this.refreshTokensTable)
-            .values({
-                uid,
-                tokenHash,
-                expiresAt,
-                userAgent: safeUserAgent,
-                ipAddress: safeIpAddress
-            })
-            .onConflictDoUpdate({
-                target: [
-                    this.refreshTokensTable.uid,
-                    this.refreshTokensTable.userAgent,
-                    this.refreshTokensTable.ipAddress
-                ],
-                set: { tokenHash, expiresAt }
-            });
+        // A plain INSERT. Rotation ADDS a token; it does not replace a device's
+        // row. Two refreshes racing on the same session therefore both succeed
+        // and both end holding a usable token, where the previous upsert had
+        // them overwrite each other and logged one of the two tabs out.
+        const values: Record<string, unknown> = {
+            uid,
+            tokenHash,
+            expiresAt,
+            userAgent: safeUserAgent,
+            ipAddress: safeIpAddress
+        };
+        if (session && this.has("sessionId")) values.sessionId = session.id;
+        if (session && this.has("sessionStartedAt")) values.sessionStartedAt = session.startedAt;
+
+        await this.db.insert(this.refreshTokensTable).values(values);
     }
 
     async findByHash(tokenHash: string): Promise<RefreshTokenInfo | null> {
         const [token] = await this.db
-            .select({
-                id: this.refreshTokensTable.id,
-                uid: this.refreshTokensTable.uid,
-                tokenHash: this.refreshTokensTable.tokenHash,
-                expiresAt: this.refreshTokensTable.expiresAt,
-                createdAt: this.refreshTokensTable.createdAt,
-                userAgent: this.refreshTokensTable.userAgent,
-                ipAddress: this.refreshTokensTable.ipAddress
-            })
+            .select(this.selection())
             .from(this.refreshTokensTable)
             .where(eq(this.refreshTokensTable.tokenHash, tokenHash));
 
-        return (token as RefreshTokenInfo) || null;
+        return (token as unknown as 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.
+     */
+    async markRotated(tokenHash: string): Promise<void> {
+        if (!this.has("rotatedAt")) {
+            await this.deleteByHash(tokenHash);
+            return;
+        }
+        await this.db
+            .update(this.refreshTokensTable)
+            .set({ rotatedAt: new Date() })
+            .where(eq(this.refreshTokensTable.tokenHash, tokenHash));
+    }
+
+    /** Final kill of one sign-in: logout, or revoking a device remotely. */
+    async revokeSession(sessionId: string): Promise<void> {
+        if (!this.has("sessionId")) return;
+        if (this.has("revoked")) {
+            await this.db
+                .update(this.refreshTokensTable)
+                .set({ revoked: true, ...(this.has("rotatedAt") ? { rotatedAt: new Date() } : {}) })
+                .where(eq(this.col("sessionId"), sessionId));
+            return;
+        }
+        await this.db.delete(this.refreshTokensTable).where(eq(this.col("sessionId"), sessionId));
+    }
+
+    /**
+     * 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.
+     */
+    async prune(uid: string, sessionId: string, supersededBefore: Date): Promise<void> {
+        const uidCol = this.refreshTokensTable.uid;
+        const expiresCol = this.refreshTokensTable.expiresAt;
+        if (!this.has("rotatedAt") || !this.has("sessionId")) {
+            await this.db.delete(this.refreshTokensTable)
+                .where(sql`${uidCol} = ${uid} AND ${expiresCol} < NOW()`);
+            return;
+        }
+        const rotatedCol = this.col("rotatedAt");
+        const sessionCol = this.col("sessionId");
+        await this.db.delete(this.refreshTokensTable).where(sql`
+            ${uidCol} = ${uid}
+            AND (
+                ${expiresCol} < NOW()
+                OR (
+                    ${sessionCol} = ${sessionId}
+                    AND ${rotatedCol} IS NOT NULL
+                    AND ${rotatedCol} < ${supersededBefore}
+                )
+            )
+        `);
+    }
+
+    async getTokensValidAfter(uid: string): Promise<Date | null> {
+        if (!this.usersTable || !(this.usersTable as unknown as Record<string, unknown>).tokensValidAfter) return null;
+        const [row] = await this.db
+            .select({ tokensValidAfter: (this.usersTable as unknown as Record<string, never>).tokensValidAfter })
+            .from(this.usersTable)
+            .where(eq(this.usersTable.id, uid));
+        const value = (row as { tokensValidAfter?: Date | string | null } | undefined)?.tokensValidAfter;
+        return value ? new Date(value) : null;
+    }
+
+    async setTokensValidAfter(uid: string, at: Date): Promise<void> {
+        if (!this.usersTable || !(this.usersTable as unknown as Record<string, unknown>).tokensValidAfter) return;
+        await this.db
+            .update(this.usersTable)
+            .set({ tokensValidAfter: at })
+            .where(eq(this.usersTable.id, uid));
     }
 
     async deleteByHash(tokenHash: string): Promise<void> {
@@ -597,20 +703,12 @@ export class RefreshTokenService {
 
     async listForUser(uid: string): Promise<RefreshTokenInfo[]> {
         const tokens = await this.db
-            .select({
-                id: this.refreshTokensTable.id,
-                uid: this.refreshTokensTable.uid,
-                tokenHash: this.refreshTokensTable.tokenHash,
-                expiresAt: this.refreshTokensTable.expiresAt,
-                createdAt: this.refreshTokensTable.createdAt,
-                userAgent: this.refreshTokensTable.userAgent,
-                ipAddress: this.refreshTokensTable.ipAddress
-            })
+            .select(this.selection())
             .from(this.refreshTokensTable)
             .where(eq(this.refreshTokensTable.uid, uid))
             .orderBy(this.refreshTokensTable.createdAt);
 
-        return tokens as RefreshTokenInfo[];
+        return tokens as unknown as RefreshTokenInfo[];
     }
 
     async deleteById(id: string, uid: string): Promise<void> {
@@ -804,8 +902,28 @@ export class PostgresTokenRepository implements TokenRepository {
 
     // Refresh token operations
 
-    async createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void> {
-        await this.refreshTokenService.createToken(uid, tokenHash, expiresAt, userAgent, ipAddress);
+    async createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void> {
+        await this.refreshTokenService.createToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session);
+    }
+
+    async markRefreshTokenRotated(tokenHash: string): Promise<void> {
+        await this.refreshTokenService.markRotated(tokenHash);
+    }
+
+    async revokeRefreshTokenSession(sessionId: string): Promise<void> {
+        await this.refreshTokenService.revokeSession(sessionId);
+    }
+
+    async pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void> {
+        await this.refreshTokenService.prune(uid, sessionId, supersededBefore);
+    }
+
+    async getTokensValidAfter(uid: string): Promise<Date | null> {
+        return this.refreshTokenService.getTokensValidAfter(uid);
+    }
+
+    async setTokensValidAfter(uid: string, at: Date): Promise<void> {
+        await this.refreshTokenService.setTokensValidAfter(uid, at);
     }
 
     async findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null> {
@@ -1018,8 +1136,28 @@ collectionPermissions: null }
 
     // Token operations (delegate to PostgresTokenRepository)
 
-    async createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string): Promise<void> {
-        await this.tokenRepository.createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress);
+    async createRefreshToken(uid: string, tokenHash: string, expiresAt: Date, userAgent?: string, ipAddress?: string, session?: RefreshTokenSession): Promise<void> {
+        await this.tokenRepository.createRefreshToken(uid, tokenHash, expiresAt, userAgent, ipAddress, session);
+    }
+
+    async markRefreshTokenRotated(tokenHash: string): Promise<void> {
+        await this.tokenRepository.markRefreshTokenRotated(tokenHash);
+    }
+
+    async revokeRefreshTokenSession(sessionId: string): Promise<void> {
+        await this.tokenRepository.revokeRefreshTokenSession(sessionId);
+    }
+
+    async pruneRefreshTokens(uid: string, sessionId: string, supersededBefore: Date): Promise<void> {
+        await this.tokenRepository.pruneRefreshTokens(uid, sessionId, supersededBefore);
+    }
+
+    async getTokensValidAfter(uid: string): Promise<Date | null> {
+        return this.tokenRepository.getTokensValidAfter(uid);
+    }
+
+    async setTokensValidAfter(uid: string, at: Date): Promise<void> {
+        await this.tokenRepository.setTokensValidAfter(uid, at);
     }
 
     async findRefreshTokenByHash(tokenHash: string): Promise<RefreshTokenInfo | null> {

package/src/backup/backup-cli.ts

@@ -13,19 +13,22 @@ import { logger } from "@rebasepro/server";
 import type { StorageController } from "@rebasepro/server";
 import {
     BackupDestination,
+    globalsFileForDump,
     parseBackupDestination,
     parseDbNameFromUrl,
     resolveConnectionString,
     withDatabaseName
 } from "./pg-tools";
 import {
+    applyGlobals,
     BackupToolError,
     createDump,
     ensureDatabaseExists,
     listBackups,
     preflight,
     restoreDump,
-    uploadBackup
+    uploadBackup,
+    validateDump
 } from "./backup-service";
 
 function formatBytes(bytes: number): string {
@@ -140,8 +143,12 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 noOwner: args["--no-owner"],
                 inheritStdio: true
             });
+            await assertDumpValid(dump.localFile);
             logger.info("");
             logger.info(chalk.green(`  ✓ Backup written to ${dump.localFile} (${formatBytes(dump.sizeBytes)})`));
+            if (dump.globalsFile) {
+                logger.info(chalk.gray(`    ✓ Roles captured to ${dump.globalsFile} (needed so RLS survives a restore).`));
+            }
         } else {
             const storage = await resolveStorageForDestination(dest, process.env);
             const dump = await createDump({
@@ -152,12 +159,20 @@ export async function backupCommand(rawArgs: string[]): Promise<void> {
                 inheritStdio: true
             });
             try {
+                await assertDumpValid(dump.localFile);
                 const uploaded = await uploadBackup(storage!, dump.localFile, dest);
                 logger.info("");
                 logger.info(chalk.green(`  ✓ Backup uploaded to ${uploaded.storageUrl} (${formatBytes(dump.sizeBytes)})`));
+                // Upload the roles sidecar next to the dump so a restore can
+                // recreate roles the dump's GRANT/RLS statements depend on.
+                if (dump.globalsFile && fs.existsSync(dump.globalsFile)) {
+                    const globalsUpload = await uploadBackup(storage!, dump.globalsFile, dest);
+                    logger.info(chalk.gray(`    ✓ Roles uploaded to ${globalsUpload.storageUrl} (needed so RLS survives a restore).`));
+                }
                 logger.info(chalk.gray("    Ensure this bucket is private — backups may contain secrets and PII."));
             } finally {
                 if (fs.existsSync(dump.localFile)) fs.unlinkSync(dump.localFile);
+                if (dump.globalsFile && fs.existsSync(dump.globalsFile)) fs.unlinkSync(dump.globalsFile);
             }
         }
         logger.info("");
@@ -177,6 +192,7 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
             "--create-db": Boolean,
             "--clean": Boolean,
             "--no-owner": Boolean,
+            "--continue-on-error": Boolean,
             "--yes": Boolean,
             "-y": "--yes"
         },
@@ -206,7 +222,11 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
     logger.info("");
 
     // Resolve the local file to restore from (download object-storage keys).
+    // Also resolve the `.globals.sql` roles sidecar so cluster roles can be
+    // recreated before the restore — without them the dump's GRANT/RLS
+    // statements fail and RLS is silently lost.
     let localFile: string;
+    let globalsSql: string | null = null;
     let cleanupTemp = false;
     try {
         if (/^(s3|gs):\/\//.test(backupArg)) {
@@ -221,12 +241,16 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
             localFile = path.join(tmpDir, path.basename(key));
             fs.writeFileSync(localFile, Buffer.from(await file.arrayBuffer()));
             cleanupTemp = true;
+            const globalsObj = await storage.getObject(globalsFileForDump(key), bucket);
+            if (globalsObj) globalsSql = Buffer.from(await globalsObj.arrayBuffer()).toString("utf-8");
         } else {
             localFile = path.resolve(backupArg);
             if (!fs.existsSync(localFile)) {
                 logger.error(chalk.red(`  ✗ Backup file not found: ${localFile}`));
                 process.exit(1);
             }
+            const globalsPath = globalsFileForDump(localFile);
+            if (fs.existsSync(globalsPath)) globalsSql = fs.readFileSync(globalsPath, "utf-8");
         }
 
         // Version pre-flight. Check against the base connection — the server
@@ -261,11 +285,29 @@ export async function restoreCommand(rawArgs: string[]): Promise<void> {
             }
         }
 
+        // Recreate cluster roles before restoring so GRANT/RLS statements in
+        // the dump apply. Best-effort and idempotent (see applyGlobals).
+        if (globalsSql) {
+            logger.info(chalk.gray("  Recreating cluster roles from the backup's roles sidecar…"));
+            const { applied, skipped } = await applyGlobals(
+                targetConnection,
+                globalsSql,
+                (m) => logger.info(chalk.gray(m))
+            );
+            logger.info(chalk.gray(`  ✓ Roles: ${applied} applied, ${skipped} skipped (already present or not permitted).`));
+        } else {
+            logger.warn(chalk.yellow("  ⚠️  No roles sidecar (.globals.sql) accompanies this backup."));
+            logger.warn(chalk.yellow("     If the dump grants to roles that don't exist (e.g. rebase_user), the restore"));
+            logger.warn(chalk.yellow("     will fail — recreate those roles first, or use a backup that includes its globals."));
+        }
+
         await restoreDump({
             connectionString: targetConnection,
             inputFile: localFile,
             clean: args["--clean"],
             noOwner: args["--no-owner"],
+            // Fail loudly by default so a skipped GRANT never leaves RLS off.
+            exitOnError: !args["--continue-on-error"],
             inheritStdio: true
         });
 
@@ -322,6 +364,17 @@ export async function backupsCommand(rawArgs: string[]): Promise<void> {
     }
 }
 
+/** Verify a freshly written dump; abort the command if it looks corrupt. */
+async function assertDumpValid(localFile: string): Promise<void> {
+    const check = await validateDump(localFile);
+    if (!check.ok) {
+        throw new BackupToolError(
+            `The backup failed validation and was not trusted: ${check.reason}`,
+            "The dump may be corrupt or truncated. Investigate before relying on it."
+        );
+    }
+}
+
 function reportError(err: unknown): void {
     if (err instanceof BackupToolError) {
         logger.error(chalk.red(`  ✗ ${err.message}`));
@@ -364,12 +417,18 @@ ${chalk.green.bold("Options")}
   ${chalk.blue("--create-db")}             Create the target database first if it doesn't exist
   ${chalk.blue("--clean")}                 Drop existing objects before recreating them
   ${chalk.blue("--no-owner")}              Ignore ownership from the dump
+  ${chalk.blue("--continue-on-error")}     Log and continue past errors ${chalk.red("(may leave RLS un-enforced!)")}
   ${chalk.blue("--yes, -y")}               Skip the interactive confirmation ${chalk.red("(destructive!)")}
 
 ${chalk.red.bold("Warning")}
   Restore is destructive and never runs automatically. Without --yes it
   requires an interactive 'yes'. Prefer --create-db/--target-db to restore
   into a fresh database rather than overwriting a live one.
+
+  By default the restore aborts on the first error (--exit-on-error) so a
+  skipped GRANT never silently leaves RLS un-enforced. Roles are recreated
+  from the backup's .globals.sql sidecar first; keep that file next to the
+  dump. Use --continue-on-error only when you understand the consequences.
 `);
 }
 

package/src/backup/backup-cron.ts

@@ -125,7 +125,7 @@ export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
         // Backups of a large database can take a while; allow up to an hour.
         timeoutSeconds: 3600,
         async handler({ log }) {
-            const { createDump, pruneBackups, uploadBackup } = await import("./backup-service");
+            const { createDump, pruneBackups, uploadBackup, validateDump } = await import("./backup-service");
             const { destination } = config;
 
             if (destination.kind !== "local" && !config.storage) {
@@ -145,12 +145,32 @@ export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
             });
             log(`Dump created: ${dump.fileName} (${formatBytes(dump.sizeBytes)})`);
 
+            // Validate BEFORE pruning: a corrupt-but-exit-0 dump must never be
+            // the reason the last good backup gets deleted.
+            const check = await validateDump(dump.localFile);
+            if (!check.ok) {
+                // Clean up the bad temp file for object destinations.
+                if (destination.kind !== "local" && fs.existsSync(dump.localFile)) {
+                    fs.unlinkSync(dump.localFile);
+                }
+                if (dump.globalsFile && destination.kind !== "local" && fs.existsSync(dump.globalsFile)) {
+                    fs.unlinkSync(dump.globalsFile);
+                }
+                throw new Error(`New backup failed validation — skipping upload and pruning to protect existing backups. ${check.reason}`);
+            }
+
             let storedKey = dump.localFile;
             try {
                 if (destination.kind !== "local") {
                     const uploaded = await uploadBackup(config.storage!, dump.localFile, destination);
                     storedKey = uploaded.storageUrl;
                     log(`Uploaded to ${uploaded.storageUrl}`);
+                    // Upload the roles sidecar so a restore can recreate the
+                    // roles the dump's GRANT/RLS statements depend on.
+                    if (dump.globalsFile && fs.existsSync(dump.globalsFile)) {
+                        const g = await uploadBackup(config.storage!, dump.globalsFile, destination);
+                        log(`Uploaded roles sidecar to ${g.storageUrl}`);
+                    }
                 }
             } finally {
                 // For object-storage destinations the local dump was a temp
@@ -158,6 +178,9 @@ export function createBackupCron(config: BackupCronConfig): CronJobDefinition {
                 if (destination.kind !== "local" && fs.existsSync(dump.localFile)) {
                     fs.unlinkSync(dump.localFile);
                 }
+                if (dump.globalsFile && destination.kind !== "local" && fs.existsSync(dump.globalsFile)) {
+                    fs.unlinkSync(dump.globalsFile);
+                }
             }
 
             let pruned: string[] = [];

package/src/backup/backup-logic.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure-ish orchestration for the backup/restore paths, kept free of `execa`
+ * and `pg` value imports so it can be unit-tested under jest (the impure
+ * edges — spawning processes, opening connections — live in
+ * `backup-service.ts`, which is vitest/runtime only).
+ *
+ * The functions here take their side-effecting dependency as an argument
+ * (a statement runner, an object deleter) so tests can inject fakes.
+ */
+import { globalsFileForDump, splitGlobalsStatements } from "./pg-tools";
+
+/**
+ * Replay a `pg_dumpall --globals-only` script one statement at a time,
+ * tolerating per-statement failures. On a same-cluster restore the roles
+ * usually already exist (`CREATE ROLE` → "already exists") and on a managed
+ * provider an `ALTER ROLE <superuser>` may be refused; neither should abort
+ * recreation of the roles that *are* missing. Returns how many statements
+ * applied vs were skipped.
+ *
+ * `runStatement` executes one SQL statement and rejects on error.
+ */
+export async function applyGlobalsWith(
+    runStatement: (sql: string) => Promise<void>,
+    globalsSql: string,
+    log: (message: string) => void = () => {}
+): Promise<{ applied: number; skipped: number }> {
+    let applied = 0;
+    let skipped = 0;
+    for (const statement of splitGlobalsStatements(globalsSql)) {
+        try {
+            await runStatement(statement);
+            applied++;
+        } catch (err) {
+            skipped++;
+            const firstLine = statement.split("\n")[0].slice(0, 80);
+            log(`  • Skipped global: ${firstLine} (${err instanceof Error ? err.message : String(err)})`);
+        }
+    }
+    return { applied, skipped };
+}
+
+/**
+ * Delete each pruned dump together with its `.globals.sql` roles sidecar, so
+ * pruning never orphans the roles file. The sidecar is best-effort — older
+ * backups predate it, so a missing-sidecar failure is swallowed while a
+ * failure deleting the dump itself propagates.
+ *
+ * `deleteObject` removes one key and rejects if it cannot (e.g. not found).
+ */
+export async function pruneWith(
+    keys: string[],
+    deleteObject: (key: string) => Promise<void>
+): Promise<void> {
+    for (const key of keys) {
+        await deleteObject(key);
+        try {
+            await deleteObject(globalsFileForDump(key));
+        } catch {
+            // Sidecar may not exist for older backups — ignore.
+        }
+    }
+}