cvx-kit 0.0.2 → 0.0.4

package/docs/tenancy.md

@@ -0,0 +1,179 @@
+# `cvx-kit/tenancy` — row-level security, with tenancy as an opt-in layer
+
+Row-level security and tenancy are **separate, composable features** of the
+same `security` config on `createAuthFunctions`:
+
+- **`security.rules` alone** — role-level / module-level RLS with no tenancy
+  at all: gate writes by role, freeze evidence tables, ownership-gate reads.
+  `defaultPolicy` stays `'allow'`; unlisted tables behave normally.
+- **`security.tenancy` alone** — pure tenant isolation from a table registry.
+- **Both** — rules are AND-composed with tenant isolation.
+
+A single-org app that only wants role-gated writes configures `rules` and
+never touches tenancy. Nothing below is required unless you opt into it.
+
+Multi-tenancy itself is a structural machine, not a per-handler
+convention. The model: **tenant = the identity provider's organization id**,
+stamped as a server-owned `tenant` string field on every tenant-scoped row,
+always derived from the verified identity — never accepted as an argument.
+Isolation is defense-in-depth; each layer covers a hole in the previous one:
+
+1. **Schema** — `tenantTable` injects the field and strips it from every
+   write boundary.
+2. **Row-level security** — deny-default rules generated mechanically from
+   one table registry, wrapped into the auth constructors.
+3. **Triggers** — a post-image invariant forbids tenant reassignment (RLS
+   authorizes against the pre-image only).
+4. **Reference guards** — client-supplied ids re-verify ownership without
+   disclosing existence.
+
+Single-org apps skip all of this: every piece is opt-in, and
+`createAuthFunctions` without a `security` config behaves exactly as before.
+
+## The registry is the design
+
+One list of table names drives everything. Adding a table to the registry is
+the entire onboarding — there is no second per-table step to forget:
+
+```ts
+// convex/tenancy.ts (or alongside triggers.ts)
+export const TENANT_TABLES = ['<entities>', '<others>'] as const
+```
+
+- `security.tenancy.tables: TENANT_TABLES` → RLS rules generated per table
+- `tenantOwnership(triggers, ...TENANT_TABLES)` → reassignment guard per table
+- each listed table is declared with `tenantTable(...)` in its module
+
+Recommended architecture test: assert every `tenantTable` in the codebase
+appears in `TENANT_TABLES`, and vice versa.
+
+## Wiring
+
+```ts
+// domain/<module>/schema.ts — tenant injected at the schema boundary
+export const <entities> = tenantTable('<entities>', (id) => ({
+  name: z.string(), ownerId: id('users'),
+}), { publicFields: ['name'] })
+// tenant: excluded from insertSchema/updateSchema/commandInput,
+// in publicDto only if explicitly allowlisted
+
+// domain/<module>/table.ts — every index tenant-prefixed
+<entities>: <entities>.table.index('by_tenant', ['tenant'])
+                            .index('by_tenant_owner', ['tenant', 'ownerId'])
+
+// convex/triggers.ts
+tenantOwnership(triggers, ...TENANT_TABLES)
+
+// convex/functions.ts
+createAuthFunctions<DataModel>({
+  ...,
+  security: {
+    tenancy: {
+      tables: TENANT_TABLES,
+      // optional; defaults to bundle.org.organizationId
+      resolve: (bundle) => bundle.org.organizationId,
+    },
+    // role-level security, AND-composed with tenant isolation
+    rules: (bundle) => ({
+      '<entities>': { modify: async () => bundle.role === '<privileged>' },
+    }),
+    // defaults to 'deny' when tenancy is configured
+    defaultPolicy: 'deny',
+  },
+})
+```
+
+## What the constructors do with it
+
+- Every authenticated ctx gains **`ctx.tenant`** (also on the frozen bundle) —
+  resolved via `security.tenancy.resolve`, defaulting to the organization id.
+  Actions re-derive it from the live-verified membership.
+- **Queries** get a wrapped reader: rows failing `read` are invisible —
+  filtered from every `get`/`query`, even a full table scan.
+- **Mutations** wrap triggers first, then the RLS writer — `insert`/`modify`
+  failing a rule throws. Order matters and is handled for you.
+- **`system*` constructors stay unwrapped** — trusted internal paths reach
+  every table. This is deliberate: schedulers and callbacks receive the
+  server-derived tenant as data, never as authority.
+- With tenancy configured, `defaultPolicy` defaults to **deny**: tables
+  outside the registry are unreachable from `auth*`/`role*`/`admin*`
+  functions. Global/platform tables are reached from `system*` paths, or by
+  explicitly granting rules for them.
+
+Handlers stamp inserts from the ctx — the schema forbids clients supplying
+it, RLS rejects a wrong value, and the trigger forbids changing it later:
+
+```ts
+await ctx.db.insert('<entities>', { ...args, tenant: ctx.tenant })
+```
+
+## Role-level security — with or without tenancy
+
+`security.rules` receives the full auth bundle and returns convex-helpers
+`Rules`. It works standalone (no tenancy configured) or AND-composed with
+tenant isolation (`composeRules`) — a row must pass **every** rule set that
+defines the operation. Use it for role-gated writes, ownership-gated reads,
+or state-machine write locks:
+
+```ts
+// rules-only, single-org app: no tenancy anywhere
+security: {
+  rules: (bundle) => ({
+    '<entities>': { modify: async () => bundle.role !== '<readonly-role>' },
+  }),
+}
+```
+
+```ts
+rules: (bundle) => ({
+  '<entities>': {
+    modify: async (_ctx, doc) =>
+      bundle.role === 'admin' || doc.ownerId === bundle.actor.userId,
+  },
+  '<evidence>': { modify: async () => false },   // frozen via RLS as well as trigger
+})
+```
+
+## Client-supplied ids
+
+RLS makes foreign rows invisible to reads, but any id a client sends should
+still be re-verified — and without disclosing existence:
+
+```ts
+import { requireTenantReference } from 'cvx-kit/tenancy'
+
+const row = await requireTenantReference(ctx.tenant, () => ctx.db.get(args.id))
+// missing row and foreign row fail identically: REFERENCE_NOT_FOUND
+```
+
+`assertTenantOwned(tenant, doc)` is the internal-path variant
+(CROSS_TENANT_REFERENCE, for rows you already loaded on trusted paths).
+
+## Footguns
+
+1. **Actions have no db** — an action passing work to internal functions must
+   pass `ctx.tenant` (server-derived) as data; internal functions must never
+   accept a caller-chosen tenant on a public path.
+2. **Provider ids are global** (memberships, invitations in WorkOS-style
+   providers): org-scoped mutations against the provider must re-check the
+   id belongs to the active org, or you ship a cross-tenant IDOR.
+3. **Tables outside the registry get none of this.** Keep the global-table
+   list short and named; every one is a per-handler-discipline zone.
+4. **`t.run(...)` in convex-test bypasses RLS and triggers** — same rule as
+   always: seeding only.
+5. **Return "not found", never "forbidden"** for cross-tenant references —
+   existence is also tenant data.
+
+## Module maps
+
+`createModule` (from `cvx-kit/zod-table`) merges per-module table maps into
+the schema and rejects a table declared by two modules:
+
+```ts
+// convex/domain/table.ts
+export const domainTables = createModule(
+  <moduleA>Tables, <moduleB>Tables, <moduleC>Tables,
+)
+// convex/schema.ts
+export default defineSchema(domainTables)
+```

