@marinoscar/platform-api 0.1.0-next.3 → 0.1.0-next.5

package/dist/db-backup/db-backup.module.js

@@ -0,0 +1,401 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var DbBackupModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbBackupModule = void 0;
+const common_1 = require("@nestjs/common");
+const index_1 = require("../storage/index");
+const backup_target_1 = require("./backup-target");
+const db_backup_events_1 = require("./db-backup-events");
+const carry_over_registry_1 = require("./carry-over.registry");
+const db_backup_key_prefix_1 = require("./db-backup-key-prefix");
+const db_backup_storage_1 = require("./db-backup-storage");
+const options_1 = require("./options");
+const restore_gate_1 = require("./restore-gate");
+const database_restore_service_1 = require("./database-restore.service");
+const db_backup_admin_service_1 = require("./db-backup-admin.service");
+const db_backup_retention_service_1 = require("./db-backup-retention.service");
+const db_backup_runner_service_1 = require("./db-backup-runner.service");
+const db_backup_controller_1 = require("./db-backup.controller");
+const db_backup_run_handler_1 = require("./handlers/db-backup-run.handler");
+const db_backup_sweep_handler_1 = require("./handlers/db-backup-sweep.handler");
+const db_restore_old_db_drop_handler_1 = require("./handlers/db-restore-old-db-drop.handler");
+const db_restore_run_handler_1 = require("./handlers/db-restore-run.handler");
+const pg_job_role_broker_1 = require("./pg-job-role.broker");
+const restore_preflight_service_1 = require("./restore-preflight.service");
+const db_backup_schedule_task_1 = require("./tasks/db-backup-schedule.task");
+const backup_pg_client_doctor_check_1 = require("./doctor/backup-pg-client.doctor-check");
+const backup_rls_doctor_check_1 = require("./doctor/backup-rls.doctor-check");
+const backup_schedule_doctor_check_1 = require("./doctor/backup-schedule.doctor-check");
+const backup_mirrors_doctor_check_1 = require("./doctor/backup-mirrors.doctor-check");
+// =============================================================================
+// DbBackupModule (issues #281, #282, #283 and #284, epic #254)
+// =============================================================================
+//
+// The backup engine and nothing else. #280 shipped the pure utilities this
+// wraps (`pg-dump.util.ts`, `pg-restore.util.ts`, `pg-version.util.ts`,
+// `schedule.util.ts`) as free functions with no module of their own, because
+// none of them needed injection; `DatabaseBackupRunnerService` is the first
+// thing here that does — it needs Prisma, the system settings and the active
+// storage provider.
+//
+// Registered in `app.module.ts` for the same reason `JobsModule` was
+// registered before anything enqueued: a broken provider graph fails at boot,
+// where it is one line in a startup log, rather than at 02:00 on the first
+// night backups were switched on.
+//
+// #282 added the caller the engine was missing. `DatabaseBackupScheduleTask`
+// is a `@Cron` provider — `ScheduleModule.forRoot()` in `app.module.ts` is
+// what makes it fire, exactly as it does for `JobStuckResetTask` in
+// `JobsModule` and `NodeStaleOfflineTask` in `NodesModule` — so from here on
+// this module DOES start a timer at boot. It still issues no query until a
+// tick runs, and the tick is gated by `DB_BACKUP_SCHEDULE_ENABLED`.
+//
+// `DatabaseBackupRetentionService` is a plain provider, and it is deliberately
+// NOT a second `@Cron`. Pruning happens only after a backup has been taken and
+// verified (see the runner's success path), so a timer of its own would be a
+// second, unsynchronised deleter of archives with no new backup to justify
+// what it removes.
+//
+// -----------------------------------------------------------------------------
+// WHAT IT IMPORTS, AND WHY EACH
+// -----------------------------------------------------------------------------
+//
+// `SettingsModule` for `SystemSettingsService.getDatabaseBackupPolicy()` — the
+// compression level, the stale window and the storage-provider name. The
+// direction is acyclic: settings depends on nothing here. `JobsModule` and
+// `NotificationsModule` import it for exactly the same kind of narrow read.
+//
+// ⚠ `StorageProvidersModule` AND NOT `StorageModule`, deliberately, and this
+// is the same choice `JobsModule` and `NodesModule` already made. The provider
+// module contributes ONE token (`STORAGE_PROVIDER`) and no controllers;
+// `StorageModule` would pull `ObjectsController`, `ObjectsService` and the
+// upload-processing pipeline into this graph, and would make the backup engine
+// depend on the interactive storage API rather than on the ability to write
+// bytes. It would also invite the genuinely wrong design underneath that
+// dependency: recording each backup as a `storage_objects` row, which would
+// give every archive a user-facing object an administrator could delete by
+// hand, outside the retention policy that is supposed to own its lifetime.
+//
+// `PrismaService` is not imported: `PrismaModule` is `@Global()`.
+//
+// -----------------------------------------------------------------------------
+// WHAT IS NOT PROVIDED, ON PURPOSE
+// -----------------------------------------------------------------------------
+//
+// `DB_BACKUP_ENGINE` and `DB_BACKUP_TIMERS` are OPTIONAL tokens that this
+// module deliberately leaves unbound, exactly as `JobsModule` leaves
+// `JOB_CLOCK` and `JOB_RANDOM` unbound. The service falls back to the real
+// `pg_dump` and the real timers when they resolve to nothing, so an
+// application always runs on real binaries and real time, and only a test that
+// constructs the service directly can substitute either. Providing them here
+// would create a seam a fork could fill by accident — a stubbed dump engine in
+// production is a backup subsystem that reports success and stores nothing.
+//
+// `DatabaseBackupRunnerService` IS exported: #282's scheduler and #283's admin
+// controller both drive it, and both must go through THE SAME claim — the
+// single-active-run index is only a guarantee if there is one writer of this
+// table. `DatabaseBackupRetentionService` is exported for the same reason in
+// the other direction: #283's admin surface needs to be able to report and
+// re-run retention, and a second implementation of "which archives may be
+// deleted" is the kind of duplicate that ends with two rules disagreeing about
+// a `pre_restore` dump.
+//
+// `DatabaseBackupScheduleTask` is a provider and NOT exported: nothing outside
+// this module should be reaching into a cron handler, and the two operations
+// it owns are already reachable through the services it composes.
+//
+// -----------------------------------------------------------------------------
+// #283 ADDS THE ADMIN SURFACE, AND IT IS A THIRD SERVICE RATHER THAN A FOURTH
+// METHOD ON THE RUNNER
+// -----------------------------------------------------------------------------
+//
+// `DatabaseBackupController` binds to `DatabaseBackupAdminService`, which reads
+// the run table, projects the schedule, writes the policy through
+// `SystemSettingsService` and DELEGATES the two dangerous operations — claiming
+// a run and cancelling one — to the runner. Splitting it out follows the
+// precedent `JobAdminService` set beside `JobsService`: what is split is the
+// WORK, not the surface. The runner exists to spawn a child process and stream
+// its output into a bucket under a set of guarantees its header spends 150
+// lines stating; an admin service exists to page through rows and turn typed
+// failures into status codes. Folding the second into the first would put HTTP
+// concerns inside the file that must stay legible as a streaming contract, and
+// would give a cron-driven engine a reason to import `@nestjs/common`'s
+// exceptions.
+//
+// The admin service is a PROVIDER AND NOT EXPORTED: it is the controller's,
+// and anything else that needs to start a backup must go through the runner,
+// which is the one writer of this table.
+//
+// `DatabaseBackupAdminService` injects `STORAGE_PROVIDER` directly, exactly as
+// the runner and the retention sweep do, so the `StorageProvidersModule` import
+// above now serves three consumers rather than two.
+//
+// -----------------------------------------------------------------------------
+// #284 ADDS RESTORE PRE-FLIGHT, AND IT ADDS NO ROUTE
+// -----------------------------------------------------------------------------
+//
+// `DatabaseRestorePreflightService` answers "can this archive be restored, and
+// what will it cost?" without creating, dropping or renaming anything. It is a
+// PROVIDER AND NOT EXPORTED, and it is NOT wired to a controller here: #286
+// owns the restore endpoints, and a service reachable over HTTP before the
+// route that authorizes it exists is a surface nobody has reviewed.
+//
+// It needs no new import. `SettingsModule` already supplies
+// `SystemSettingsService` (it reads `restoreRollbackMode`), `PrismaModule` is
+// `@Global()`, and every cluster call goes through a short-lived `pg.Client`
+// that is deliberately OUTSIDE the Prisma pool — see
+// `admin-connection.util.ts` for the two structural reasons. Notably it does
+// NOT take `StorageProvidersModule`: pre-flight never touches the archive's
+// bytes, because verifying them means downloading gigabytes and that belongs
+// to #285's asynchronous run, not to an HTTP request.
+//
+// `RESTORE_PREFLIGHT_SEAM` and `RESTORE_ADMIN_CLIENT_FACTORY` are OPTIONAL
+// tokens left unbound, for the identical reason `DB_BACKUP_ENGINE` and
+// `DB_BACKUP_TIMERS` are: the application always probes a real cluster, and a
+// stubbed cluster connection in production is a restore subsystem that reports
+// a clean pre-flight against nothing at all.
+//
+// -----------------------------------------------------------------------------
+// #285 ADDS THE RESTORE ITSELF, AND THE ONE NEW IMPORT IT NEEDS
+// -----------------------------------------------------------------------------
+//
+// `DatabaseRestoreService` is the first thing in this repository that CREATES,
+// DROPS AND RENAMES DATABASES. It is a PROVIDER AND NOT EXPORTED and it is bound
+// to no controller, exactly as the pre-flight is: #286 owns the restore
+// endpoints, and a service that can replace the production database must not be
+// reachable over HTTP before the route that authorizes it has been reviewed.
+//
+// ⚠ `MaintenanceModule` IS THE ONE NEW IMPORT, and it is not optional. The swap
+// renames the live database out from under this process, so for those seconds
+// the PERSISTED maintenance flag — which lives inside that database — cannot be
+// read. `MaintenanceModeService`'s IN-MEMORY override layer exists for this one
+// caller and says so in its own header; without this import the swap would have
+// no way to hold traffic back at the only moment it must.
+//
+// It is a plain import rather than a re-export: the module is NOT `@Global()`
+// (unlike `PrismaModule`), it exports `MaintenanceModeService` explicitly, and
+// the dependency direction stays acyclic — maintenance depends on settings and
+// JWT, and on nothing here.
+// (The history of the app module. The packaged slice reaches the switch
+// through its `DB_BACKUP_MAINTENANCE` port; the reference app binds it to the
+// host core's global `MaintenanceModeService`, #867.)
+//
+// `DATABASE_RESTORE_SEAM` joins the list of OPTIONAL tokens deliberately left
+// unbound, and it is the most important member of that list: it carries
+// `exitProcess`, and a bound stub in production would leave a process serving
+// requests through a connection pool pointed at a database that has been
+// renamed away.
+//
+// `DatabaseBackupScheduleTask` gains a third duty in the same ten-minute tick —
+// dropping retained `<live>_old_<ts>` databases past their retention window — so
+// it now injects the restore service. It is deliberately NOT a fourth `@Cron`,
+// for the same reason retention is not a second one: a window measured in hours
+// does not need a timer of its own, and a second unsynchronised deleter of
+// databases is exactly the kind of thing this module has already decided once
+// not to have.
+// =============================================================================
+// -----------------------------------------------------------------------------
+// #288 ADDS `NotificationsModule`, AND THREE CALL SITES BEHIND IT
+// -----------------------------------------------------------------------------
+//
+// Imported for `NotificationsService`'s permission-addressed entry points, used
+// from three places in this module and nowhere else:
+//
+//   - `DatabaseBackupRunnerService.markFailed` — a run that reported an error.
+//   - `DatabaseBackupScheduleTask.releaseStaleRuns` — a run whose executing
+//     process went away. Both raise `db_backup.backup_failed`, differing only
+//     in the payload's `outcome`, because an operator chases the two in
+//     completely different places.
+//   - `DatabaseRestoreService.swap` — `db_backup.restore_completed`, and the
+//     ONE case in this repository that must use the AWAITED
+//     `notifyPermissionHoldersNow`: the swap ends in `process.exit(0)`, which
+//     would drop a detached dispatch outright. That call site carries the full
+//     argument; do not "tidy" it into the detached form.
+//
+// The direction is acyclic, like every other import here: `NotificationsModule`
+// reaches `PrismaModule`, `EmailModule` and `SettingsModule`, and none of those
+// reaches back into backups.
+//
+// ⚠ THE RECIPIENTS ARE `db_backup:read` HOLDERS, resolved from the database —
+// which for the restore notification means the RESTORED database, because the
+// dispatch happens after the swap. That is deliberate and is argued at the call
+// site: the post-restore answer to "who can act on this?" is the correct one.
+// =============================================================================
+// -----------------------------------------------------------------------------
+// #351 (EPIC #345) ADDS `JobsModule`, AND THE DUMP BECOMES A QUEUE JOB
+// -----------------------------------------------------------------------------
+//
+// Imported for exactly two things, both narrow: `JobsService` (the runner
+// enqueues `db.backup.run` from `queueBackup`) and `JobHandlerRegistry` (the
+// new handler self-registers with it). The direction stays acyclic, which is
+// the property that makes this import safe at all: `JobsModule` reaches
+// `PrismaModule`, `SettingsModule`, `StorageProvidersModule` and
+// `NotificationsModule`, and NOTHING in the queue reaches back into backups —
+// the queue does not know this type exists, which is precisely the promise of
+// the one-class extension point.
+//
+// `DatabaseBackupRunHandler` is a provider here rather than in `JobsModule`
+// for the reason step 3 of `jobs/handlers/README.md` gives: a handler belongs
+// to the module that owns the FEATURE, and the queue's own module provides
+// only the handlers that belong to no feature (`example.echo`,
+// `example.checksum`, `job.history.purge`). It is NOT exported: registration
+// happens through its own `onModuleInit`, so nothing outside this module ever
+// needs to resolve it, and a handler reachable from elsewhere is an invitation
+// to call `process()` directly and bypass the lease the worker is holding.
+//
+// ⚠ THE RUNNER IS STILL THE ONE WRITER OF `database_backup_runs`, and the
+// handler changes nothing about that: it delegates to `runQueuedBackup` and
+// holds no Prisma client of its own. Two writers of that table would make the
+// single-active-run index a coincidence rather than a guarantee.
+//
+// -----------------------------------------------------------------------------
+// #350 (EPIC #345) ADDS `PgJobRoleBroker`, THE FIRST `JobSecretBroker` ANYWHERE
+// -----------------------------------------------------------------------------
+//
+// A provider, injected into `DatabaseBackupRunHandler` (which exposes it as
+// `nodeSecretBroker`) and into `DatabaseBackupAdminService` (which exposes its
+// pre-flight over HTTP). It needs NO new import: everything it does goes through
+// a short-lived `pg.Client` outside the Prisma pool, the same way the restore
+// path does, and `PG_JOB_ROLE_SEAM` joins the list of OPTIONAL tokens
+// deliberately left unbound for exactly the reason `RESTORE_PREFLIGHT_SEAM` is
+// — a stubbed cluster in production is a broker that reports minting
+// credentials it never made.
+//
+// ⚠ ONE INSTANCE, AND THAT IS LOAD-BEARING RATHER THAN INCIDENTAL. Nest
+// providers are singletons per module, and the broker caches its `CREATEROLE`
+// probe for a minute (`USABLE_CACHE_MS`) precisely so a polling fleet does not
+// re-probe per node per tick. Constructing a broker inside the handler instead
+// would give the cache one owner per construction, which is a cache that never
+// hits.
+//
+// It is NOT exported. The two consumers are both in this module, and a broker
+// reachable from elsewhere is an invitation to mint a database credential
+// outside the one route that authorises it (`POST /api/nodes/:id/jobs/:jobId
+// /secret`, gated on the hold guard, the opt-in setting and `usable()`).
+// =============================================================================
+/**
+ * Fails boot when a bound target is malformed or two targets share an id.
+ * Instantiated with the module (it injects the targets, so a `useClass` target
+ * is built and checked at startup rather than at the first backup).
+ */
+let DbBackupTargetValidator = class DbBackupTargetValidator {
+    constructor(primary, mirrors) {
+        (0, backup_target_1.validateBackupTargets)(primary, mirrors ?? []);
+    }
+};
+DbBackupTargetValidator = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(backup_target_1.DB_BACKUP_TARGET)),
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(backup_target_1.DB_BACKUP_MIRROR_TARGETS)),
+    __metadata("design:paramtypes", [Object, Array])
+], DbBackupTargetValidator);
+/**
+ * The database backup and restore slice: the backup engine, its schedule and
+ * retention, the restore (pre-flight, swap, rollback), the four job types
+ * (`db.backup.run`, `db.backup.sweep`, `db.restore.run`,
+ * `db.restore.old-db-drop`), the `/api/admin/db-backup` routes and three
+ * Doctor checks (`backup.schedule`, `backup.pg-client`, `backup.rls-bypass`, `backup.mirrors`).
+ *
+ * Needs, from the app: `JobsModule.forRoot()` and `SettingsModule.forRoot()`
+ * (global), the core `PlatformHostModule` (`PLATFORM_PRISMA`), the
+ * `DoctorModule`, `ConfigModule` (`appUrl`, `dbBackup.scheduleEnabled`), and a
+ * host module binding `DB_BACKUP_NOTIFIER` and `DB_BACKUP_MAINTENANCE`
+ * (required), `DB_BACKUP_SYSTEM_DATA` (the Doctor's RLS check),
+ * `DB_BACKUP_METRICS` and `DB_BACKUP_DEPLOYMENT_MODE` (optional).
+ *
+ * @stability experimental
+ */
+let DbBackupModule = DbBackupModule_1 = class DbBackupModule {
+    /**
+     * The slice for one app. Call once. Registers the `database-backups/` key
+     * prefix (idempotent) and the `extraCarryOver` entries, and sets the
+     * archive-name slug from `appName`.
+     *
+     * @param options - see {@link DbBackupModuleOptions}; every field defaults to today's behaviour.
+     * @returns the dynamic module. It exports the runner, the retention service and `DB_BACKUP_OPTIONS`.
+     * @throws Error when an option is invalid.
+     *
+     * @example
+     * ```ts
+     * export const DbBackupModule = PlatformDbBackupModule.forRoot({ appName: APP_NAME, imports: [DbBackupHostModule] });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const resolved = (0, options_1.resolveDbBackupModuleOptions)(options);
+        (0, db_backup_key_prefix_1.registerDbBackupKeyPrefix)();
+        (0, carry_over_registry_1.registerRestoreCarryOvers)(options.extraCarryOver ?? []);
+        (0, db_backup_storage_1.configureBackupNameSlug)(resolved.appName);
+        const mirrorTokens = resolved.mirrorTargets.map((_binding, index) => Symbol.for(`@marinoscar/platform/db-backup/MIRROR_TARGET/${index}`));
+        return {
+            module: DbBackupModule_1,
+            imports: [...resolved.imports, index_1.StorageProvidersModule],
+            controllers: [db_backup_controller_1.DatabaseBackupController],
+            providers: [
+                { provide: options_1.DB_BACKUP_OPTIONS, useValue: resolved },
+                // PP-14.12. The primary target: the app's binding, else the adapter over
+                // the active STORAGE_PROVIDER (today's behaviour).
+                (resolved.target !== undefined
+                    ? { provide: backup_target_1.DB_BACKUP_TARGET, ...resolved.target }
+                    : {
+                        provide: backup_target_1.DB_BACKUP_TARGET,
+                        useFactory: (storage, storageConfig) => new backup_target_1.StorageProviderBackupTarget(storage, storageConfig),
+                        inject: [index_1.STORAGE_PROVIDER, index_1.StorageConfigService],
+                    }),
+                // The mirrors: one token each (module-scoped), collected into one array.
+                ...resolved.mirrorTargets.map((binding, index) => ({ provide: mirrorTokens[index], ...binding })),
+                { provide: backup_target_1.DB_BACKUP_MIRROR_TARGETS, useFactory: (...mirrors) => mirrors, inject: mirrorTokens },
+                DbBackupTargetValidator,
+                db_backup_events_1.DbBackupEvents,
+                restore_gate_1.DbBackupRestoreGate,
+                db_backup_runner_service_1.DatabaseBackupRunnerService,
+                db_backup_retention_service_1.DatabaseBackupRetentionService,
+                db_backup_admin_service_1.DatabaseBackupAdminService,
+                db_backup_schedule_task_1.DatabaseBackupScheduleTask,
+                db_backup_run_handler_1.DatabaseBackupRunHandler,
+                // #353 (epic #345): the three remaining long-running activities in this
+                // subsystem, each now a queue job with a handler of its own. The schedule
+                // task enqueues the first two; `startRestore` enqueues the third.
+                db_backup_sweep_handler_1.DatabaseBackupSweepHandler,
+                db_restore_old_db_drop_handler_1.DatabaseRestoreOldDbDropHandler,
+                db_restore_run_handler_1.DatabaseRestoreRunHandler,
+                pg_job_role_broker_1.PgJobRoleBroker,
+                restore_preflight_service_1.DatabaseRestorePreflightService,
+                database_restore_service_1.DatabaseRestoreService,
+                // Doctor checks (#634): read-only — never the backup or restore paths.
+                backup_schedule_doctor_check_1.BackupScheduleDoctorCheck,
+                backup_pg_client_doctor_check_1.BackupPgClientDoctorCheck,
+                backup_rls_doctor_check_1.BackupRlsDoctorCheck,
+                backup_mirrors_doctor_check_1.BackupMirrorsDoctorCheck,
+            ],
+            exports: [
+                options_1.DB_BACKUP_OPTIONS,
+                backup_target_1.DB_BACKUP_TARGET,
+                backup_target_1.DB_BACKUP_MIRROR_TARGETS,
+                restore_gate_1.DbBackupRestoreGate,
+                db_backup_runner_service_1.DatabaseBackupRunnerService,
+                db_backup_retention_service_1.DatabaseBackupRetentionService,
+            ],
+        };
+    }
+};
+exports.DbBackupModule = DbBackupModule;
+exports.DbBackupModule = DbBackupModule = DbBackupModule_1 = __decorate([
+    (0, common_1.Module)({})
+], DbBackupModule);
+//# sourceMappingURL=db-backup.module.js.map

package/dist/db-backup/db-backup.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-backup.module.js","sourceRoot":"","sources":["../../src/db-backup/db-backup.module.ts"],"names":[],"mappings":"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"}

package/dist/db-backup/db-backup.permissions.d.ts

@@ -0,0 +1,32 @@
+import type { PermissionDeclaration } from '../core/index';
+/**
+ * One permission this slice declares: core's `PermissionDeclaration`, the
+ * entry type of the permission registry (`registerPermissions`).
+ *
+ * @typeParam Id - the permission string.
+ *
+ * @stability stable
+ */
+export type DbBackupPermissionDeclaration<Id extends string = string> = PermissionDeclaration<Id>;
+/**
+ * The db-backup permissions (`db_backup:read`, `db_backup:write`,
+ * `db_backup:restore`): system scope, `admin` only. The admin
+ * `Database backups` card declares `db_backup:read`, the exact string
+ * `DatabaseBackupController` enforces.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(DB_BACKUP_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const DB_BACKUP_PERMISSIONS: {
+    /** `db_backup:read`: view the schedule, history and status. */
+    readonly DB_BACKUP_READ: DbBackupPermissionDeclaration<'db_backup:read'>;
+    /** `db_backup:write`: configure the schedule and run a backup. */
+    readonly DB_BACKUP_WRITE: DbBackupPermissionDeclaration<'db_backup:write'>;
+    /** `db_backup:restore`: restore the database from a backup. */
+    readonly DB_BACKUP_RESTORE: DbBackupPermissionDeclaration<'db_backup:restore'>;
+};
+//# sourceMappingURL=db-backup.permissions.d.ts.map

