@classytic/arc 2.23.0 → 2.25.0

package/dist/migrations/index.mjs

@@ -1,4 +1,59 @@
+import { t as startRenewingLease } from "../renewingLease-3cuQH7h8.mjs";
+import { createHash, randomUUID } from "node:crypto";
 //#region src/migrations/index.ts
+/**
+* Schema Versioning and Migrations System
+*
+* Manages database schema changes over time with version tracking.
+* Supports forward migrations, rollbacks, and schema compatibility layers.
+*
+* DB-agnostic: the `db` parameter is typed as `unknown` — the user passes
+* whatever connection object their adapter uses (Mongoose db, Prisma client,
+* Knex instance, etc.) and their `up`/`down` functions cast it internally.
+*
+* @example
+* import { defineMigration, MigrationRunner } from '@classytic/arc/migrations';
+*
+* const productV2 = defineMigration({
+*   version: 2,
+*   resource: 'product',
+*   up: async (db) => {
+*     const mongo = db as import('mongoose').mongo.Db;
+*     await mongo.collection('products').updateMany(
+*       {},
+*       { $rename: { 'oldField': 'newField' } }
+*     );
+*   },
+*   down: async (db) => {
+*     const mongo = db as import('mongoose').mongo.Db;
+*     await mongo.collection('products').updateMany(
+*       {},
+*       { $rename: { 'newField': 'oldField' } }
+*     );
+*   },
+* });
+*
+* const runner = new MigrationRunner(mongoose.connection.db, {
+*   store: new MongoMigrationStore(mongoose.connection.db),
+*   lock: createMongoLockAdapter({ connection }), // multi-replica safety
+* });
+* await runner.up(migrations);
+*
+* ## Deployment discipline
+*
+* Migrations should be executed by ONE owner — a deploy job, a CI step, or
+* a leader — not by every replica on startup. The optional `lock` (any
+* ecosystem `LockAdapter`) makes concurrent runners fail fast instead of
+* double-applying, and the pending set is recomputed INSIDE the lock so a
+* runner that waited on another deploy sees its writes. Two windows remain
+* host concerns and are deliberately documented instead of hidden:
+*   - a crash between `up()` and `record()` re-executes that migration on
+*     the next run — write migrations to be idempotent (`$rename`,
+*     `IF NOT EXISTS`, upserts);
+*   - `up()` and `record()` are not one transaction — stores backed by a
+*     transactional DB can override `record()` to join the migration's
+*     transaction.
+*/
 /** Default logger that writes to stdout/stderr */
 const defaultLogger = {
 	info: (msg) => process.stdout.write(`${msg}\n`),
@@ -14,13 +69,14 @@ var MongoMigrationStore = class {
 	async getApplied() {
 		return await this.db.collection(this.collectionName).find({}).sort({ appliedAt: 1 }).toArray();
 	}
-	async record(migration, executionTime) {
+	async record(migration, executionTime, meta) {
 		await this.db.collection(this.collectionName).insertOne({
 			version: migration.version,
 			resource: migration.resource,
 			description: migration.description,
 			appliedAt: /* @__PURE__ */ new Date(),
-			executionTime
+			executionTime,
+			...meta?.checksum ? { checksum: meta.checksum } : {}
 		});
 	}
 	async remove(migration) {
@@ -30,6 +86,16 @@ var MongoMigrationStore = class {
 		});
 	}
 };
+const MIGRATION_LOCK_NAME = "arc:migrations";
+const DEFAULT_LOCK_LEASE_MS = 600 * 1e3;
+/**
+* Source checksum for drift detection — SHA-256 over the migration's
+* `up`/`down` source. Stable for a given build; a transpile-target change
+* can legitimately shift it (hence `checksumMismatch: 'warn'` default).
+*/
+function computeMigrationChecksum(migration) {
+	return createHash("sha256").update(migration.up.toString()).update("\n").update(migration.down.toString()).digest("hex");
+}
 /**
 * Define a migration
 */
@@ -62,62 +128,148 @@ var MigrationRunner = class {
 	db;
 	store;
 	log;
+	lock;
+	lockLeaseMs;
+	holderId;
+	checksumMismatch;
 	constructor(db, opts) {
 		this.db = db;
 		this.store = opts.store;
 		this.log = opts.logger ?? defaultLogger;
+		this.lock = opts.lock;
+		this.lockLeaseMs = opts.lockLeaseMs ?? DEFAULT_LOCK_LEASE_MS;
+		this.holderId = opts.holderId ?? `migration-runner-${randomUUID()}`;
+		this.checksumMismatch = opts.checksumMismatch ?? "warn";
 	}
 	/**
-	* Run all pending migrations
+	* Acquire the migration lease (when a lock is configured) and run `fn`.
+	* Fail-fast on contention: a concurrent deploy should error loudly, not
+	* queue — the OTHER runner is applying the same set.
+	*
+	* The lease renews while `fn` runs (`startRenewingLease` — serialized,
+	* awaited teardown), so a migration slower than `lockLeaseMs` can't let
+	* a second deployment acquire the lock mid-run. Ownership loss is
+	* ENFORCED, not just logged: `fn` receives a `leaseLost` probe to refuse
+	* starting further migrations, and even a successful `fn` fails the run
+	* when the lease was lost — a concurrent runner may have interleaved, so
+	* the applied state must be verified, not trusted. (A stale holder's
+	* in-flight write can only be truly fenced by a token from the lock
+	* contract — planned repo-core evolution.)
 	*/
-	async up(migrations) {
-		const applied = await this.store.getApplied();
-		const appliedVersions = new Set(applied.map((m) => `${m.resource}:${m.version}`));
-		const pending = migrations.filter((m) => !appliedVersions.has(`${m.resource}:${m.version}`)).sort((a, b) => a.version - b.version);
-		if (pending.length === 0) {
-			this.log.info("No pending migrations");
-			return;
+	async withLock(fn) {
+		const lock = this.lock;
+		if (!lock) return fn(() => false);
+		if (!await lock.tryAcquire(MIGRATION_LOCK_NAME, this.holderId, this.lockLeaseMs)) throw new Error(`MigrationRunner: another runner holds the migration lock — refusing to run concurrently. If a previous runner crashed, the lease expires on its own (leaseMs: ${this.lockLeaseMs}).`);
+		const lease = startRenewingLease({
+			lock,
+			name: MIGRATION_LOCK_NAME,
+			holderId: this.holderId,
+			leaseMs: this.lockLeaseMs,
+			onLost: () => this.log.error("MigrationRunner: lease renewal lost — another holder took the migration lock; no further migrations will start and this run will fail."),
+			onError: (error) => this.log.error(`MigrationRunner: lease renewal errored (lease may lapse mid-run): ${error.message}`)
+		});
+		try {
+			const result = await fn(() => lease.lost);
+			if (lease.lost) throw new Error("MigrationRunner: migration lock ownership was lost mid-run — a concurrent runner may have executed migrations in parallel. Verify the applied state (getAppliedMigrations) before re-running.");
+			return result;
+		} finally {
+			await lease.stop();
+			try {
+				await lock.release(MIGRATION_LOCK_NAME, this.holderId);
+			} catch (error) {
+				this.log.error(`MigrationRunner: lock release failed: ${error.message}`);
+			}
 		}
-		this.log.info(`Running ${pending.length} migration(s)...`);
-		for (const migration of pending) await this.runMigration(migration, "up");
-		this.log.info("All migrations completed successfully");
 	}
 	/**
-	* Rollback last migration
+	* Drift detection: compare each APPLIED record's stored checksum against
+	* the current source of the same migration. A mismatch means the file was
+	* edited after being applied — its `down()` may no longer invert what
+	* actually ran.
 	*/
-	async down(migrations) {
-		const applied = await this.store.getApplied();
-		if (applied.length === 0) {
-			this.log.info("No migrations to rollback");
-			return;
-		}
-		const last = applied[applied.length - 1];
-		if (!last) {
-			this.log.info("No migrations to rollback");
-			return;
+	verifyChecksums(applied, migrations) {
+		for (const record of applied) {
+			if (!record.checksum) continue;
+			const current = migrations.find((m) => m.resource === record.resource && m.version === record.version);
+			if (!current) continue;
+			const checksum = computeMigrationChecksum(current);
+			if (checksum !== record.checksum) {
+				const msg = `Migration ${record.resource}:${record.version} source changed after it was applied (checksum ${record.checksum.slice(0, 12)}… → ${checksum.slice(0, 12)}…). Ship a NEW migration instead of editing an applied one.`;
+				if (this.checksumMismatch === "error") throw new Error(`MigrationRunner: ${msg}`);
+				this.log.error(`WARNING: ${msg}`);
+			}
 		}
-		const migration = migrations.find((m) => m.resource === last.resource && m.version === last.version);
-		if (!migration) throw new Error(`Migration ${last.resource}:${last.version} not found in migration files`);
-		this.log.info(`Rolling back ${migration.resource} v${migration.version}...`);
-		await this.runMigration(migration, "down", true);
-		this.log.info("Rollback completed");
 	}
 	/**
-	* Rollback to specific version
+	* Run all pending migrations.
+	*
+	* With a `lock` configured, the applied set is (re)read INSIDE the lease —
+	* a runner that raced another deploy computes pending against the winner's
+	* completed writes, not a stale pre-lock snapshot.
 	*/
-	async downTo(migrations, targetVersion) {
-		const toRollback = (await this.store.getApplied()).filter((m) => m.version > targetVersion).reverse();
-		if (toRollback.length === 0) {
-			this.log.info(`Already at or below version ${targetVersion}`);
-			return;
-		}
-		this.log.info(`Rolling back ${toRollback.length} migration(s)...`);
-		for (const record of toRollback) {
-			const migration = migrations.find((m) => m.resource === record.resource && m.version === record.version);
-			if (!migration) throw new Error(`Migration ${record.resource}:${record.version} not found`);
+	async up(migrations) {
+		await this.withLock(async (leaseLost) => {
+			const applied = await this.store.getApplied();
+			this.verifyChecksums(applied, migrations);
+			const appliedVersions = new Set(applied.map((m) => `${m.resource}:${m.version}`));
+			const pending = migrations.filter((m) => !appliedVersions.has(`${m.resource}:${m.version}`)).sort((a, b) => a.version - b.version);
+			if (pending.length === 0) {
+				this.log.info("No pending migrations");
+				return;
+			}
+			this.log.info(`Running ${pending.length} migration(s)...`);
+			for (const migration of pending) {
+				if (leaseLost()) throw new Error("MigrationRunner: refusing to start the next migration — lock ownership lost.");
+				await this.runMigration(migration, "up");
+			}
+			this.log.info("All migrations completed successfully");
+		});
+	}
+	/**
+	* Rollback last migration
+	*/
+	async down(migrations) {
+		await this.withLock(async () => {
+			const applied = await this.store.getApplied();
+			const last = applied[applied.length - 1];
+			if (!last) {
+				this.log.info("No migrations to rollback");
+				return;
+			}
+			const migration = migrations.find((m) => m.resource === last.resource && m.version === last.version);
+			if (!migration) throw new Error(`Migration ${last.resource}:${last.version} not found in migration files`);
+			this.log.info(`Rolling back ${migration.resource} v${migration.version}...`);
 			await this.runMigration(migration, "down", true);
-		}
-		this.log.info("Rollback completed");
+			this.log.info("Rollback completed");
+		});
+	}
+	/**
+	* Rollback to a specific version.
+	*
+	* Versions are RESOURCE-scoped, so a bare numeric threshold is only
+	* meaningful within one resource. When the applied set spans multiple
+	* resources, `options.resource` is required — rolling every resource back
+	* across a shared number silently reverts unrelated schemas.
+	*/
+	async downTo(migrations, targetVersion, options) {
+		await this.withLock(async (leaseLost) => {
+			const applied = await this.store.getApplied();
+			const resources = new Set(applied.map((m) => m.resource));
+			if (!options?.resource && resources.size > 1) throw new Error(`MigrationRunner.downTo: applied migrations span ${resources.size} resources (${[...resources].sort().join(", ")}) — versions are resource-scoped, so pass { resource: '<name>' } to select which one to roll back.`);
+			const toRollback = (options?.resource ? applied.filter((m) => m.resource === options.resource) : applied).filter((m) => m.version > targetVersion).reverse();
+			if (toRollback.length === 0) {
+				this.log.info(`Already at or below version ${targetVersion}`);
+				return;
+			}
+			this.log.info(`Rolling back ${toRollback.length} migration(s)...`);
+			for (const record of toRollback) {
+				if (leaseLost()) throw new Error("MigrationRunner: refusing to start the next rollback — lock ownership lost.");
+				const migration = migrations.find((m) => m.resource === record.resource && m.version === record.version);
+				if (!migration) throw new Error(`Migration ${record.resource}:${record.version} not found`);
+				await this.runMigration(migration, "down", true);
+			}
+			this.log.info("Rollback completed");
+		});
 	}
 	/**
 	* Get all applied migrations
@@ -154,7 +306,7 @@ var MigrationRunner = class {
 				if (migration.validate) {
 					if (!await migration.validate(this.db)) throw new Error("Migration validation failed");
 				}
-				await this.store.record(migration, Date.now() - start);
+				await this.store.record(migration, Date.now() - start, { checksum: computeMigrationChecksum(migration) });
 			} else {
 				await migration.down(this.db);
 				if (isRollback) await this.store.remove(migration);
@@ -232,4 +384,4 @@ var MigrationRegistry = class {
 	}
 };
 //#endregion
-export { MigrationRegistry, MigrationRunner, MongoMigrationStore, defineMigration, withSchemaVersion };
+export { MigrationRegistry, MigrationRunner, MongoMigrationStore, computeMigrationChecksum, defineMigration, withSchemaVersion };

package/dist/{multipartBody-CHEQSZ6G.mjs → multipartBody-D0eBvkeq.mjs}

@@ -2,6 +2,7 @@ import sjson from "secure-json-parse";
 //#region src/middleware/multipartBody.ts
 const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
 const DEFAULT_MAX_FILES = 5;
+const DEFAULT_MAX_TOTAL_BYTES = 25 * 1024 * 1024;
 const DEFAULT_FILES_KEY = "_files";
 /**
 * Build a matcher for MIME allow-lists that supports exact (e.g. `image/png`),
@@ -45,10 +46,19 @@ function buildMimeMatcher(allowed) {
 * For non-multipart requests (regular JSON), this is a no-op — the request
 * passes through unchanged. This makes it safe to add to create/update
 * middlewares without breaking JSON clients.
+*
+* **BUFFERED — for small uploads only.** Every accepted file is held fully
+* in process memory for the request's lifetime; memory cost is
+* `concurrency × maxTotalBytes`. Suitable for avatars, documents, and
+* form attachments. For large files use PRESIGNED direct-to-object-storage
+* uploads (see the files-upload preset / production guide) and pair upload
+* routes with strict rate limits — buffering video through the app tier is
+* the wrong architecture regardless of limits.
 */
 function multipartBody(options = {}) {
 	const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
 	const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+	const maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
 	const mimeMatcher = buildMimeMatcher(options.allowedMimeTypes);
 	const filesKey = options.filesKey ?? DEFAULT_FILES_KEY;
 	const requiredFields = options.requiredFields && options.requiredFields.length > 0 ? options.requiredFields : void 0;
@@ -61,6 +71,7 @@ function multipartBody(options = {}) {
 		const body = {};
 		const files = {};
 		let fileCount = 0;
+		let totalBytes = 0;
 		try {
 			const parts = request.parts();
 			for await (const part of parts) if (part.type === "file") {
@@ -76,6 +87,12 @@ function multipartBody(options = {}) {
 					message: `File '${part.filename}' exceeds maximum size of ${Math.round(maxFileSize / 1024 / 1024)}MB`,
 					status: 413
 				});
+				totalBytes += buffer.length;
+				if (totalBytes > maxTotalBytes) return reply.code(413).send({
+					code: "arc.payload_too_large",
+					message: `Combined upload size exceeds ${Math.round(maxTotalBytes / 1024 / 1024)}MB per request`,
+					status: 413
+				});
 				files[part.fieldname] = {
 					filename: part.filename,
 					mimetype: part.mimetype,

package/dist/{openapi-jSDx-VDv.mjs → openapi-DrLtog_B.mjs}

@@ -1,8 +1,8 @@
-import { t as getUserRoles } from "./types-XTApa8b6.mjs";
+import { n as getUserRoles } from "./userHelpers-Cg_y3fBz.mjs";
 import { n as convertRouteSchema } from "./schemaConverter-DJvodiHj.mjs";
-import { t as resolveActionPermission } from "./actionPermissions-lszoJle1.mjs";
 import { t as pluralize } from "./pluralize-BhrgwZb9.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-BuOv-m4Y.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-CAphcmUG.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-B6GvAuAX.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi/canonical-schemas.ts
 /**

package/dist/permissions/index.d.mts

@@ -1,4 +1,4 @@
-import { a as getUserRoles, i as UserBase, n as PermissionContext, o as normalizeRoles, r as PermissionResult, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { i as UserBase, n as PermissionContext, o as getUserRoles, r as PermissionResult, s as normalizeRoles, t as PermissionCheck } from "../types-Dmw-6Qeo.mjs";
 import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-D3lhgzhD.mjs";
-import { A as allOf, B as applyPermissionResult, C as requireGrant, D as PermissionEventBus, E as DynamicPermissionMatrixConfig, F as requireAuth, G as requireDPoP, H as RequireAgentScopeOptions, I as requireOwnership, K as requireMandate, L as requireRoles, M as anyOf, N as denyAll, O as createDynamicPermissionMatrix, P as not, R as roles, S as modeSatisfies, T as DynamicPermissionMatrix, U as RequireMandateOptions, V as normalizePermissionResult, W as requireAgentScope, _ as createRoleHierarchy, a as permissionMatrix, b as GrantResolution, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, j as allowPublic, k as createOrgPermissions, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, v as GRANT_MODES, w as ConnectEventsOptions, x as RequireGrantOptions, y as GrantMode, z as when } from "../index-wMoWBLkn.mjs";
+import { A as allOf, B as applyPermissionResult, C as requireGrant, D as PermissionEventBus, E as DynamicPermissionMatrixConfig, F as requireAuth, G as requireDPoP, H as RequireAgentScopeOptions, I as requireOwnership, K as requireMandate, L as requireRoles, M as anyOf, N as denyAll, O as createDynamicPermissionMatrix, P as not, R as roles, S as modeSatisfies, T as DynamicPermissionMatrix, U as RequireMandateOptions, V as normalizePermissionResult, W as requireAgentScope, _ as createRoleHierarchy, a as permissionMatrix, b as GrantResolution, c as publicReadAdminWrite, d as requireOrgMembership, f as requireOrgRole, g as RoleHierarchy, h as requireTeamMembership, i as ownerWithAdminBypass, j as allowPublic, k as createOrgPermissions, l as readOnly, m as requireServiceScope, n as authenticated, o as presets_d_exports, p as requireScopeContext, r as fullPublic, s as publicRead, t as adminOnly, u as requireOrgInScope, v as GRANT_MODES, w as ConnectEventsOptions, x as RequireGrantOptions, y as GrantMode, z as when } from "../index-BMnbzvtO.mjs";
 export { type ConnectEventsOptions, type DynamicPermissionMatrix, type DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, GRANT_MODES, type GrantMode, type GrantResolution, type PermissionCheck, type PermissionContext, type PermissionEventBus, type PermissionResult, type RequireAgentScopeOptions, type RequireGrantOptions, type RequireMandateOptions, type RoleHierarchy, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, modeSatisfies, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/permissions/index.mjs

@@ -1,4 +1,4 @@
+import { n as getUserRoles, r as normalizeRoles } from "../userHelpers-Cg_y3fBz.mjs";
 import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, o as fields, r as normalizePermissionResult, s as resolveEffectiveRoles, t as applyPermissionResult } from "../applyPermissionResult-Tw4iXtlf.mjs";
-import { n as normalizeRoles, t as getUserRoles } from "../types-XTApa8b6.mjs";
-import { A as roles, C as allowPublic, D as requireAuth, E as not, M as requireAgentScope, N as requireDPoP, O as requireOwnership, P as requireMandate, S as allOf, T as denyAll, _ as requireOrgMembership, a as permissionMatrix, b as requireServiceScope, c as publicReadAdminWrite, d as GRANT_MODES, f as modeSatisfies, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as when, k as requireRoles, l as readOnly, m as createDynamicPermissionMatrix, n as authenticated, o as presets_exports, p as requireGrant, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as requireOrgRole, w as anyOf, x as requireTeamMembership, y as requireScopeContext } from "../permissions-tbxFHxjZ.mjs";
+import { A as requireAuth, C as requireDPoP, D as anyOf, E as allowPublic, M as requireRoles, N as roles, O as denyAll, P as when, S as requireAgentScope, T as allOf, _ as requireOrgMembership, a as permissionMatrix, b as requireServiceScope, c as publicReadAdminWrite, d as GRANT_MODES, f as modeSatisfies, g as requireOrgInScope, h as createOrgPermissions, i as ownerWithAdminBypass, j as requireOwnership, k as not, l as readOnly, m as createDynamicPermissionMatrix, n as authenticated, o as presets_exports, p as requireGrant, r as fullPublic, s as publicRead, t as adminOnly, u as createRoleHierarchy, v as requireOrgRole, w as requireMandate, x as requireTeamMembership, y as requireScopeContext } from "../permissions-BrtiBKGs.mjs";
 export { GRANT_MODES, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, modeSatisfies, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, permissionMatrix, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAgentScope, requireAuth, requireDPoP, requireGrant, requireMandate, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };