cvx-kit 0.0.1 → 0.0.3

package/docs/zod-table.md

@@ -0,0 +1,173 @@
+# `cvx-kit/zod-table` — one zod shape per entity, masked into every boundary
+
+The core idea: an entity's shape is declared **once** as a zod object, and every
+boundary that shape crosses — storage, insert, update, command input, public
+DTO, LLM tool input — is a *derived mask* of that single declaration. There is
+no second source of truth to drift.
+
+```ts
+import { z } from 'zod'
+import { zodTable } from 'cvx-kit/zod-table'
+
+export const documents = zodTable(
+  'documents',
+  (id) => ({
+    title: z.string(),
+    ownerId: id('users'),        // `id` is convex-helpers' zid — typed Id<'users'>
+    secretNote: z.string(),
+    reviewState: z.enum(['draft', 'published']),
+  }),
+  {
+    serverFields: ['reviewState'],       // excluded from inserts — server assigns it
+    commandFields: ['title'],            // the ONLY fields a command may carry
+    publicFields: ['title', 'ownerId'],  // the DTO allowlist — everything else is redacted
+  },
+)
+```
+
+## What you get back
+
+| Property | What it is | Where you use it |
+|---|---|---|
+| `table` | `defineTable(...)` from the storage shape | `convex/schema.ts` |
+| `storage` | zod object of the raw row (no `_id`/`_creationTime`) | validating rows |
+| `schema` | `storage` + `_id` + `_creationTime` | full-document validation |
+| `insertSchema` | storage minus timestamps minus `serverFields` | mutation args |
+| `updateSchema` | `insertSchema.partial()` | patch mutation args |
+| `commandInput` | strict pick of `commandFields` | command protocol inputs |
+| `publicDto` | strict pick of `publicFields` | query return validators |
+| `toPublicDto(row)` | projects **and re-parses** a row into the DTO | query handlers |
+| `insert(omit?)` / `update(omit?)` | schema with per-callsite field omission | specialized mutations |
+| `tools.insert` / `tools.update` / `tools.id` | ready-made LLM tool input schemas | agent tool definitions |
+| `tableName` | the literal table name | indexes, triggers registration |
+
+## Redaction is runtime, not just types
+
+`toPublicDto` does not merely `pick` at the type level — it re-parses the
+projected object through the strict `publicDto` schema. A field that leaks into
+the projection throws instead of shipping to the client. Use it on **every**
+row a public query returns:
+
+```ts
+export const get = authQuery({
+  args: { id: zid('documents') },
+  returns: documents.publicDto,
+  handler: async (ctx, { id }) => {
+    const row = await ctx.db.get(id)
+    if (!row) throw new KitError({ code: 'NOT_FOUND' })
+    return documents.toPublicDto(row) // secretNote can never leak
+  },
+})
+```
+
+## Opinionated timestamps
+
+Every `zodTable` bakes in three optional, **server-owned** fields:
+
+- `createdAt` — set once on insert
+- `updatedAt` — moved on every update
+- `archivedAt` — soft-delete marker, under application control
+
+They are always excluded from `insertSchema`, `updateSchema`, and
+`commandInput` — a client or command can never write them. They are *not* in
+`publicFields` by default; list them explicitly when a DTO needs them
+(`publicFields: ['title', 'createdAt']`).
+
+They maintain themselves only if you register the `timestamps` trigger once
+per table (see `triggers.md`). Without the trigger they stay `undefined`.
+
+Prefer `createdAt` over `_creationTime` in DTOs so the whole lifecycle
+vocabulary is yours; `_creationTime` remains available for index ordering.
+
+## Field masks — who sees what
+
+Think of the options as three independent allowlists over the same shape:
+
+- `serverFields` — *the server assigns these.* Excluded from `insertSchema`
+  and `updateSchema`. Example: `reviewState`, denormalized counters.
+- `commandFields` — *a command may say these.* The command protocol's input
+  is exactly this pick, strict. Everything else must be derived by the handler.
+- `publicFields` — *a client may see these.* The DTO is exactly this pick;
+  may include timestamp fields.
+
+All derived objects are `.strict()` — unknown keys are rejected, in both
+directions.
+
+## `tenantTable` — tenant-owned rows
+
+`tenantTable` is `zodTable` plus a server-owned `tenant` string field —
+injected exactly like timestamps: present in storage, excluded from
+`insertSchema`/`updateSchema`/`commandInput`, in `publicDto` only by explicit
+allowlist. Handlers stamp it from `ctx.tenant`; row-level security matches on
+it; the `tenantOwnership` trigger forbids reassigning it. See `tenancy.md`.
+
+```ts
+export const <entities> = tenantTable('<entities>', (id) => ({ ... }), {
+  commandFields: [...], publicFields: [...],
+})
+```
+
+## `createModule` — module table maps
+
+Merges per-module table maps into the application schema, throwing when two
+modules declare the same table — the combinator for `domain/table.ts`:
+
+```ts
+export default defineSchema(createModule(<moduleA>Tables, <moduleB>Tables))
+```
+
+## `zodVariantTable` — discriminated unions
+
+For tables whose rows are a discriminated union (events, polymorphic
+resources), `zodTable`'s object-shape model doesn't apply. `zodVariantTable`
+keeps the same "one owner per table" convention while accepting any zod type
+as storage:
+
+```ts
+const events = zodVariantTable('events', z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('created'), by: zid('users') }),
+  z.object({ kind: z.literal('archived'), reason: z.string() }),
+]))
+// events.table → defineTable, events.insertSchema → the union itself
+```
+
+Note: variant tables do not get the timestamp fields or boundary masks — the
+union is the boundary.
+
+## `jsonSafeZid` — Ids in LLM tool schemas
+
+JSON-schema generators turn `zid('users')` into an opaque custom type that
+confuses LLM tool calling. `jsonSafeZid('users')` presents as a plain
+described string in the generated JSON schema while keeping `Id<'users'>` at
+the type level:
+
+```ts
+const assignInput = z.object({
+  documentId: jsonSafeZid('documents'), // LLM sees: string, "Convex document id for table \"documents\""
+})
+```
+
+## Wiring into `schema.ts`
+
+```ts
+// convex/schema.ts
+import { defineSchema } from 'convex/server'
+import { documents } from './tables/documents'
+
+export default defineSchema({
+  documents: documents.table
+    .index('by_owner', ['ownerId'])
+    .index('by_owner_archived', ['ownerId', 'archivedAt']),
+})
+```
+
+Indexes are chained on `.table` exactly like a hand-written `defineTable`.
+
+## Rules of thumb
+
+1. One `zodTable` per entity, in its own module, exported by name.
+2. Never define an inline `defineTable` or a second zod object for the same
+   entity — masks only.
+3. Every public query returns `publicDto`-shaped data via `toPublicDto`.
+4. Every command input is `commandInput` (or a documented composition of it).
+5. Timestamps are trigger-maintained; handlers never write them.