package/docs/triggers.md

@@ -48,6 +48,11 @@ createAuthFunctions<DataModel>({ ..., triggers })
   votes/history/audit-style evidence tables.
 - **`noDelete(triggers, ...tables)`** — forbids hard deletes only; updates
   pass. Pair with `archivedAt` for soft deletion.
+- **`tenantOwnership(triggers, ...tables)`** — the tenancy post-image
+  invariant: inserts must carry a non-empty `tenant`, updates may never
+  reassign it. Register for every table in the tenancy registry (row-level
+  security checks the pre-image only — this closes that hole). See
+  `tenancy.md`.
 
 `Triggers`, `Change`, and `Trigger` are re-exported for custom registrations.
 

package/docs/zod-table.md

@@ -93,6 +93,29 @@ Think of the options as three independent allowlists over the same shape:
 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

package/package.json

@@ -1,16 +1,10 @@
 {
 	"name": "cvx-kit",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"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/docs",
-		"docs"
-	],
 	"exports": {
 		"./package.json": "./package.json",
 		".": {
@@ -25,6 +19,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"
@@ -70,7 +68,7 @@
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run",
 		"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",
+		"prepublishOnly": "bun run build && bun run typecheck && bun run test && 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/test.ts

@@ -2,16 +2,18 @@
  * Test helpers for consumers, following the official component template:
  * register the kit's components on a convex-test instance so host-app tests
  * run against them in-memory. Requires a vitest-compatible runner
- * (import.meta.glob), which is why this export ships as source.
+ * (import.meta.glob), which is why this file ships as source — but it
+ * registers the COMPILED component modules from dist, so dist is the only
+ * code the package ships.
  */
-import approvalsSchema from './components/approvals/schema'
-import foundationSchema from './components/foundation/schema'
+import approvalsSchema from '../dist/components/approvals/schema.mjs'
+import foundationSchema from '../dist/components/foundation/schema.mjs'
 
 const foundationModules = import.meta.glob(
-	'./components/foundation/**/!(*.test).ts',
+	'../dist/components/foundation/**/*.mjs',
 )
 const approvalsModules = import.meta.glob(
-	'./components/approvals/**/!(*.test).ts',
+	'../dist/components/approvals/**/*.mjs',
 )
 
 type RegistersComponents = {

package/src/auth.ts

@@ -1,360 +0,0 @@
-import {
-	zCustomAction,
-	zCustomMutation,
-	zCustomQuery,
-} from 'convex-helpers/server/zod4'
-import type {
-	ActionBuilder,
-	DocumentByInfo,
-	GenericActionCtx,
-	GenericDataModel,
-	GenericMutationCtx,
-	GenericQueryCtx,
-	GenericTableInfo,
-	IndexNames,
-	IndexRange,
-	IndexRangeBuilder,
-	MutationBuilder,
-	NamedIndex,
-	Query,
-	QueryBuilder,
-	QueryInitializer,
-	UserIdentity,
-} from 'convex/server'
-import type { Triggers } from 'convex-helpers/server/triggers'
-import { defaultErrors, type ErrorFactory } from './errors'
-
-/** The default vocabulary; every app can supply its own via the Role generic. */
-export type DefaultRole = 'reader' | 'writer' | 'admin'
-
-export type Actor<Role extends string> = Readonly<{
-	userId: string
-	organizationId: string
-	role: Role
-}>
-
-export type AuthBundle<Role extends string> = Readonly<{
-	identity: UserIdentity
-	user: Readonly<{ id: string }>
-	org: Readonly<{ organizationId: string; role: Role }>
-	role: Role
-	actor: Actor<Role>
-}>
-
-type AnyAuthContext<DataModel extends GenericDataModel> =
-	| GenericQueryCtx<DataModel>
-	| GenericMutationCtx<DataModel>
-	| GenericActionCtx<DataModel>
-
-export type AuthFunctionsConfig<
-	DataModel extends GenericDataModel,
-	Role extends string,
-> = {
-	/** The consumer's generated function builders (from ./_generated/server). */
-	query: QueryBuilder<DataModel, 'public'>
-	mutation: MutationBuilder<DataModel, 'public'>
-	action: ActionBuilder<DataModel, 'public'>
-	internalMutation: MutationBuilder<DataModel, 'internal'>
-	internalAction: ActionBuilder<DataModel, 'internal'>
-	/** Resolves the synchronized principal, e.g. (ctx) => authKit.getAuthUser(ctx). */
-	getAuthUser: (
-		ctx: AnyAuthContext<DataModel>,
-	) => Promise<{ id: string } | null>
-	/**
-	 * Maps an identity role slug onto the app's role vocabulary. Returning
-	 * null rejects the caller with FORBIDDEN — unknown roles never pass.
-	 */
-	mapRole: (roleSlug?: string) => Role | null
-	/** Roles allowed through the admin* constructors. */
-	adminRoles: readonly NoInfer<Role>[]
-	/**
-	 * Live membership check for actions (queries/mutations trust the JWT).
-	 * Authentication fails closed with FORBIDDEN when verification errors.
-	 * Omit to let actions trust the JWT like queries do.
-	 */
-	verifyMembership?: (input: {
-		userId: string
-		organizationId: string
-	}) => Promise<{ organizationId: string; roleSlug: string } | null>
-	/** Host error policy; defaults to throwing KitError. */
-	errors?: ErrorFactory
-	/**
-	 * Application trigger registry. When set, every authMutation,
-	 * roleMutation, and systemMutation write runs through triggers.wrapDB —
-	 * evaluations registered on tables fire structurally.
-	 */
-	triggers?: Triggers<DataModel>
-	/** Lower-level alternative to `triggers`: a custom ctx wrapper. */
-	wrapDB?: (
-		ctx: GenericMutationCtx<DataModel>,
-	) => GenericMutationCtx<DataModel>
-	/** Upper bound for include() reads. */
-	maxIncludedQueryRows?: number
-}
-
-/** WorkOS-style default: `member` writes; reader/writer/admin pass through. */
-export function defaultRoleMap(roleSlug?: string): DefaultRole | null {
-	const normalized = roleSlug?.trim().toLowerCase()
-	if (normalized === 'member') return 'writer'
-	return normalized === 'reader' ||
-		normalized === 'writer' ||
-		normalized === 'admin'
-		? normalized
-		: null
-}
-
-export type IncludedQuery<Table extends GenericTableInfo> = {
-	when<Value>(
-		value: Value | null | undefined,
-		select: (query: QueryInitializer<Table>, value: Value) => Query<Table>,
-	): IncludedQuery<Table>
-	matching<IndexName extends IndexNames<Table>>(
-		indexName: IndexName,
-		indexRange?: (
-			query: IndexRangeBuilder<
-				DocumentByInfo<Table>,
-				NamedIndex<Table, IndexName>
-			>,
-		) => IndexRange,
-		shouldMatch?: boolean,
-	): IncludedQuery<Table>
-	otherwise(
-		select: (query: QueryInitializer<Table>) => Query<Table>,
-	): Query<Table>
-	resolve(): Query<Table>
-	execute<Result = Awaited<ReturnType<Query<Table>['take']>>>(
-		limit: number,
-		transform?: (
-			data: Awaited<ReturnType<Query<Table>['take']>>,
-		) => Result | Promise<Result>,
-	): Promise<Result>
-}
-
-export type Include = <Table extends GenericTableInfo>(
-	query: QueryInitializer<Table>,
-) => IncludedQuery<Table>
-
-/** Builds an include() that selects the first matching indexed query and bounds the read. */
-export function createInclude(options?: {
-	errors?: ErrorFactory
-	maxRows?: number
-}): Include {
-	const errors = options?.errors ?? defaultErrors
-	const maxRows = options?.maxRows ?? 100
-
-	function attach<Table extends GenericTableInfo>(
-		query: QueryInitializer<Table>,
-		selected?: Query<Table>,
-	): IncludedQuery<Table> {
-		return {
-			when: (value, select) =>
-				selected || value === undefined || value === null
-					? attach(query, selected)
-					: attach(query, select(query, value)),
-			matching: (indexName, indexRange, shouldMatch = true) =>
-				selected || !shouldMatch
-					? attach(query, selected)
-					: attach(query, query.withIndex(indexName, indexRange)),
-			otherwise: (select) => selected ?? select(query),
-			resolve: () => selected ?? query.fullTableScan(),
-			execute: async (limit, transform) => {
-				if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxRows) {
-					return errors.throw({
-						code: 'INVALID_REQUEST_BOUNDARY',
-						message: `A bounded query limit must be from 1 to ${maxRows}`,
-					})
-				}
-				const data = await (selected ?? query.fullTableScan()).take(limit)
-				return transform ? transform(data) : (data as never)
-			},
-		}
-	}
-
-	return (query) => attach(query)
-}
-
-/**
- * Builds the auth-aware function constructors from the host's injected
- * policy: identity resolution, the app's own role vocabulary, live
- * membership verification for actions, trigger wrapping for mutations,
- * and errors. Role-based access is first-class — every constructor family
- * has a role-gated variant (roleQuery/roleMutation/roleAction), and the
- * admin* constructors are just that gate applied to config.adminRoles.
- */
-export function createAuthFunctions<
-	DataModel extends GenericDataModel,
-	const Role extends string = DefaultRole,
->(config: AuthFunctionsConfig<DataModel, Role>) {
-	const errors = config.errors ?? defaultErrors
-	const wrapDB = config.triggers
-		? (ctx: GenericMutationCtx<DataModel>) =>
-				(config.triggers as Triggers<DataModel>).wrapDB(ctx)
-		: (config.wrapDB ?? ((ctx) => ctx))
-	const include = createInclude({
-		errors,
-		maxRows: config.maxIncludedQueryRows,
-	})
-
-	async function authenticatedUser(
-		ctx: AnyAuthContext<DataModel>,
-	): Promise<AuthBundle<Role>> {
-		const identity = await ctx.auth.getUserIdentity()
-		const user = identity ? await config.getAuthUser(ctx) : null
-		if (!identity || !user) return errors.throw({ code: 'UNAUTHENTICATED' })
-		const organization = identity.organization
-		const organizationId =
-			organization &&
-			typeof organization === 'object' &&
-			'organizationId' in organization &&
-			typeof organization.organizationId === 'string'
-				? organization.organizationId
-				: typeof identity.org_id === 'string'
-					? identity.org_id
-					: null
-		if (!organizationId) return errors.throw({ code: 'UNAUTHENTICATED' })
-		const organizationRole =
-			organization &&
-			typeof organization === 'object' &&
-			'role' in organization &&
-			typeof organization.role === 'string'
-				? organization.role
-				: typeof identity.role === 'string'
-					? identity.role
-					: undefined
-		const role = config.mapRole(organizationRole)
-		if (!role) return errors.throw({ code: 'FORBIDDEN' })
-		return Object.freeze({
-			identity,
-			user: Object.freeze({ id: user.id }),
-			org: Object.freeze({ organizationId, role }),
-			role,
-			actor: Object.freeze({ userId: user.id, organizationId, role }),
-		})
-	}
-
-	async function verifiedMembership(userId: string, organizationId: string) {
-		if (!config.verifyMembership) return null
-		try {
-			const membership = await config.verifyMembership({
-				userId,
-				organizationId,
-			})
-			if (membership && membership.organizationId === organizationId) {
-				return membership
-			}
-		} catch {
-			// Authentication fails closed when membership cannot be verified.
-		}
-		return errors.throw({ code: 'FORBIDDEN' })
-	}
-
-	function requireRole(role: Role, allowed: readonly Role[]) {
-		if (!allowed.includes(role)) return errors.throw({ code: 'FORBIDDEN' })
-	}
-
-	async function queryInput(ctx: GenericQueryCtx<DataModel>) {
-		return {
-			ctx: { ...ctx, include, ...(await authenticatedUser(ctx)) },
-			args: {},
-		}
-	}
-
-	async function mutationInput(ctx: GenericMutationCtx<DataModel>) {
-		return {
-			ctx: { ...wrapDB(ctx), include, ...(await authenticatedUser(ctx)) },
-			args: {},
-		}
-	}
-
-	async function actionInput(ctx: GenericActionCtx<DataModel>) {
-		const authenticated = await authenticatedUser(ctx)
-		const membership = await verifiedMembership(
-			authenticated.user.id,
-			authenticated.org.organizationId,
-		)
-		if (!membership) return { ctx: { ...ctx, ...authenticated }, args: {} }
-		const role = config.mapRole(membership.roleSlug)
-		if (!role) return errors.throw({ code: 'FORBIDDEN' })
-		return {
-			ctx: {
-				...ctx,
-				...authenticated,
-				org: Object.freeze({
-					organizationId: membership.organizationId,
-					role,
-				}),
-				role,
-				actor: Object.freeze({
-					userId: authenticated.user.id,
-					organizationId: membership.organizationId,
-					role,
-				}),
-			},
-			args: {},
-		}
-	}
-
-	/** Query constructor allowing only the given roles. */
-	function roleQuery(...allowed: readonly Role[]) {
-		return zCustomQuery(config.query, {
-			args: {},
-			input: async (ctx) => {
-				const authenticated = await queryInput(ctx)
-				requireRole(authenticated.ctx.actor.role, allowed)
-				return authenticated
-			},
-		})
-	}
-
-	/** Mutation constructor allowing only the given roles. */
-	function roleMutation(...allowed: readonly Role[]) {
-		return zCustomMutation(config.mutation, {
-			args: {},
-			input: async (ctx) => {
-				const authenticated = await mutationInput(ctx)
-				requireRole(authenticated.ctx.actor.role, allowed)
-				return authenticated
-			},
-		})
-	}
-
-	/** Action constructor allowing only the given roles (post live verification). */
-	function roleAction(...allowed: readonly Role[]) {
-		return zCustomAction(config.action, {
-			args: {},
-			input: async (ctx) => {
-				const authenticated = await actionInput(ctx)
-				requireRole(authenticated.ctx.actor.role, allowed)
-				return authenticated
-			},
-		})
-	}
-
-	return {
-		include,
-		authenticatedUser,
-		roleQuery,
-		roleMutation,
-		roleAction,
-		authQuery: zCustomQuery(config.query, { args: {}, input: queryInput }),
-		authMutation: zCustomMutation(config.mutation, {
-			args: {},
-			input: mutationInput,
-		}),
-		authAction: zCustomAction(config.action, {
-			args: {},
-			input: actionInput,
-		}),
-		adminQuery: roleQuery(...config.adminRoles),
-		adminMutation: roleMutation(...config.adminRoles),
-		adminAction: roleAction(...config.adminRoles),
-		systemMutation: zCustomMutation(config.internalMutation, {
-			args: {},
-			input: async (ctx) => ({ ctx: { ...wrapDB(ctx), include }, args: {} }),
-		}),
-		systemAction: zCustomAction(config.internalAction, {
-			args: {},
-			input: async (ctx) => ({ ctx, args: {} }),
-		}),
-	}
-}