package/dist/db-backup/db-backup.permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-backup.permissions.d.ts","sourceRoot":"","sources":["../../src/db-backup/db-backup.permissions.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,MAAM,6BAA6B,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAKlG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,6BAA6B,CAAC,gBAAgB,CAAC,CAAC;IACzE,kEAAkE;IAClE,QAAQ,CAAC,eAAe,EAAE,6BAA6B,CAAC,iBAAiB,CAAC,CAAC;IAC3E,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,6BAA6B,CAAC,mBAAmB,CAAC,CAAC;CA8BhF,CAAC"}

package/dist/db-backup/db-backup.permissions.js

@@ -0,0 +1,62 @@
+"use strict";
+// =============================================================================
+// Database backup permissions (issue #676, PP-1.4)
+// =============================================================================
+//
+// Pure data: this slice's permissions and their default role grants. No
+// import and no side effect; the app's permission manifest registers it, and
+// its `roles.constants.ts` derives `PERMISSIONS` from it. After a change, run
+// `npm run catalog:permissions --workspace=api` and commit the regenerated
+// `prisma/catalog/permissions.json`. All three are SYSTEM scope: a restore is
+// deployment-wide and rolls back every organization, so no org role may ever
+// hold one (#723, #740).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DB_BACKUP_PERMISSIONS = void 0;
+// Default grants: ADMIN ONLY, including the read half, for the reason given on
+// `JOBS_PERMISSIONS` in the jobs slice (#256, epic #254: the queue, the fleet
+// and the backup history are operational surfaces).
+/**
+ * The db-backup permissions (`db_backup:read`, `db_backup:write`,
+ * `db_backup:restore`): system scope, `admin` only. The admin
+ * `Database backups` card declares `db_backup:read`, the exact string
+ * `DatabaseBackupController` enforces.
+ *
+ * @example
+ * ```ts
+ * registerPermissions(DB_BACKUP_PERMISSIONS);
+ * ```
+ *
+ * @stability stable
+ */
+exports.DB_BACKUP_PERMISSIONS = {
+    // Database backup (#256, epic #254).
+    //
+    // `:restore` IS A THIRD PERMISSION, not part of `:write`, because the two
+    // are not the same act. Writing is routine scheduling — change the hour,
+    // change how many copies are kept — and is reversible by writing again.
+    // Restoring renames the live database and restarts the process: it is
+    // destructive, it interrupts every session, and it is exactly the operation
+    // an operator should have to be granted on purpose. Folding it into `:write`
+    // would mean anyone allowed to adjust the backup schedule is also allowed to
+    // roll the database back over the top of production.
+    DB_BACKUP_READ: {
+        id: 'db_backup:read',
+        description: 'View backup schedule, history and status',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    DB_BACKUP_WRITE: {
+        id: 'db_backup:write',
+        description: 'Configure the backup schedule and run a backup',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+    DB_BACKUP_RESTORE: {
+        id: 'db_backup:restore',
+        description: 'Restore the database from a backup',
+        scope: 'system',
+        defaultGrants: ['admin'],
+    },
+};
+//# sourceMappingURL=db-backup.permissions.js.map

package/dist/db-backup/db-backup.permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-backup.permissions.js","sourceRoot":"","sources":["../../src/db-backup/db-backup.permissions.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,mDAAmD;AACnD,gFAAgF;AAChF,EAAE;AACF,wEAAwE;AACxE,6EAA6E;AAC7E,8EAA8E;AAC9E,2EAA2E;AAC3E,8EAA8E;AAC9E,6EAA6E;AAC7E,yBAAyB;AACzB,gFAAgF;;;AAchF,+EAA+E;AAC/E,8EAA8E;AAC9E,oDAAoD;AACpD;;;;;;;;;;;;GAYG;AACU,QAAA,qBAAqB,GAO9B;IACF,qCAAqC;IACrC,EAAE;IACF,0EAA0E;IAC1E,yEAAyE;IACzE,wEAAwE;IACxE,sEAAsE;IACtE,4EAA4E;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,qDAAqD;IACrD,cAAc,EAAE;QACd,EAAE,EAAE,gBAAgB;QACpB,WAAW,EAAE,0CAA0C;QACvD,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,eAAe,EAAE;QACf,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,gDAAgD;QAC7D,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;IACD,iBAAiB,EAAE;QACjB,EAAE,EAAE,mBAAmB;QACvB,WAAW,EAAE,oCAAoC;QACjD,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,CAAC,OAAO,CAAC;KACzB;CACF,CAAC"}

package/dist/db-backup/db-backup.registrations.d.ts

@@ -0,0 +1,76 @@
+import type { AppMetricDef } from '../otel-core/index';
+/**
+ * One backup instrument's declaration: an {@link AppMetricDef} whose `key` is
+ * a literal, so the app's metric-key union keeps every backup key.
+ *
+ * @typeParam Key - the metric's code key.
+ * @stability stable
+ */
+export interface DbBackupAppMetricDef<Key extends string> extends AppMetricDef {
+    /** The metric's code key. */
+    readonly key: Key;
+}
+/**
+ * The `app.backup.*` instruments, exactly as the reference app exported them
+ * before the move (a name or unit is a GreptimeDB table name: changing one
+ * orphans every dashboard query that reads it). The duration buckets are in
+ * seconds, the size buckets in bytes.
+ *
+ * @example
+ * ```ts
+ * registerAppMetrics([...JOBS_METRICS, ...DB_BACKUP_APP_METRICS, ...AUTH_METRICS]);
+ * ```
+ *
+ * @stability stable
+ */
+export declare const DB_BACKUP_APP_METRICS: readonly [
+    DbBackupAppMetricDef<'backupRuns'>,
+    DbBackupAppMetricDef<'backupDuration'>,
+    DbBackupAppMetricDef<'backupSize'>,
+    DbBackupAppMetricDef<'backupLastSuccessTimestamp'>,
+    DbBackupAppMetricDef<'backupLastSuccessSize'>
+];
+/**
+ * The notification event keys the slice raises. Persisted (preferences,
+ * delivery rows): never rename one. `db_backup.restore_completed` is
+ * mandatory (cannot be turned off).
+ *
+ * @stability stable
+ */
+export declare const DB_BACKUP_NOTIFICATION_EVENTS: Readonly<{
+    /** A backup run failed or went stale. */
+    readonly BACKUP_FAILED: "db_backup.backup_failed";
+    /** A restore swapped the restored copy in. */
+    readonly RESTORE_COMPLETED: "db_backup.restore_completed";
+}>;
+/**
+ * The email templates those events render (shipped by the email slice's
+ * template registry).
+ *
+ * @stability stable
+ */
+export declare const DB_BACKUP_EMAIL_TEMPLATES: Readonly<{
+    /** For `db_backup.backup_failed`. */
+    readonly BACKUP_FAILED: "backup-failed";
+    /** For `db_backup.restore_completed`. */
+    readonly RESTORE_COMPLETED: "restore-completed";
+}>;
+/**
+ * The four job types the slice registers. PERMANENT once jobs of a type exist
+ * (`apps/api/test/jobs/job-type-snapshot.spec.ts` pins them). `db.backup.run`
+ * is node-eligible (profile `{ maxRuntimeMs: 6 h, maxAttempts: 1 }`, its
+ * credential brokered per job); `db.restore.run` is server-only, permanently.
+ *
+ * @stability stable
+ */
+export declare const DB_BACKUP_JOB_TYPES: Readonly<{
+    /** The dump. */
+    readonly BACKUP_RUN: "db.backup.run";
+    /** Stale-run release and retention, enqueued by the schedule tick. */
+    readonly BACKUP_SWEEP: "db.backup.sweep";
+    /** The restore. Server-only. */
+    readonly RESTORE_RUN: "db.restore.run";
+    /** Drops retained `<live>_old_<ts>` databases past their window. */
+    readonly RESTORE_OLD_DB_DROP: "db.restore.old-db-drop";
+}>;
+//# sourceMappingURL=db-backup.registrations.d.ts.map

package/dist/db-backup/db-backup.registrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-backup.registrations.d.ts","sourceRoot":"","sources":["../../src/db-backup/db-backup.registrations.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAsB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAI3E;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB,CAAC,GAAG,SAAS,MAAM,CAAE,SAAQ,YAAY;IAC5E,6BAA6B;IAC7B,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS;IAC3C,oBAAoB,CAAC,YAAY,CAAC;IAClC,oBAAoB,CAAC,gBAAgB,CAAC;IACtC,oBAAoB,CAAC,YAAY,CAAC;IAClC,oBAAoB,CAAC,4BAA4B,CAAC;IAClD,oBAAoB,CAAC,uBAAuB,CAAC;CA0C9C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B;IACxC,yCAAyC;;IAEzC,8CAA8C;;EAErC,CAAC;AAEZ;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;IACpC,qCAAqC;;IAErC,yCAAyC;;EAEhC,CAAC;AAEZ;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB;IAC9B,gBAAgB;;IAEhB,sEAAsE;;IAEtE,gCAAgC;;IAEhC,oEAAoE;;EAE3D,CAAC"}