cvx-kit 0.0.2 → 0.0.3

package/src/tenancy.ts

@@ -0,0 +1,110 @@
+import {
+	wrapDatabaseReader,
+	wrapDatabaseWriter,
+	type RLSConfig,
+	type Rules,
+} from 'convex-helpers/server/rowLevelSecurity'
+import type {
+	GenericDataModel,
+	TableNamesInDataModel,
+} from 'convex/server'
+import { defaultErrors, type ErrorFactory } from './errors'
+
+export { wrapDatabaseReader, wrapDatabaseWriter }
+export type { RLSConfig, Rules }
+
+/** The server-owned tenancy field stamped on every tenant table row. */
+export const TENANT_FIELD = 'tenant' as const
+
+type TenantRow = { [TENANT_FIELD]?: unknown }
+
+/**
+ * Deny-oriented row-level security rules generated mechanically from a table
+ * registry: read/insert/modify pass only when the row's tenant matches.
+ * Registering a table here is the entire onboarding — there is no second
+ * per-table step to forget.
+ */
+export function createTenantRules<DataModel extends GenericDataModel>(
+	tenant: string,
+	tables: readonly TableNamesInDataModel<DataModel>[],
+): Rules<unknown, DataModel> {
+	const owned = async (_ctx: unknown, doc: TenantRow) =>
+		doc[TENANT_FIELD] === tenant
+	return Object.fromEntries(
+		tables.map((table) => [
+			table,
+			{ read: owned, insert: owned, modify: owned },
+		]),
+	) as unknown as Rules<unknown, DataModel>
+}
+
+/**
+ * AND-composes rule sets: a row passes an operation only when every rule set
+ * that defines a rule for it passes. Lets tenant isolation and role-level
+ * rules coexist on the same wrapped database.
+ */
+export function composeRules<Ctx, DataModel extends GenericDataModel>(
+	...sets: readonly Rules<Ctx, DataModel>[]
+): Rules<Ctx, DataModel> {
+	const tables = new Set(sets.flatMap((set) => Object.keys(set)))
+	const composed: Record<string, Record<string, unknown>> = {}
+	for (const table of tables) {
+		const operations: Record<string, unknown> = {}
+		for (const operation of ['read', 'insert', 'modify'] as const) {
+			const rules = sets
+				.map((set) => (set as Record<string, Record<string, unknown>>)[table])
+				.map((tableRules) => tableRules?.[operation])
+				.filter((rule): rule is (ctx: Ctx, doc: never) => Promise<boolean> =>
+					typeof rule === 'function',
+				)
+			if (rules.length === 0) continue
+			operations[operation] = async (ctx: Ctx, doc: never) => {
+				for (const rule of rules) {
+					if (!(await rule(ctx, doc))) return false
+				}
+				return true
+			}
+		}
+		composed[table] = operations
+	}
+	return composed as Rules<Ctx, DataModel>
+}
+
+/**
+ * Loads a client-referenced document and verifies tenant ownership without
+ * disclosing existence: a missing row and a foreign row fail identically
+ * with REFERENCE_NOT_FOUND. Use for every id argument a client supplies.
+ */
+export async function requireTenantReference<
+	Document extends { [TENANT_FIELD]?: unknown },
+>(
+	tenant: string,
+	load: () => Promise<Document | null>,
+	errors: ErrorFactory = defaultErrors,
+): Promise<Document> {
+	const document = await load()
+	if (!document || document[TENANT_FIELD] !== tenant) {
+		return errors.throw({
+			code: 'REFERENCE_NOT_FOUND',
+			message: 'The referenced row is unavailable',
+		})
+	}
+	return document
+}
+
+/** Asserts a loaded document belongs to the tenant; use on internal paths. */
+export function assertTenantOwned<
+	Document extends { [TENANT_FIELD]?: unknown },
+>(
+	tenant: string,
+	document: Document,
+	errors: ErrorFactory = defaultErrors,
+): Document {
+	if (document[TENANT_FIELD] !== tenant) {
+		return errors.throw({
+			code: 'CROSS_TENANT_REFERENCE',
+			message: 'The document belongs to another tenant',
+		})
+	}
+	return document
+}

package/src/triggers.ts

@@ -54,6 +54,40 @@ export function noDelete<DataModel extends GenericDataModel>(
 	}
 }
 