package/package.json

@@ -1,13 +1,15 @@
 {
 	"name": "cvx-kit",
-	"version": "0.0.1",
+	"version": "0.0.3",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
 	"type": "module",
 	"license": "MIT",
 	"sideEffects": false,
 	"files": [
 		"dist",
-		"src"
+		"src",
+		"!src/docs",
+		"docs"
 	],
 	"exports": {
 		"./package.json": "./package.json",
@@ -23,6 +25,10 @@
 			"types": "./dist/auth.d.mts",
 			"import": "./dist/auth.mjs"
 		},
+		"./tenancy": {
+			"types": "./dist/tenancy.d.mts",
+			"import": "./dist/tenancy.mjs"
+		},
 		"./triggers": {
 			"types": "./dist/triggers.d.mts",
 			"import": "./dist/triggers.mjs"
@@ -67,7 +73,8 @@
 		"build": "vp pack",
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run",
-		"prepublishOnly": "bun run typecheck && bun run test && bun run build",
+		"docs:sync": "rm -f docs/*.md && cp src/docs/*.md docs/",
+		"prepublishOnly": "bun run typecheck && bun run test && bun run build && bun run docs:sync",
 		"build:codegen": "convex codegen --component-dir ./src/components/foundation && convex codegen --component-dir ./src/components/approvals && vp pack",
 		"release": "npm version patch && git push --follow-tags",
 		"release:minor": "npm version minor && git push --follow-tags"

package/src/auth.ts

@@ -22,7 +22,16 @@ import type {
 	UserIdentity,
 } from 'convex/server'
 import type { Triggers } from 'convex-helpers/server/triggers'
+import type { TableNamesInDataModel } from 'convex/server'
 import { defaultErrors, type ErrorFactory } from './errors'
+import {
+	composeRules,
+	createTenantRules,
+	wrapDatabaseReader,
+	wrapDatabaseWriter,
+	type RLSConfig,
+	type Rules,
+} from './tenancy'
 
 /** The default vocabulary; every app can supply its own via the Role generic. */
 export type DefaultRole = 'reader' | 'writer' | 'admin'
@@ -39,8 +48,43 @@ export type AuthBundle<Role extends string> = Readonly<{
 	org: Readonly<{ organizationId: string; role: Role }>
 	role: Role
 	actor: Actor<Role>
+	/** The resolved tenant — security.tenancy.resolve, or the organization id. */
+	tenant: string
 }>
 
+/**
+ * Row-level security configuration. Tenant isolation and role-level rules
+ * compose (AND) onto the same wrapped database: queries get a wrapped
+ * reader, mutations get triggers first, then a wrapped writer.
+ */
+export type SecurityConfig<
+	DataModel extends GenericDataModel,
+	Role extends string,
+> = {
+	/**
+	 * Tenant isolation. `tables` is THE registry: every listed table gets
+	 * read/insert/modify gated on row.tenant === ctx.tenant. Pair with
+	 * tenantTable (schema) and tenantOwnership (triggers) on the same list.
+	 */
+	tenancy?: {
+		tables: readonly TableNamesInDataModel<DataModel>[]
+		/** Maps the auth bundle to the tenant; defaults to org.organizationId. */
+		resolve?: (bundle: Omit<AuthBundle<Role>, 'tenant'>) => string
+	}
+	/**
+	 * Role-level (or any policy) rules derived from the authenticated bundle,
+	 * composed AND-wise with tenant isolation. E.g. gate `modify` on a table
+	 * to admin roles.
+	 */
+	rules?: (bundle: AuthBundle<Role>) => Rules<unknown, DataModel>
+	/**
+	 * Policy for tables with no rule. Defaults to 'deny' when tenancy is
+	 * configured (unlisted tables are unreachable — fail closed), 'allow'
+	 * otherwise.
+	 */
+	defaultPolicy?: RLSConfig['defaultPolicy']
+}
+
 type AnyAuthContext<DataModel extends GenericDataModel> =
 	| GenericQueryCtx<DataModel>
 	| GenericMutationCtx<DataModel>
@@ -90,6 +134,12 @@ export type AuthFunctionsConfig<
 	) => GenericMutationCtx<DataModel>
 	/** Upper bound for include() reads. */
 	maxIncludedQueryRows?: number
+	/**
+	 * Row-level security: tenant isolation (from a table registry) and
+	 * role-level rules, applied structurally inside every auth*, role*, and
+	 * admin* constructor. system* constructors stay unwrapped (trusted).
+	 */
+	security?: SecurityConfig<DataModel, Role>
 }
 
 /** WorkOS-style default: `member` writes; reader/writer/admin pass through. */
