@flowdular/sdk 0.3.0 → 0.3.1

package/modules/exports/src/cli/commands.json

@@ -0,0 +1,17 @@
+{
+	"protocolVersion": 1,
+	"moduleId": "exports.core",
+	"commands": [
+		{
+			"path": ["exports", "secrets-rotate"],
+			"capability": {
+				"id": "exports.storage.rotate",
+				"version": 1,
+				"summary": "Re-seal stored export files with the current storage encryption key.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		}
+	]
+}

package/modules/exports/src/cli/index.ts

@@ -0,0 +1,145 @@
+import {
+	defineCliExtension,
+	type CliExtensionContext,
+} from '@flowdular/sdk/cli-protocol';
+import {
+	DATABASE_CAPABILITY_IDS,
+	DATABASE_DIALECT_IDS,
+	type DatabaseAdapterLease,
+} from '@flowdular/sdk/database';
+import {
+	createStorageKeyring,
+	createStoragePort,
+	storageConfigFromEnvironment,
+} from '@flowdular/sdk/storage';
+import { migrateExportsDatabase } from '../services/database-repository.ts';
+import {
+	rotateExportObjects,
+	type StorageRotationReport,
+} from '../services/storage-rotation.ts';
+
+const rotateCapability = {
+	id: 'exports.storage.rotate',
+	version: 1,
+	summary:
+		'Re-seal stored export files with the current storage encryption key.',
+	risk: 'process' as const,
+	requiresApprovedSpec: false,
+	supportsDryRun: true,
+};
+
+interface OpenDatabase {
+	readonly leases: readonly DatabaseAdapterLease[];
+	readonly runtime: DatabaseAdapterLease;
+	readonly background: DatabaseAdapterLease;
+}
+
+/* The operator command reads the same deployment database the platform does;
+   the runner owns the provider and a module owns no driver, so it arrives on
+   the context. It may be the first thing to touch a fresh database, so it
+   migrates before reading. */
+async function open(context: CliExtensionContext): Promise<OpenDatabase> {
+	const databases = context.databases;
+	if (!databases) {
+		throw new Error(
+			'exports.core CLI commands read the deployment database, and this workspace has none configured.',
+		);
+	}
+	const requirements = {
+		dialectIds: [DATABASE_DIALECT_IDS.postgresql],
+		capabilities: [DATABASE_CAPABILITY_IDS.TRANSACTIONS],
+	};
+	const migration = await databases.acquire({
+		namespace: 'exports.core',
+		purpose: 'migration',
+		requirements,
+	});
+	await migrateExportsDatabase(migration.database);
+	const runtime = await databases.acquire({
+		namespace: 'exports.core',
+		purpose: 'runtime',
+		requirements,
+	});
+	/* The inventory lists workspaces across the whole deployment, which only
+	   the cross-tenant read-only role may do. */
+	const background = await databases.acquire({
+		namespace: 'exports.core',
+		purpose: 'background',
+		requirements,
+	});
+	return { leases: [migration, runtime, background], runtime, background };
+}
+
+/* The provider belongs to the runner; only the leases this command took are
+   released here. */
+async function close(open: OpenDatabase): Promise<void> {
+	for (const lease of open.leases) await lease.release();
+}
+
+export function storageRotationWarnings(
+	report: StorageRotationReport,
+	variable: string,
+): string[] {
+	const warnings: string[] = [];
+	if (report.unknown > 0) {
+		warnings.push(
+			`${report.unknown} objects are sealed under a key this ring does not hold and were left as they are. Put that key back in ${variable}_PREVIOUS before retiring it.`,
+		);
+	}
+	if (report.refused > 0) {
+		warnings.push(
+			`${report.refused} objects failed authentication under the key they name and were left as they are. Restore them from the object store backup.`,
+		);
+	}
+	if (report.missing > 0) {
+		warnings.push(
+			`${report.missing} jobs name a file the store no longer holds.`,
+		);
+	}
+	return warnings;
+}
+
+export const cliExtension = defineCliExtension({
+	protocolVersion: 1,
+	moduleId: 'exports.core',
+	commands: [
+		{
+			path: ['exports', 'secrets-rotate'],
+			capability: rotateCapability,
+			execute: async (context) => {
+				/* The report names key ids and counts only; no file content reaches
+				   the command output. The port is the platform's own, built from the
+				   same environment the server reads. */
+				const storage = createStoragePort(
+					storageConfigFromEnvironment(process.env, context.workspaceRoot),
+					{ keyring: createStorageKeyring(process.env, context.workspaceRoot) },
+				);
+				const opened = await open(context);
+				try {
+					const report = await rotateExportObjects({
+						runtime: opened.runtime.database,
+						background: opened.background.database,
+						storage,
+						apply: context.apply,
+					});
+					return {
+						data: { moduleId: 'exports.core', ...report },
+						evidence: [
+							'modules/exports/spec/module.yaml',
+							'docs/operations.md',
+						],
+						warnings: storageRotationWarnings(
+							report,
+							'FD_STORAGE_ENCRYPTION_KEY',
+						),
+					};
+				} finally {
+					await close(opened);
+					await storage.dispose();
+				}
+			},
+		},
+	],
+});
+
+export default cliExtension;

package/modules/exports/src/server/index.ts

@@ -37,7 +37,6 @@ export type {
 	ExportJobPage,
 	ExportJobQuery,
 	ExportRepository,
-	ExportSweepBatch,
 	ExportSweepInput,
 	SettleExportJobInput,
 } from '../services/repository.ts';

package/modules/exports/src/services/data-classes.ts

@@ -33,19 +33,22 @@ export function exportsDataClass(
 		exportable: true,
 		sweep: async ({ tenantId, cutoff, limit }) => {
 			const open = await repository();
-			const batch = await open.claimSweepBatch(tenantId, {
-				settledBefore: cutoff.getTime(),
-				/* The platform's number is the caller's; this is the module's own
-				   bound on one pass. */
-				limit: Math.min(Math.max(Math.trunc(limit), 1), EXPORT_SWEEP_JOBS),
-			});
-			if (batch.ids.length === 0) return { removed: 0 };
-			/* The file goes before the row it belongs to. An interrupted pass then
-			   leaves a row naming a file that is gone, which the next pass removes
-			   and a read answers as gone; the other order would leave a file
-			   nothing references and no pass could ever find. */
-			await (await service()).discardObjects(tenantId, batch.objectIds);
-			return { removed: await open.deleteJobs(tenantId, batch.ids) };
+			/* The file goes before the row it belongs to, under the row lock. An
+			   interrupted pass then leaves a row naming a file that is gone, which
+			   the next pass removes and a read answers as gone; the other order
+			   would leave a file nothing references and no pass could ever find. */
+			const removed = await open.sweepJobs(
+				tenantId,
+				{
+					settledBefore: cutoff.getTime(),
+					/* The platform's number is the caller's; this is the module's own
+					   bound on one pass. */
+					limit: Math.min(Math.max(Math.trunc(limit), 1), EXPORT_SWEEP_JOBS),
+				},
+				async (objectIds) =>
+					(await service()).discardObjects(tenantId, objectIds),
+			);
+			return { removed };
 		},
 		/* Metadata only. The requester snapshot is bookkeeping for a background
 		   stage, and the exported files are the lists' own data, already covered

package/modules/exports/src/services/database-repository.ts

@@ -17,7 +17,6 @@ import type {
 	ExportJobPage,
 	ExportJobQuery,
 	ExportRepository,
-	ExportSweepBatch,
 	ExportSweepInput,
 	SettleExportJobInput,
 } from './repository.ts';
@@ -67,13 +66,14 @@ const SQL = {
 	 WHERE tenant_id = $1 AND id = $2 AND status = 'running'
 	 RETURNING ${JOB_COLUMNS}`,
 
-	/* The batch is chosen once and its objects come back with it: deleting the
-	   files and then the rows from one chosen set means no pass can delete a
-	   file whose row a differently ordered second query kept. */
+	/* The batch is chosen once and locked: the files and then the rows go from
+	   one chosen set, and a rewrite of a file under the same row lock waits for
+	   the delete or is waited for by it. */
 	sweepBatch: `SELECT id, object_id FROM exports_jobs
 	 WHERE tenant_id = $1 AND started_at < $2
 	   AND status IN ('completed', 'failed')
-	 ORDER BY started_at, id LIMIT $3`,
+	 ORDER BY started_at, id LIMIT $3
+	 FOR UPDATE`,
 
 	exportPage: `SELECT ${JOB_COLUMNS} FROM exports_jobs
 	 WHERE tenant_id = $1 AND (started_at, id) > ($2, $3)
@@ -319,40 +319,38 @@ export class DatabaseExportRepository implements ExportRepository {
 		return row ? jobFromRow(row) : null;
 	}
 
-	async claimSweepBatch(
+	async sweepJobs(
 		tenantId: string,
 		input: ExportSweepInput,
-	): Promise<ExportSweepBatch> {
-		const result = await this.#handles.runtime.transaction(
-			(transaction) =>
-				transaction.query<{ id: string; object_id: string | null }>({
+		discard: (objectIds: readonly string[]) => Promise<void>,
+	): Promise<number> {
+		return this.#handles.runtime.transaction(
+			async (transaction) => {
+				const chosen = await transaction.query<{
+					id: string;
+					object_id: string | null;
+				}>({
 					text: SQL.sweepBatch,
 					parameters: [tenantId, input.settledBefore, input.limit],
-				}),
-			{ access: 'read', tenantId },
-		);
-		const ids: string[] = [];
-		const objectIds: string[] = [];
-		for (const row of result.rows) {
-			ids.push(row.id);
-			if (row.object_id !== null) objectIds.push(row.object_id);
-		}
-		return { ids, objectIds };
-	}
-
-	async deleteJobs(tenantId: string, ids: readonly string[]): Promise<number> {
-		if (ids.length === 0) return 0;
-		const parameters: (string | number)[] = [tenantId, ...ids];
-		const placeholders = ids.map((_id, index) => `$${index + 2}`).join(', ');
-		const result = await this.#handles.runtime.transaction(
-			(transaction) =>
-				transaction.execute({
+				});
+				if (chosen.rows.length === 0) return 0;
+				await discard(
+					chosen.rows.flatMap((row) =>
+						row.object_id === null ? [] : [row.object_id],
+					),
+				);
+				const ids = chosen.rows.map((row) => row.id);
+				const placeholders = ids
+					.map((_id, index) => `$${index + 2}`)
+					.join(', ');
+				const result = await transaction.execute({
 					text: `DELETE FROM exports_jobs WHERE tenant_id = $1 AND id IN (${placeholders})`,
-					parameters,
-				}),
+					parameters: [tenantId, ...ids],
+				});
+				return result.affectedRows;
+			},
 			{ access: 'write', tenantId },
 		);
-		return result.affectedRows;
 	}
 
 	async exportJobs(

package/modules/exports/src/services/migration.ts

@@ -57,6 +57,18 @@ REVOKE SELECT ON exports_jobs FROM coreloom_background;
 GRANT SELECT (tenant_id, id, status, started_at) ON exports_jobs TO coreloom_background;
 `;
 
+/* Mirrors migrations/0003_exports_rotation_inventory.up.sql byte for byte. */
+export const EXPORTS_MIGRATION_003_ROTATION_INVENTORY = `-- The storage key rotation has to find the workspaces that still hold export
+-- files before it knows which files those are. The routing policy shows the
+-- background role only waiting and running jobs; this one adds the completed
+-- jobs under the same four routing columns, so the object id, the list, the
+-- requester and every count stay invisible to it, and every file it names is
+-- read again under the workspace that row named.
+CREATE POLICY exports_jobs_rotation_policy ON exports_jobs
+  FOR SELECT TO coreloom_background
+  USING (status = 'completed');
+`;
+
 export const databaseMigrations: readonly DatabaseMigration[] = [
 	{
 		id: '0001_exports_core',
@@ -86,4 +98,19 @@ export const databaseMigrations: readonly DatabaseMigration[] = [
 			return result.rows[0]?.granted ? 'complete' : 'absent';
 		},
 	},
+	{
+		id: '0003_exports_rotation_inventory',
+		sql: { postgresql: EXPORTS_MIGRATION_003_ROTATION_INVENTORY },
+		/* A policy leaves no schema object behind, so its catalogue row is what
+		   proves this migration ran. */
+		inspectExisting: async (database) => {
+			const result = await database.query<{ present: boolean }>({
+				text: `SELECT EXISTS (
+				  SELECT 1 FROM pg_policies
+				  WHERE tablename = 'exports_jobs' AND policyname = 'exports_jobs_rotation_policy'
+				) AS present`,
+			});
+			return result.rows[0]?.present === true ? 'complete' : 'absent';
+		},
+	},
 ];

package/modules/exports/src/services/repository.ts

@@ -50,12 +50,6 @@ export interface ExportSweepInput {
 	readonly limit: number;
 }
 
-export interface ExportSweepBatch {
-	readonly ids: readonly string[];
-	/** The objects those jobs hold, for the caller to delete before the rows. */
-	readonly objectIds: readonly string[];
-}
-
 /**
  * The business port: async, database-agnostic, and unaware of SQL. Every method
  * is tenant-scoped except `listPendingJobs`, which crosses workspaces on the
@@ -83,12 +77,17 @@ export interface ExportRepository {
 		input: SettleExportJobInput,
 	): Promise<ExportJob | null>;
 	/** The batch one retention pass removes, chosen once, oldest first. */
-	claimSweepBatch(
+	/**
+	 * Locks one batch of settled jobs, hands their object ids to `discard`
+	 * while the rows are held, then deletes the rows; answers how many went.
+	 * The lock orders the sweep against a pass that rewrites a file under the
+	 * same lock, so neither can leave a file the other does not see.
+	 */
+	sweepJobs(
 		tenantId: string,
 		input: ExportSweepInput,
-	): Promise<ExportSweepBatch>;
-	/** Removes the jobs of a chosen batch; answers how many rows went. */
-	deleteJobs(tenantId: string, ids: readonly string[]): Promise<number>;
+		discard: (objectIds: readonly string[]) => Promise<void>,
+	): Promise<number>;
 	/** The whole workspace, oldest first, for the data class export. */
 	exportJobs(
 		tenantId: string,

package/modules/exports/src/services/storage-rotation.ts

@@ -0,0 +1,138 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import type { StorageResealCount, StorageResealPort } from '@flowdular/sdk/storage';
+import { EXPORT_OWNER_MODULE } from './export-service.ts';
+
+/** Objects walked inside one tenant-scoped transaction. */
+export const STORAGE_ROTATION_BATCH = 200;
+
+export const STORAGE_ROTATION_TABLE = 'exports_jobs';
+
+export interface StorageRotationReport {
+	readonly table: string;
+	/** Key id every object should end on: the current key of the storage ring. */
+	readonly currentKeyId: string;
+	readonly counts: readonly StorageResealCount[];
+	readonly tenants: number;
+	/** Completed jobs that name a file. */
+	readonly objects: number;
+	/** Objects on a retired key the ring still holds when the run started. */
+	readonly stale: number;
+	readonly resealed: number;
+	/** Objects under a key id the ring does not hold; left as they are. */
+	readonly unknown: number;
+	/** Objects that failed authentication; left as they are. */
+	readonly refused: number;
+	/** Jobs whose file the store no longer holds. */
+	readonly missing: number;
+}
+
+export interface StorageRotationOptions {
+	/** Tenant-scoped handle. Every row is read on it. */
+	readonly runtime: DatabaseHandle;
+	/** Cross-tenant handle. It is granted the routing columns and nothing else. */
+	readonly background: DatabaseHandle;
+	readonly storage: StorageResealPort;
+	readonly apply?: boolean;
+	readonly batchSize?: number;
+}
+
+const SQL = {
+	/* The cross-tenant role sees the job status and not the object id, so the
+	   inventory names workspaces with completed jobs; the rows that carry a
+	   file are read under each of them. */
+	tenants: `SELECT tenant_id
+	          FROM exports_jobs
+	          WHERE status = 'completed'
+	          GROUP BY tenant_id
+	          ORDER BY tenant_id`,
+	/* Paged by primary key. The rows are locked while their files are
+	   rewritten, so the retention sweep deletes a row after the batch that
+	   rewrote its file, never between the read and the write. */
+	batch: `SELECT id, object_id
+	        FROM exports_jobs
+	        WHERE tenant_id = $1 AND object_id IS NOT NULL AND id > $2
+	        ORDER BY id
+	        LIMIT $3
+	        FOR UPDATE`,
+	inventoryBatch: `SELECT id, object_id
+	                 FROM exports_jobs
+	                 WHERE tenant_id = $1 AND object_id IS NOT NULL AND id > $2
+	                 ORDER BY id
+	                 LIMIT $3`,
+};
+
+/**
+ * Re-seals every export file that is not on the current storage key. The
+ * workspaces are listed once on the cross-tenant role, and each batch of jobs
+ * is read under its own tenant; the files they name are read from the store,
+ * and the stale ones rewritten in place. It is idempotent: a second run finds
+ * nothing to do.
+ */
+export async function rotateExportObjects(
+	options: StorageRotationOptions,
+): Promise<StorageRotationReport> {
+	const apply = options.apply === true;
+	const batchSize = options.batchSize ?? STORAGE_ROTATION_BATCH;
+	const inventory = await options.background.transaction(
+		(transaction) =>
+			transaction.query<{ tenant_id: string }>({ text: SQL.tenants }),
+		{ access: 'read' },
+	);
+	const counts = new Map<string, number>();
+	let objects = 0;
+	let stale = 0;
+	let resealed = 0;
+	let unknown = 0;
+	let refused = 0;
+	let missing = 0;
+	for (const { tenant_id: tenantId } of inventory.rows) {
+		let cursor = '';
+		for (;;) {
+			const batch = await options.runtime.transaction(
+				async (transaction) => {
+					const rows = (
+						await transaction.query<{ id: string; object_id: string }>({
+							text: apply ? SQL.batch : SQL.inventoryBatch,
+							parameters: [tenantId, cursor, batchSize],
+						})
+					).rows;
+					const report = await options.storage.reseal(
+						rows.map((row) => ({
+							tenantId,
+							moduleId: EXPORT_OWNER_MODULE,
+							objectId: row.object_id,
+						})),
+						{ apply },
+					);
+					return { read: rows.length, last: rows.at(-1)?.id, report };
+				},
+				{ access: apply ? 'write' : 'read', tenantId },
+			);
+			objects += batch.read;
+			for (const entry of batch.report.counts) {
+				counts.set(entry.keyId, (counts.get(entry.keyId) ?? 0) + entry.objects);
+			}
+			stale += batch.report.stale;
+			resealed += batch.report.resealed;
+			unknown += batch.report.unknown;
+			refused += batch.report.refused;
+			missing += batch.report.missing;
+			if (batch.read < batchSize || batch.last === undefined) break;
+			cursor = batch.last;
+		}
+	}
+	return {
+		table: STORAGE_ROTATION_TABLE,
+		currentKeyId: options.storage.keyId,
+		counts: [...counts]
+			.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+			.map(([keyId, total]) => ({ keyId, objects: total })),
+		tenants: inventory.rows.length,
+		objects,
+		stale,
+		resealed,
+		unknown,
+		refused,
+		missing,
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/sdk",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"type": "module",
 	"description": "Flowdular platform SDK: server, client, UI, data, agents and core modules through separate exports.",
 	"license": "MIT",

package/packages/contracts/src/index.ts

@@ -4,7 +4,7 @@
    removed or changed. The surface is pinned by
    packages/kernel/platform-api.snapshot.d.ts; `pnpm platform-api:check` fails
    when the surface changes without a bump here. */
-export const PLATFORM_API_VERSION = '0.1.6';
+export const PLATFORM_API_VERSION = '0.1.8';
 
 /* The workspace time zone: one tenant setting, declared by the module named
    here and read by any module that shows or schedules a local time. The id, the

package/packages/database/src/backup.ts

@@ -14,6 +14,7 @@ export const BACKUP_MANIFEST_VERSION = 1;
 export const BACKUP_KEY_VARIABLES = Object.freeze([
 	'FD_AGENT_CREDENTIAL_KEY',
 	'FD_AGENT_RUN_GRANT_KEY',
+	'FD_APPROVAL_GRANT_KEY',
 	'FD_WORKFLOWS_PAYLOAD_KEY',
 	'FD_WORKFLOWS_CURSOR_KEY',
 	'FD_AUTH_MFA_KEY',

package/packages/database/src/migrations.ts

@@ -10,6 +10,8 @@ import {
 } from './contracts.ts';
 
 export const DATABASE_MIGRATION_LEDGER = '_coreloom_migrations_v2';
+/** The advisory lock every module migration takes before its own. */
+export const DATABASE_MIGRATION_LEDGER_LOCK = 'coreloom.migrations';
 
 /* Line endings and surrounding blank space are editor noise; everything else,
    including whitespace inside the SQL, is part of the checksum. Changing this
@@ -377,6 +379,11 @@ export async function runDatabaseMigrations(
 
 	return database.transaction(
 		async (transaction) => {
+			/* Every module shares the ledger table, and this transaction is
+			   serializable, so two modules migrating at the same boot collide on
+			   it with a serialization failure. The ledger lock serialises boots
+			   across modules; the namespace lock keeps the per-module contract. */
+			await transaction.acquireMigrationLock(DATABASE_MIGRATION_LEDGER_LOCK);
 			await transaction.acquireMigrationLock(namespace);
 			await transaction.executeScript(
 				database.capabilities.sql.migrationLedgerDdl(DATABASE_MIGRATION_LEDGER),