+/**
+ * Post-image tenant invariant for tenantTable rows. Row-level security
+ * authorizes a modification against the PRE-image, so ownership must also be
+ * enforced against the post-image: inserts must carry a tenant, and updates
+ * may never reassign it. Register for every tenant table (same registry that
+ * drives createTenantRules).
+ */
+export function tenantOwnership<DataModel extends GenericDataModel>(
+	triggers: Triggers<DataModel>,
+	...tables: readonly TableNamesInDataModel<DataModel>[]
+) {
+	for (const table of tables) {
+		triggers.register(table, async (_ctx, change) => {
+			if (change.operation === 'insert') {
+				const document = change.newDoc as { tenant?: unknown }
+				if (
+					typeof document.tenant !== 'string' ||
+					document.tenant.length === 0
+				) {
+					throw new Error(`${table} rows require a tenant`)
+				}
+				return
+			}
+			if (change.operation === 'update') {
+				const previous = change.oldDoc as { tenant?: unknown }
+				const current = change.newDoc as { tenant?: unknown }
+				if (previous.tenant !== current.tenant) {
+					throw new Error(`${table} tenant ownership cannot be reassigned`)
+				}
+			}
+		})
+	}
+}
+
 /**
  * Maintains zod-table's opinionated lifecycle timestamps: createdAt and
  * updatedAt on insert, updatedAt on every update. archivedAt stays under

package/src/zod-table.ts

@@ -138,6 +138,92 @@ export function zodTable<
 	}
 }
 
+const tenantShape = {
+	tenant: z.string().min(1),
+} satisfies Shape
+
+type TenantShape = typeof tenantShape
+
+/**
+ * A zodTable whose rows are tenant-owned: injects the server-owned `tenant`
+ * field (the tenancy boundary — see cvx-kit/tenancy). Like timestamps, it is
+ * excluded from insert/update/command boundaries; handlers stamp it from
+ * ctx.tenant, row-level security matches on it, and the tenantOwnership
+ * trigger forbids reassigning it. Expose it via publicFields only when a DTO
+ * genuinely needs it.
+ */
+export function tenantTable<
+	Table extends string,
+	Fields extends Shape,
+	const ServerFields extends readonly ShapeKey<Fields>[] = readonly [],
+	const CommandFields extends readonly ShapeKey<Fields>[] = readonly [],
+	const PublicFields extends readonly ShapeKey<
+		Fields & TenantShape & TimestampShape
+	>[] = readonly [],
+>(
+	tableName: Table,
+	fields: (id: typeof zid) => Fields,
+	options: TableBoundaryOptions<
+		Fields & TenantShape,
+		readonly (ServerFields[number] | 'tenant')[],
+		CommandFields,
+		PublicFields
+	> = {},
+) {
+	return zodTable(
+		tableName,
+		(id) => ({ ...fields(id), ...tenantShape }),
+		{
+			...options,
+			serverFields: [
+				...((options.serverFields ?? []) as readonly (
+					| ServerFields[number]
+					| 'tenant'
+				)[]),
+				'tenant',
+			] as never,
+		} as never,
+	) as ReturnType<
+		typeof zodTable<
+			Table,
+			Fields & TenantShape,
+			readonly (ServerFields[number] | 'tenant')[],
+			CommandFields,
+			PublicFields
+		>
+	>
+}
+
+/**
+ * Merges per-module table maps into the application schema map, rejecting
+ * duplicate table names across modules — the module-registry combinator for
+ * domain/table.ts: `defineSchema(createModule(catalogTables, salesTables))`.
+ */
+export function createModule<
+	const Maps extends readonly Record<string, TableDefinition<any>>[],
+>(...maps: Maps): UnionToIntersection<Maps[number]> {
+	const combined: Record<string, TableDefinition<any>> = {}
+	for (const map of maps) {
+		for (const [tableName, definition] of Object.entries(map)) {
+			if (tableName in combined) {
+				throw new Error(
+					`Table "${tableName}" is declared by more than one module`,
+				)
+			}
+			combined[tableName] = definition
+		}
+	}
+	return combined as UnionToIntersection<Maps[number]>
+}
+
+type UnionToIntersection<Union> = (
+	Union extends unknown
+		? (member: Union) => void
+		: never
+) extends (member: infer Intersection) => void
+	? Intersection
+	: never
+
 /** Preserves discriminated-union storage while retaining the same table owner. */
 export function zodVariantTable<Table extends string, Schema extends z.ZodType>(
 	tableName: Table,