@@ -223,15 +273,68 @@ export function createAuthFunctions<
 					: undefined
 		const role = config.mapRole(organizationRole)
 		if (!role) return errors.throw({ code: 'FORBIDDEN' })
-		return Object.freeze({
+		const base = {
 			identity,
 			user: Object.freeze({ id: user.id }),
 			org: Object.freeze({ organizationId, role }),
 			role,
 			actor: Object.freeze({ userId: user.id, organizationId, role }),
+		}
+		return Object.freeze({
+			...base,
+			tenant: config.security?.tenancy?.resolve?.(base) ?? organizationId,
 		})
 	}
 
+	const securityConfig: RLSConfig | undefined = config.security
+		? {
+				defaultPolicy:
+					config.security.defaultPolicy ??
+					(config.security.tenancy ? 'deny' : 'allow'),
+			}
+		: undefined
+
+	function securityRules(
+		bundle: AuthBundle<Role>,
+	): Rules<unknown, DataModel> | undefined {
+		const security = config.security
+		if (!security) return undefined
+		const sets: Rules<unknown, DataModel>[] = []
+		if (security.tenancy) {
+			sets.push(
+				createTenantRules<DataModel>(bundle.tenant, security.tenancy.tables),
+			)
+		}
+		if (security.rules) sets.push(security.rules(bundle))
+		return sets.length === 1 ? sets[0] : composeRules(...sets)
+	}
+
+	function secureReader(
+		ctx: GenericQueryCtx<DataModel>,
+		bundle: AuthBundle<Role>,
+	): GenericQueryCtx<DataModel> {
+		const rules = securityRules(bundle)
+		if (!rules) return ctx
+		return {
+			...ctx,
+			db: wrapDatabaseReader({}, ctx.db, rules as never, securityConfig),
+		}
+	}
+
+	function secureWriter(
+		ctx: GenericMutationCtx<DataModel>,
+		bundle: AuthBundle<Role>,
+	): GenericMutationCtx<DataModel> {
+		const rules = securityRules(bundle)
+		if (!rules) return ctx
+		// Triggers wrap first (ctx already trigger-wrapped by the caller),
+		// then row-level security wraps the triggered db — order matters.
+		return {
+			...ctx,
+			db: wrapDatabaseWriter({}, ctx.db, rules as never, securityConfig),
+		}
+	}
+
 	async function verifiedMembership(userId: string, organizationId: string) {
 		if (!config.verifyMembership) return null
 		try {
@@ -253,15 +356,17 @@ export function createAuthFunctions<
 	}
 
 	async function queryInput(ctx: GenericQueryCtx<DataModel>) {
+		const bundle = await authenticatedUser(ctx)
 		return {
-			ctx: { ...ctx, include, ...(await authenticatedUser(ctx)) },
+			ctx: { ...secureReader(ctx, bundle), include, ...bundle },
 			args: {},
 		}
 	}
 
 	async function mutationInput(ctx: GenericMutationCtx<DataModel>) {
+		const bundle = await authenticatedUser(ctx)
 		return {
-			ctx: { ...wrapDB(ctx), include, ...(await authenticatedUser(ctx)) },
+			ctx: { ...secureWriter(wrapDB(ctx), bundle), include, ...bundle },
 			args: {},
 		}
 	}
@@ -275,20 +380,28 @@ export function createAuthFunctions<
 		if (!membership) return { ctx: { ...ctx, ...authenticated }, args: {} }
 		const role = config.mapRole(membership.roleSlug)
 		if (!role) return errors.throw({ code: 'FORBIDDEN' })
+		const verified = {
+			identity: authenticated.identity,
+			user: authenticated.user,
+			org: Object.freeze({
+				organizationId: membership.organizationId,
+				role,
+			}),
+			role,
+			actor: Object.freeze({
+				userId: authenticated.user.id,
+				organizationId: membership.organizationId,
+				role,
+			}),
+		}
 		return {
 			ctx: {
 				...ctx,
-				...authenticated,
-				org: Object.freeze({
-					organizationId: membership.organizationId,
-					role,
-				}),
-				role,
-				actor: Object.freeze({
-					userId: authenticated.user.id,
-					organizationId: membership.organizationId,
-					role,
-				}),
+				...verified,
+				// Tenant re-derives from the live-verified organization.
+				tenant:
+					config.security?.tenancy?.resolve?.(verified) ??
+					membership.organizationId,
 			},
 			args: {},
 		}

package/src/components/foundation/client.ts

@@ -35,12 +35,41 @@ export type AuditedOperation = Readonly<{
 	command: Readonly<{ parse: (value: unknown) => unknown }>
 	result: Readonly<{ parse: (value: unknown) => unknown }>
 	classification: string
+	/**
+	 * Permission slug required to execute this operation. Checked through the
+	 * Foundation's injected checkPermission BEFORE guards and the handler;
+	 * declaring a permission without injecting a checker fails closed.
+	 */
+	permission?: string
+	/**
+	 * Per-operation precondition, after the permission check and the registry
+	 * default guard, before the handler. Throw to deny — nothing has run yet.
+	 */
+	guard?: (context: never, command: never) => MaybePromise<void>
+	/**
+	 * Allowlist of aggregate types this operation's audit may reference. When
+	 * declared, an audit entry whose aggregate.type is not listed throws —
+	 * the audit vocabulary is enforced, not advisory.
+	 */
+	aggregates?: readonly string[]
 	audit: (
 		resolution: Readonly<{ command: never; result: never }>,
 		context: never,
 	) => MaybePromise<Omit<AuditEntryInput, 'classification'> | null>
 }>
 
+/** Registry-wide defaults applied to every operation of one Command. */
+export type CommandDefaults = Readonly<{
+	/** Runs before every operation's own guard. Throw to deny. */
+	guard?: (context: never) => MaybePromise<void>
+}>
+
+/** Injected permission policy: throw to deny. Host semantics, kit ordering. */
+export type PermissionChecker = (
+	context: never,
+	input: Readonly<{ permission: string; operation: string }>,
+) => MaybePromise<void>
+
 export type AuditedRegistry = Readonly<Record<string, AuditedOperation>>
 
 export type FoundationOptions = Readonly<{
@@ -52,6 +81,12 @@ export type FoundationOptions = Readonly<{
 			 */
 			writeAudit?: AuditWriter
 		}>
+	/**
+	 * Permission policy for operations that declare a `permission`. Runs
+	 * before guards and the handler; throw to deny. An operation with a
+	 * permission but no injected checker fails closed.
+	 */
+	checkPermission?: PermissionChecker
 }>
 
 type FoundationComponentApi = Readonly<{
@@ -68,6 +103,13 @@ class BoundCommand<Context, const Operations extends AuditedRegistry> {
 	readonly #kernel: CommandKernelClass<Context, Operations>
 	readonly #observability: Observability
 	readonly #writeAudit: AuditWriter
+	readonly #checkPermission: PermissionChecker | undefined
+	readonly #defaults: CommandDefaults
+
+	/** Declared aggregate types per operation — introspectable for tests. */
+	readonly aggregates: Readonly<{
+		[Key in OperationKey<Operations>]: Operations[Key]['aggregates']
+	}>
 
 	static operation<const Definition extends AuditedOperation>(
 		definition: Definition,
@@ -77,10 +119,25 @@ class BoundCommand<Context, const Operations extends AuditedRegistry> {
 
 	constructor(
 		operations: Operations,
-		deps: { observability: Observability; writeAudit: AuditWriter },
+		deps: {
+			observability: Observability
+			writeAudit: AuditWriter
+			checkPermission?: PermissionChecker
+			defaults?: CommandDefaults
+		},
 	) {
 		this.#observability = deps.observability
 		this.#writeAudit = deps.writeAudit
+		this.#checkPermission = deps.checkPermission
+		this.#defaults = deps.defaults ?? {}
+		this.aggregates = Object.freeze(
+			Object.fromEntries(
+				Object.entries(operations).map(([operation, definition]) => [
+					operation,
+					definition.aggregates,
+				]),
+			),
+		) as this['aggregates']
 		this.#kernel = new CommandKernelClass<Context, Operations>({
 			operations,
 			execute: (execution) => this.#execute(execution),
@@ -106,12 +163,35 @@ class BoundCommand<Context, const Operations extends AuditedRegistry> {
 				classification: execution.definition.classification,
 			},
 			async () => {
+				// Guards run before the handler: permission → default → operation.
+				const permission = execution.definition.permission
+				if (permission !== undefined) {
+					if (!this.#checkPermission) {
+						throw new CommandPermissionError(execution.operation)
+					}
+					await this.#checkPermission(execution.context as never, {
+						permission,
+						operation: execution.operation,
+					})
+				}
+				await this.#defaults.guard?.(execution.context as never)
+				await execution.definition.guard?.(
+					execution.context as never,
+					execution.command as never,
+				)
 				const result = await execution.run()
 				const audit = await execution.definition.audit(
 					{ command: execution.command, result } as never,
 					execution.context as never,
 				)
 				if (audit) {
+					const allowed = execution.definition.aggregates
+					if (allowed && !allowed.includes(audit.aggregate.type)) {
+						throw new CommandAggregateError(
+							execution.operation,
+							audit.aggregate.type,
+						)
+					}
 					await this.#writeAudit(execution.context as never, {
 						...audit,
 						classification: execution.definition.classification,
@@ -123,6 +203,30 @@ class BoundCommand<Context, const Operations extends AuditedRegistry> {
 	}
 }
 
+/** The audit referenced an aggregate type outside the operation's allowlist. */
+class CommandAggregateError extends Error {
+	readonly code = 'COMMAND_AGGREGATE_NOT_DECLARED'
+	readonly name = 'CommandAggregateError'
+
+	constructor(operation: string, aggregateType: string) {
+		super(
+			`Operation "${operation}" audited aggregate type "${aggregateType}" outside its declared aggregates`,
+		)
+	}
+}
+
+/** Fails closed: an operation declared a permission but no checker exists. */
+class CommandPermissionError extends Error {
+	readonly code = 'COMMAND_PERMISSION_NOT_CONFIGURED'
+	readonly name = 'CommandPermissionError'
+
+	constructor(operation: string) {
+		super(
+			`Operation "${operation}" declares a permission but the Foundation has no checkPermission`,
+		)
+	}
+}
+
 export type ApplicationCommand<
 	Context,
 	Operations extends AuditedRegistry,
@@ -131,6 +235,7 @@ export type ApplicationCommand<
 type CommandConstructor = {
 	new <Context, const Operations extends AuditedRegistry>(
 		operations: Operations,
+		defaults?: CommandDefaults,
 	): BoundCommand<Context, Operations>
 	operation: (typeof BoundCommand)['operation']
 }
@@ -153,12 +258,18 @@ export class Foundation<
 		const observability = new Observability(options.observability)
 		this.observability = observability
 		const writeAudit = options.observability.writeAudit ?? (() => undefined)
+		const checkPermission = options.checkPermission
 		this.Command = class <
 			Context,
 			const Operations extends AuditedRegistry,
 		> extends BoundCommand<Context, Operations> {
-			constructor(operations: Operations) {
-				super(operations, { observability, writeAudit })
+			constructor(operations: Operations, defaults?: CommandDefaults) {
+				super(operations, {
+					observability,
+					writeAudit,
+					checkPermission,
+					defaults,
+				})
 			}
 		}
 	}

package/src/index.ts

@@ -4,12 +4,23 @@ export {
 	type ErrorFactory,
 } from './errors'
 export {
+	createModule,
 	jsonSafeZid,
+	tenantTable,
 	TIMESTAMP_FIELDS,
 	zodTable,
 	zodVariantTable,
 	type TableBoundaryOptions,
 } from './zod-table'
+export {
+	assertTenantOwned,
+	composeRules,
+	createTenantRules,
+	requireTenantReference,
+	TENANT_FIELD,
+	type RLSConfig,
+	type Rules,
+} from './tenancy'
 export {
 	createAuthFunctions,
 	createInclude,
@@ -20,9 +31,11 @@ export {
 	type DefaultRole,
 	type Include,
 	type IncludedQuery,
+	type SecurityConfig,
 } from './auth'
 export {
 	appendOnly,
+	tenantOwnership,
 	createTriggers,
 	noDelete,
 	timestamps,
@@ -37,5 +50,7 @@ export {
 	type AuditedRegistry,
 	type AuditEntryInput,
 	type AuditWriter,
+	type CommandDefaults,
 	type FoundationOptions,
+	type PermissionChecker,
 } from './components/foundation/client'