cvx-kit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Angel Lopez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# cvx-kit
+
+[![CI](https://github.com/ImRLopezAG/cvx-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/ImRLopezAG/cvx-kit/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/cvx-kit)](https://www.npmjs.com/package/cvx-kit)
+
+Reusable Convex application kit: foundation kernels, a generic approvals
+component, zod table boundaries, auth-aware function constructors with
+per-app role vocabularies, an application trigger registry, and an audited
+command protocol.
+
+```sh
+bun add cvx-kit
+# or: npm install cvx-kit
+```
+
+## Toolchain
+
+- `bun install` — dependencies
+- `bun run test` — vite-plus test suite (`vp test run`, convex-test on edge-runtime)
+- `bun run typecheck` — `tsc --noEmit`
+- `bun run build` — `vp pack` (tsdown on Rolldown); all build options live in
+  the `pack` key of `vite.config.ts`: per-module ESM + `.d.mts` to `dist/`,
+  target ES2025, minified, deps external, publint-verified
+- `bun run build:codegen` — re-run `convex codegen` for both components, then build
+
+## Modules
+
+### `cvx-kit/zod-table`
+
+One zod shape per entity, masked into every boundary it crosses:
+
+```ts
+import { zodTable } from 'cvx-kit/zod-table'
+
+export const documents = zodTable(
+  'documents',
+  (id) => ({
+    title: z.string(),
+    ownerId: id('users'),
+    secretNote: z.string(),
+  }),
+  {
+    commandFields: ['title'],           // what a command may say
+    publicFields: ['title', 'ownerId'], // the DTO allowlist
+  },
+)
+// documents.table → defineTable(...) for schema.ts
+// documents.toPublicDto(row) → projects AND re-parses (runtime redaction)
+```
+
+Every table gets `createdAt`, `updatedAt`, and `archivedAt` baked in —
+opinionated, server-owned, always excluded from inserts and commands
+(expose them via `publicFields` when a DTO needs them). Register the
+`timestamps` trigger once and they maintain themselves; `archivedAt` stays
+under application control.
+
+`zodVariantTable` covers discriminated-union tables; `jsonSafeZid` keeps
+LLM-tool JSON schemas primitive while preserving the `Id<...>` type.
+
+### `cvx-kit/auth`
+
+`createAuthFunctions` builds the six auth-aware constructors from injected
+policy — nothing in the kit imports your app's singletons:
+
+```ts
+import { createAuthFunctions } from 'cvx-kit/auth'
+import { action, internalAction, internalMutation, mutation, query } from './_generated/server'
+
+export const { authQuery, authMutation, authAction, adminQuery, adminMutation,
+  adminAction, systemMutation, systemAction, include } =
+  createAuthFunctions<DataModel>({
+    query, mutation, action, internalMutation, internalAction,
+    getAuthUser: (ctx) => authKit.getAuthUser(ctx),
+    verifyMembership: async ({ userId, organizationId }) => {
+      const memberships = await authKit.workos.userManagement
+        .listOrganizationMemberships({ organizationId, userId, statuses: ['active'] })
+      const m = memberships.data.find((c) => c.userId === userId)
+      return m ? { organizationId: m.organizationId, roleSlug: m.role.slug } : null
+    },
+    wrapDB: (ctx) => triggers.wrapDB(ctx),
+  })
+```
+
+Actions re-verify membership live and fail closed; mutations get the trigger
+registry structurally; `include()` bounds every read (default 100 rows).
+
+### `cvx-kit/components/foundation`
+
+Declared once; everything destructures from it. `Command` comes out of the
+Foundation already bound to observability and the audit writer — there is no
+separate command import.
+
+```ts
+// convex/convex.config.ts
+import foundation from 'cvx-kit/components/foundation'
+app.use(foundation)
+
+// convex/foundation.ts — declared once, the single kernel source
+import { Foundation } from 'cvx-kit/components/foundation'
+export const { Command, Query, observability } = new Foundation(
+  components.foundation,
+  {
+    observability: {
+      enabled: () => env.OBS === 'true',
+      classifyError,
+      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
+    },
+  },
+)
+
+// convex/domain/<owner>/commands.ts
+import { Command } from '../foundation'
+
+const commands = new Command({
+  'documents.rename': Command.operation({
+    command: renameInput,
+    result: renameResult,
+    classification: 'business',
+    audit: ({ command }, ctx) => ({ ... }),
+  }),
+})
+export const executeRename = commands.exec({ operation: 'documents.rename', handler })
+```
+
+Every command is validated (input and output zod-parsed), observed, and
+audited in-transaction. `classification` and `audit()` are mandatory per
+operation: auditing is type-enforced, not opt-in. The foundation component
+itself owns zero tables and ships `executeResultBoundary` (typed failures
+only while the transaction has no effects; otherwise rethrow so Convex
+rolls back).
+
+### `cvx-kit/components/approvals` (component)
+
+Declarative approval workflows (decision / branch / mutation / action /
+notify) with quorum, maker-checker, expiry, compatibility keys, durable
+execution via a nested `@convex-dev/workflow`, and its own audit trail via a
+nested `convex-audit-log`. Tenancy is an opaque `scopeRef`; callbacks are
+function handles — the component never imports host code.
+
+```ts
+// convex/convex.config.ts
+import approvals from 'cvx-kit/components/approvals'
+app.use(approvals)
+```
+
+## Component authoring conventions
+
+This package follows the official Convex component template
+(`get-convex/templates/template-component`; see
+https://docs.convex.dev/components/authoring):
+
+- Components live in `src/components/<name>` with their own
+  `convex.config.ts`, `schema.ts`, functions, and **checked-in
+  `_generated/`** (required for npm-distributed components).
+- Hosts mount via the `./components/<name>/convex.config` subpath export and call the
+  component only through its client class — never its tables directly.
+- `bun run build:codegen` re-runs `convex codegen --component-dir` for both
+  components before building.
+- Consumers test in-memory via the `cvx-kit/test` export:
+
+```ts
+import { convexTest } from 'convex-test'
+import { registerApprovals, registerFoundation } from 'cvx-kit/test'
+
+const t = convexTest(appSchema, modules)
+registerFoundation(t)
+registerApprovals(t)
+```
+
+## Releasing
+
+Publishing uses [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
+(OIDC) — no tokens stored anywhere. The release workflow authenticates via
+GitHub's OIDC and npm generates provenance attestations automatically.
+
+- `bun run release` — patch version bump, tag, and push; the `v*` tag
+  triggers `.github/workflows/release.yml`, which verifies (typecheck, test,
+  build + publint) and publishes.
+- `bun run release:minor` — same, minor bump.
+
+One-time setup (already-published package required first):
+
+1. First publish is manual: `npm publish --access public` locally.
+2. On npmjs.com → package → Settings → Trusted Publisher: GitHub Actions,
+   owner `ImRLopezAG`, repository `cvx-kit`, workflow `release.yml`,
+   environment `npm`.
+3. Create the `npm` environment in the GitHub repo settings.
+
+## Roadmap
+
+- [ ] Port the approvals `copyability` test (cp -r + tsc + `convex codegen
+      --dry-run`) into this repo's suite as the portability guarantee.
+- [ ] `createArchitectureTest(rules)` helper so consuming projects get the
+      boundary guardrails (no inline tables/enums, single facade per
+      component) on day one.
+- [ ] WorkOS scaffold generator for `auth.ts` / `auth.config.ts` / `http.ts`.
+- [ ] Audit facade helpers (fingerprinted cursors, bounded windows) over any
+      `convex-audit-log` instance.
+- [ ] Decide the published name/scope before `npm publish` (`cvx-kit` is a
+      working title).

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1 @@
+var e=Object.defineProperty,t=(t,n)=>{let r={};for(var i in t)e(r,i,{get:t[i],enumerable:!0});return n||e(r,Symbol.toStringTag,{value:`Module`}),r};export{t as __exportAll};

package/dist/auth.d.mts

@@ -0,0 +1,353 @@
+import { ErrorFactory } from "./errors.mjs";
+import { ActionBuilder, DocumentByInfo, GenericActionCtx, GenericDataModel, GenericMutationCtx, GenericQueryCtx, GenericTableInfo, IndexNames, IndexRange, IndexRangeBuilder, MutationBuilder, NamedIndex, Query, QueryBuilder, QueryInitializer, UserIdentity } from "convex/server";
+import { Triggers } from "convex-helpers/server/triggers";
+//#region src/auth.d.ts
+/** The default vocabulary; every app can supply its own via the Role generic. */
+type DefaultRole = 'reader' | 'writer' | 'admin';
+type Actor<Role extends string> = Readonly<{
+  userId: string;
+  organizationId: string;
+  role: Role;
+}>;
+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>;
+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. */
+declare function defaultRoleMap(roleSlug?: string): DefaultRole | null;
+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>;
+};
+type Include = <Table extends GenericTableInfo>(query: QueryInitializer<Table>) => IncludedQuery<Table>;
+/** Builds an include() that selects the first matching indexed query and bounds the read. */
+declare function createInclude(options?: {
+  errors?: ErrorFactory;
+  maxRows?: number;
+}): Include;
+/**
+ * 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.
+ */
+declare function createAuthFunctions<DataModel extends GenericDataModel, const Role extends string = DefaultRole>(config: AuthFunctionsConfig<DataModel, Role>): {
+  include: Include;
+  authenticatedUser: (ctx: AnyAuthContext<DataModel>) => Promise<AuthBundle<Role>>;
+  roleQuery: (...allowed: readonly Role[]) => import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
+    db: import("convex/server").GenericDatabaseReader<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageReader;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    meta: import("convex/server").QueryMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+    include: Include;
+  }, {}, GenericQueryCtx<DataModel>, "public", object>;
+  roleMutation: (...allowed: readonly Role[]) => import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
+    db: import("convex/server").GenericDatabaseWriter<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageWriter;
+    scheduler: import("convex/server").Scheduler;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    meta: import("convex/server").MutationMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+    include: Include;
+  }, {}, GenericMutationCtx<DataModel>, "public", object>;
+  roleAction: (...allowed: readonly Role[]) => import("convex-helpers/server/zod4").CustomBuilder<"action", {}, {
+    runQuery<Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").OptionalRestArgs<Query>): Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation<Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").OptionalRestArgs<Mutation>): Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    runAction<Action extends import("convex/server").FunctionReference<"action", "public" | "internal">>(action: Action, ...args: import("convex/server").OptionalRestArgs<Action>): Promise<import("convex/server").FunctionReturnType<Action>>;
+    scheduler: import("convex/server").Scheduler;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageActionWriter;
+    vectorSearch<TableName extends import("convex/server").TableNamesInDataModel<DataModel>, IndexName extends import("convex/server").VectorIndexNames<import("convex/server").NamedTableInfo<DataModel, TableName>>>(tableName: TableName, indexName: IndexName, query: {
+      vector: number[];
+      limit?: number;
+      filter?: ((q: import("convex/server").VectorFilterBuilder<DocumentByInfo<import("convex/server").NamedTableInfo<DataModel, TableName>>, import("convex/server").NamedVectorIndex<import("convex/server").NamedTableInfo<DataModel, TableName>, IndexName>>) => import("convex/server").FilterExpression<boolean>) | undefined;
+    }): Promise<{
+      _id: import("convex/values").GenericId<TableName>;
+      _score: number;
+    }[]>;
+    meta: import("convex/server").ActionMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+  }, {}, GenericActionCtx<DataModel>, "public", object>;
+  authQuery: import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
+    db: import("convex/server").GenericDatabaseReader<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageReader;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    meta: import("convex/server").QueryMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+    include: Include;
+  }, {}, GenericQueryCtx<DataModel>, "public", object>;
+  authMutation: import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
+    db: import("convex/server").GenericDatabaseWriter<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageWriter;
+    scheduler: import("convex/server").Scheduler;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    meta: import("convex/server").MutationMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+    include: Include;
+  }, {}, GenericMutationCtx<DataModel>, "public", object>;
+  authAction: import("convex-helpers/server/zod4").CustomBuilder<"action", {}, {
+    runQuery<Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").OptionalRestArgs<Query>): Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation<Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").OptionalRestArgs<Mutation>): Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    runAction<Action extends import("convex/server").FunctionReference<"action", "public" | "internal">>(action: Action, ...args: import("convex/server").OptionalRestArgs<Action>): Promise<import("convex/server").FunctionReturnType<Action>>;
+    scheduler: import("convex/server").Scheduler;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageActionWriter;
+    vectorSearch<TableName extends import("convex/server").TableNamesInDataModel<DataModel>, IndexName extends import("convex/server").VectorIndexNames<import("convex/server").NamedTableInfo<DataModel, TableName>>>(tableName: TableName, indexName: IndexName, query: {
+      vector: number[];
+      limit?: number;
+      filter?: ((q: import("convex/server").VectorFilterBuilder<DocumentByInfo<import("convex/server").NamedTableInfo<DataModel, TableName>>, import("convex/server").NamedVectorIndex<import("convex/server").NamedTableInfo<DataModel, TableName>, IndexName>>) => import("convex/server").FilterExpression<boolean>) | undefined;
+    }): Promise<{
+      _id: import("convex/values").GenericId<TableName>;
+      _score: number;
+    }[]>;
+    meta: import("convex/server").ActionMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+  }, {}, GenericActionCtx<DataModel>, "public", object>;
+  adminQuery: import("convex-helpers/server/zod4").CustomBuilder<"query", {}, {
+    db: import("convex/server").GenericDatabaseReader<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageReader;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    meta: import("convex/server").QueryMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+    include: Include;
+  }, {}, GenericQueryCtx<DataModel>, "public", object>;
+  adminMutation: import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
+    db: import("convex/server").GenericDatabaseWriter<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageWriter;
+    scheduler: import("convex/server").Scheduler;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    meta: import("convex/server").MutationMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+    include: Include;
+  }, {}, GenericMutationCtx<DataModel>, "public", object>;
+  adminAction: import("convex-helpers/server/zod4").CustomBuilder<"action", {}, {
+    runQuery<Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").OptionalRestArgs<Query>): Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation<Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").OptionalRestArgs<Mutation>): Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    runAction<Action extends import("convex/server").FunctionReference<"action", "public" | "internal">>(action: Action, ...args: import("convex/server").OptionalRestArgs<Action>): Promise<import("convex/server").FunctionReturnType<Action>>;
+    scheduler: import("convex/server").Scheduler;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageActionWriter;
+    vectorSearch<TableName extends import("convex/server").TableNamesInDataModel<DataModel>, IndexName extends import("convex/server").VectorIndexNames<import("convex/server").NamedTableInfo<DataModel, TableName>>>(tableName: TableName, indexName: IndexName, query: {
+      vector: number[];
+      limit?: number;
+      filter?: ((q: import("convex/server").VectorFilterBuilder<DocumentByInfo<import("convex/server").NamedTableInfo<DataModel, TableName>>, import("convex/server").NamedVectorIndex<import("convex/server").NamedTableInfo<DataModel, TableName>, IndexName>>) => import("convex/server").FilterExpression<boolean>) | undefined;
+    }): Promise<{
+      _id: import("convex/values").GenericId<TableName>;
+      _score: number;
+    }[]>;
+    meta: import("convex/server").ActionMeta;
+    identity: UserIdentity;
+    user: Readonly<{
+      id: string;
+    }>;
+    org: Readonly<{
+      organizationId: string;
+      role: Role;
+    }>;
+    role: Role;
+    actor: Readonly<{
+      userId: string;
+      organizationId: string;
+      role: Role;
+    }>;
+  }, {}, GenericActionCtx<DataModel>, "public", object>;
+  systemMutation: import("convex-helpers/server/zod4").CustomBuilder<"mutation", {}, {
+    db: import("convex/server").GenericDatabaseWriter<DataModel>;
+    auth: import("convex/server").Auth;
+    storage: import("convex/server").StorageWriter;
+    scheduler: import("convex/server").Scheduler;
+    runQuery: <Query extends import("convex/server").FunctionReference<"query", "public" | "internal">>(query: Query, ...args: import("convex/server").ArgsAndOptions<Query, import("convex/server").AdvancedRunQueryOptions>) => Promise<import("convex/server").FunctionReturnType<Query>>;
+    runMutation: <Mutation extends import("convex/server").FunctionReference<"mutation", "public" | "internal">>(mutation: Mutation, ...args: import("convex/server").ArgsAndOptions<Mutation, {
+      transactionLimits?: import("convex/server").TransactionLimits;
+    }>) => Promise<import("convex/server").FunctionReturnType<Mutation>>;
+    meta: import("convex/server").MutationMeta;
+    include: Include;
+  }, {}, GenericMutationCtx<DataModel>, "internal", object>;
+  systemAction: import("convex-helpers/server/zod4").CustomBuilder<"action", {}, GenericActionCtx<DataModel>, {}, GenericActionCtx<DataModel>, "internal", object>;
+};
+//#endregion
+export { Actor, AuthBundle, AuthFunctionsConfig, DefaultRole, Include, IncludedQuery, createAuthFunctions, createInclude, defaultRoleMap };
+//# sourceMappingURL=auth.d.mts.map

package/dist/auth.mjs

@@ -0,0 +1,2 @@
+import{defaultErrors as e}from"./errors.mjs";import{zCustomAction as t,zCustomMutation as n,zCustomQuery as r}from"convex-helpers/server/zod4";function i(e){let t=e?.trim().toLowerCase();return t===`member`?`writer`:t===`reader`||t===`writer`||t===`admin`?t:null}function a(t){let n=t?.errors??e,r=t?.maxRows??100;function i(e,t){return{when:(n,r)=>t||n==null?i(e,t):i(e,r(e,n)),matching:(n,r,a=!0)=>t||!a?i(e,t):i(e,e.withIndex(n,r)),otherwise:n=>t??n(e),resolve:()=>t??e.fullTableScan(),execute:async(i,a)=>{if(!Number.isSafeInteger(i)||i<1||i>r)return n.throw({code:`INVALID_REQUEST_BOUNDARY`,message:`A bounded query limit must be from 1 to ${r}`});let o=await(t??e.fullTableScan()).take(i);return a?a(o):o}}}return e=>i(e)}function o(i){let o=i.errors??e,s=i.triggers?e=>i.triggers.wrapDB(e):i.wrapDB??(e=>e),c=a({errors:o,maxRows:i.maxIncludedQueryRows});async function l(e){let t=await e.auth.getUserIdentity(),n=t?await i.getAuthUser(e):null;if(!t||!n)return o.throw({code:`UNAUTHENTICATED`});let r=t.organization,a=r&&typeof r==`object`&&`organizationId`in r&&typeof r.organizationId==`string`?r.organizationId:typeof t.org_id==`string`?t.org_id:null;if(!a)return o.throw({code:`UNAUTHENTICATED`});let s=r&&typeof r==`object`&&`role`in r&&typeof r.role==`string`?r.role:typeof t.role==`string`?t.role:void 0,c=i.mapRole(s);return c?Object.freeze({identity:t,user:Object.freeze({id:n.id}),org:Object.freeze({organizationId:a,role:c}),role:c,actor:Object.freeze({userId:n.id,organizationId:a,role:c})}):o.throw({code:`FORBIDDEN`})}async function u(e,t){if(!i.verifyMembership)return null;try{let n=await i.verifyMembership({userId:e,organizationId:t});if(n&&n.organizationId===t)return n}catch{}return o.throw({code:`FORBIDDEN`})}function d(e,t){if(!t.includes(e))return o.throw({code:`FORBIDDEN`})}async function f(e){return{ctx:{...e,include:c,...await l(e)},args:{}}}async function p(e){return{ctx:{...s(e),include:c,...await l(e)},args:{}}}async function m(e){let t=await l(e),n=await u(t.user.id,t.org.organizationId);if(!n)return{ctx:{...e,...t},args:{}};let r=i.mapRole(n.roleSlug);return r?{ctx:{...e,...t,org:Object.freeze({organizationId:n.organizationId,role:r}),role:r,actor:Object.freeze({userId:t.user.id,organizationId:n.organizationId,role:r})},args:{}}:o.throw({code:`FORBIDDEN`})}function h(...e){return r(i.query,{args:{},input:async t=>{let n=await f(t);return d(n.ctx.actor.role,e),n}})}function g(...e){return n(i.mutation,{args:{},input:async t=>{let n=await p(t);return d(n.ctx.actor.role,e),n}})}function _(...e){return t(i.action,{args:{},input:async t=>{let n=await m(t);return d(n.ctx.actor.role,e),n}})}return{include:c,authenticatedUser:l,roleQuery:h,roleMutation:g,roleAction:_,authQuery:r(i.query,{args:{},input:f}),authMutation:n(i.mutation,{args:{},input:p}),authAction:t(i.action,{args:{},input:m}),adminQuery:h(...i.adminRoles),adminMutation:g(...i.adminRoles),adminAction:_(...i.adminRoles),systemMutation:n(i.internalMutation,{args:{},input:async e=>({ctx:{...s(e),include:c},args:{}})}),systemAction:t(i.internalAction,{args:{},input:async e=>({ctx:e,args:{}})})}}export{o as createAuthFunctions,a as createInclude,i as defaultRoleMap};
+//# sourceMappingURL=auth.mjs.map

package/dist/auth.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.mjs","names":[],"sources":["../src/auth.ts"],"sourcesContent":["import {\n\tzCustomAction,\n\tzCustomMutation,\n\tzCustomQuery,\n} from 'convex-helpers/server/zod4'\nimport type {\n\tActionBuilder,\n\tDocumentByInfo,\n\tGenericActionCtx,\n\tGenericDataModel,\n\tGenericMutationCtx,\n\tGenericQueryCtx,\n\tGenericTableInfo,\n\tIndexNames,\n\tIndexRange,\n\tIndexRangeBuilder,\n\tMutationBuilder,\n\tNamedIndex,\n\tQuery,\n\tQueryBuilder,\n\tQueryInitializer,\n\tUserIdentity,\n} from 'convex/server'\nimport type { Triggers } from 'convex-helpers/server/triggers'\nimport { defaultErrors, type ErrorFactory } from './errors'\n\n/** The default vocabulary; every app can supply its own via the Role generic. */\nexport type DefaultRole = 'reader' | 'writer' | 'admin'\n\nexport type Actor<Role extends string> = Readonly<{\n\tuserId: string\n\torganizationId: string\n\trole: Role\n}>\n\nexport type AuthBundle<Role extends string> = Readonly<{\n\tidentity: UserIdentity\n\tuser: Readonly<{ id: string }>\n\torg: Readonly<{ organizationId: string; role: Role }>\n\trole: Role\n\tactor: Actor<Role>\n}>\n\ntype AnyAuthContext<DataModel extends GenericDataModel> =\n\t| GenericQueryCtx<DataModel>\n\t| GenericMutationCtx<DataModel>\n\t| GenericActionCtx<DataModel>\n\nexport type AuthFunctionsConfig<\n\tDataModel extends GenericDataModel,\n\tRole extends string,\n> = {\n\t/** The consumer's generated function builders (from ./_generated/server). */\n\tquery: QueryBuilder<DataModel, 'public'>\n\tmutation: MutationBuilder<DataModel, 'public'>\n\taction: ActionBuilder<DataModel, 'public'>\n\tinternalMutation: MutationBuilder<DataModel, 'internal'>\n\tinternalAction: ActionBuilder<DataModel, 'internal'>\n\t/** Resolves the synchronized principal, e.g. (ctx) => authKit.getAuthUser(ctx). */\n\tgetAuthUser: (\n\t\tctx: AnyAuthContext<DataModel>,\n\t) => Promise<{ id: string } | null>\n\t/**\n\t * Maps an identity role slug onto the app's role vocabulary. Returning\n\t * null rejects the caller with FORBIDDEN — unknown roles never pass.\n\t */\n\tmapRole: (roleSlug?: string) => Role | null\n\t/** Roles allowed through the admin* constructors. */\n\tadminRoles: readonly NoInfer<Role>[]\n\t/**\n\t * Live membership check for actions (queries/mutations trust the JWT).\n\t * Authentication fails closed with FORBIDDEN when verification errors.\n\t * Omit to let actions trust the JWT like queries do.\n\t */\n\tverifyMembership?: (input: {\n\t\tuserId: string\n\t\torganizationId: string\n\t}) => Promise<{ organizationId: string; roleSlug: string } | null>\n\t/** Host error policy; defaults to throwing KitError. */\n\terrors?: ErrorFactory\n\t/**\n\t * Application trigger registry. When set, every authMutation,\n\t * roleMutation, and systemMutation write runs through triggers.wrapDB —\n\t * evaluations registered on tables fire structurally.\n\t */\n\ttriggers?: Triggers<DataModel>\n\t/** Lower-level alternative to `triggers`: a custom ctx wrapper. */\n\twrapDB?: (\n\t\tctx: GenericMutationCtx<DataModel>,\n\t) => GenericMutationCtx<DataModel>\n\t/** Upper bound for include() reads. */\n\tmaxIncludedQueryRows?: number\n}\n\n/** WorkOS-style default: `member` writes; reader/writer/admin pass through. */\nexport function defaultRoleMap(roleSlug?: string): DefaultRole | null {\n\tconst normalized = roleSlug?.trim().toLowerCase()\n\tif (normalized === 'member') return 'writer'\n\treturn normalized === 'reader' ||\n\t\tnormalized === 'writer' ||\n\t\tnormalized === 'admin'\n\t\t? normalized\n\t\t: null\n}\n\nexport type IncludedQuery<Table extends GenericTableInfo> = {\n\twhen<Value>(\n\t\tvalue: Value | null | undefined,\n\t\tselect: (query: QueryInitializer<Table>, value: Value) => Query<Table>,\n\t): IncludedQuery<Table>\n\tmatching<IndexName extends IndexNames<Table>>(\n\t\tindexName: IndexName,\n\t\tindexRange?: (\n\t\t\tquery: IndexRangeBuilder<\n\t\t\t\tDocumentByInfo<Table>,\n\t\t\t\tNamedIndex<Table, IndexName>\n\t\t\t>,\n\t\t) => IndexRange,\n\t\tshouldMatch?: boolean,\n\t): IncludedQuery<Table>\n\totherwise(\n\t\tselect: (query: QueryInitializer<Table>) => Query<Table>,\n\t): Query<Table>\n\tresolve(): Query<Table>\n\texecute<Result = Awaited<ReturnType<Query<Table>['take']>>>(\n\t\tlimit: number,\n\t\ttransform?: (\n\t\t\tdata: Awaited<ReturnType<Query<Table>['take']>>,\n\t\t) => Result | Promise<Result>,\n\t): Promise<Result>\n}\n\nexport type Include = <Table extends GenericTableInfo>(\n\tquery: QueryInitializer<Table>,\n) => IncludedQuery<Table>\n\n/** Builds an include() that selects the first matching indexed query and bounds the read. */\nexport function createInclude(options?: {\n\terrors?: ErrorFactory\n\tmaxRows?: number\n}): Include {\n\tconst errors = options?.errors ?? defaultErrors\n\tconst maxRows = options?.maxRows ?? 100\n\n\tfunction attach<Table extends GenericTableInfo>(\n\t\tquery: QueryInitializer<Table>,\n\t\tselected?: Query<Table>,\n\t): IncludedQuery<Table> {\n\t\treturn {\n\t\t\twhen: (value, select) =>\n\t\t\t\tselected || value === undefined || value === null\n\t\t\t\t\t? attach(query, selected)\n\t\t\t\t\t: attach(query, select(query, value)),\n\t\t\tmatching: (indexName, indexRange, shouldMatch = true) =>\n\t\t\t\tselected || !shouldMatch\n\t\t\t\t\t? attach(query, selected)\n\t\t\t\t\t: attach(query, query.withIndex(indexName, indexRange)),\n\t\t\totherwise: (select) => selected ?? select(query),\n\t\t\tresolve: () => selected ?? query.fullTableScan(),\n\t\t\texecute: async (limit, transform) => {\n\t\t\t\tif (!Number.isSafeInteger(limit) || limit < 1 || limit > maxRows) {\n\t\t\t\t\treturn errors.throw({\n\t\t\t\t\t\tcode: 'INVALID_REQUEST_BOUNDARY',\n\t\t\t\t\t\tmessage: `A bounded query limit must be from 1 to ${maxRows}`,\n\t\t\t\t\t})\n\t\t\t\t}\n\t\t\t\tconst data = await (selected ?? query.fullTableScan()).take(limit)\n\t\t\t\treturn transform ? transform(data) : (data as never)\n\t\t\t},\n\t\t}\n\t}\n\n\treturn (query) => attach(query)\n}\n\n/**\n * Builds the auth-aware function constructors from the host's injected\n * policy: identity resolution, the app's own role vocabulary, live\n * membership verification for actions, trigger wrapping for mutations,\n * and errors. Role-based access is first-class — every constructor family\n * has a role-gated variant (roleQuery/roleMutation/roleAction), and the\n * admin* constructors are just that gate applied to config.adminRoles.\n */\nexport function createAuthFunctions<\n\tDataModel extends GenericDataModel,\n\tconst Role extends string = DefaultRole,\n>(config: AuthFunctionsConfig<DataModel, Role>) {\n\tconst errors = config.errors ?? defaultErrors\n\tconst wrapDB = config.triggers\n\t\t? (ctx: GenericMutationCtx<DataModel>) =>\n\t\t\t\t(config.triggers as Triggers<DataModel>).wrapDB(ctx)\n\t\t: (config.wrapDB ?? ((ctx) => ctx))\n\tconst include = createInclude({\n\t\terrors,\n\t\tmaxRows: config.maxIncludedQueryRows,\n\t})\n\n\tasync function authenticatedUser(\n\t\tctx: AnyAuthContext<DataModel>,\n\t): Promise<AuthBundle<Role>> {\n\t\tconst identity = await ctx.auth.getUserIdentity()\n\t\tconst user = identity ? await config.getAuthUser(ctx) : null\n\t\tif (!identity || !user) return errors.throw({ code: 'UNAUTHENTICATED' })\n\t\tconst organization = identity.organization\n\t\tconst organizationId =\n\t\t\torganization &&\n\t\t\ttypeof organization === 'object' &&\n\t\t\t'organizationId' in organization &&\n\t\t\ttypeof organization.organizationId === 'string'\n\t\t\t\t? organization.organizationId\n\t\t\t\t: typeof identity.org_id === 'string'\n\t\t\t\t\t? identity.org_id\n\t\t\t\t\t: null\n\t\tif (!organizationId) return errors.throw({ code: 'UNAUTHENTICATED' })\n\t\tconst organizationRole =\n\t\t\torganization &&\n\t\t\ttypeof organization === 'object' &&\n\t\t\t'role' in organization &&\n\t\t\ttypeof organization.role === 'string'\n\t\t\t\t? organization.role\n\t\t\t\t: typeof identity.role === 'string'\n\t\t\t\t\t? identity.role\n\t\t\t\t\t: undefined\n\t\tconst role = config.mapRole(organizationRole)\n\t\tif (!role) return errors.throw({ code: 'FORBIDDEN' })\n\t\treturn Object.freeze({\n\t\t\tidentity,\n\t\t\tuser: Object.freeze({ id: user.id }),\n\t\t\torg: Object.freeze({ organizationId, role }),\n\t\t\trole,\n\t\t\tactor: Object.freeze({ userId: user.id, organizationId, role }),\n\t\t})\n\t}\n\n\tasync function verifiedMembership(userId: string, organizationId: string) {\n\t\tif (!config.verifyMembership) return null\n\t\ttry {\n\t\t\tconst membership = await config.verifyMembership({\n\t\t\t\tuserId,\n\t\t\t\torganizationId,\n\t\t\t})\n\t\t\tif (membership && membership.organizationId === organizationId) {\n\t\t\t\treturn membership\n\t\t\t}\n\t\t} catch {\n\t\t\t// Authentication fails closed when membership cannot be verified.\n\t\t}\n\t\treturn errors.throw({ code: 'FORBIDDEN' })\n\t}\n\n\tfunction requireRole(role: Role, allowed: readonly Role[]) {\n\t\tif (!allowed.includes(role)) return errors.throw({ code: 'FORBIDDEN' })\n\t}\n\n\tasync function queryInput(ctx: GenericQueryCtx<DataModel>) {\n\t\treturn {\n\t\t\tctx: { ...ctx, include, ...(await authenticatedUser(ctx)) },\n\t\t\targs: {},\n\t\t}\n\t}\n\n\tasync function mutationInput(ctx: GenericMutationCtx<DataModel>) {\n\t\treturn {\n\t\t\tctx: { ...wrapDB(ctx), include, ...(await authenticatedUser(ctx)) },\n\t\t\targs: {},\n\t\t}\n\t}\n\n\tasync function actionInput(ctx: GenericActionCtx<DataModel>) {\n\t\tconst authenticated = await authenticatedUser(ctx)\n\t\tconst membership = await verifiedMembership(\n\t\t\tauthenticated.user.id,\n\t\t\tauthenticated.org.organizationId,\n\t\t)\n\t\tif (!membership) return { ctx: { ...ctx, ...authenticated }, args: {} }\n\t\tconst role = config.mapRole(membership.roleSlug)\n\t\tif (!role) return errors.throw({ code: 'FORBIDDEN' })\n\t\treturn {\n\t\t\tctx: {\n\t\t\t\t...ctx,\n\t\t\t\t...authenticated,\n\t\t\t\torg: Object.freeze({\n\t\t\t\t\torganizationId: membership.organizationId,\n\t\t\t\t\trole,\n\t\t\t\t}),\n\t\t\t\trole,\n\t\t\t\tactor: Object.freeze({\n\t\t\t\t\tuserId: authenticated.user.id,\n\t\t\t\t\torganizationId: membership.organizationId,\n\t\t\t\t\trole,\n\t\t\t\t}),\n\t\t\t},\n\t\t\targs: {},\n\t\t}\n\t}\n\n\t/** Query constructor allowing only the given roles. */\n\tfunction roleQuery(...allowed: readonly Role[]) {\n\t\treturn zCustomQuery(config.query, {\n\t\t\targs: {},\n\t\t\tinput: async (ctx) => {\n\t\t\t\tconst authenticated = await queryInput(ctx)\n\t\t\t\trequireRole(authenticated.ctx.actor.role, allowed)\n\t\t\t\treturn authenticated\n\t\t\t},\n\t\t})\n\t}\n\n\t/** Mutation constructor allowing only the given roles. */\n\tfunction roleMutation(...allowed: readonly Role[]) {\n\t\treturn zCustomMutation(config.mutation, {\n\t\t\targs: {},\n\t\t\tinput: async (ctx) => {\n\t\t\t\tconst authenticated = await mutationInput(ctx)\n\t\t\t\trequireRole(authenticated.ctx.actor.role, allowed)\n\t\t\t\treturn authenticated\n\t\t\t},\n\t\t})\n\t}\n\n\t/** Action constructor allowing only the given roles (post live verification). */\n\tfunction roleAction(...allowed: readonly Role[]) {\n\t\treturn zCustomAction(config.action, {\n\t\t\targs: {},\n\t\t\tinput: async (ctx) => {\n\t\t\t\tconst authenticated = await actionInput(ctx)\n\t\t\t\trequireRole(authenticated.ctx.actor.role, allowed)\n\t\t\t\treturn authenticated\n\t\t\t},\n\t\t})\n\t}\n\n\treturn {\n\t\tinclude,\n\t\tauthenticatedUser,\n\t\troleQuery,\n\t\troleMutation,\n\t\troleAction,\n\t\tauthQuery: zCustomQuery(config.query, { args: {}, input: queryInput }),\n\t\tauthMutation: zCustomMutation(config.mutation, {\n\t\t\targs: {},\n\t\t\tinput: mutationInput,\n\t\t}),\n\t\tauthAction: zCustomAction(config.action, {\n\t\t\targs: {},\n\t\t\tinput: actionInput,\n\t\t}),\n\t\tadminQuery: roleQuery(...config.adminRoles),\n\t\tadminMutation: roleMutation(...config.adminRoles),\n\t\tadminAction: roleAction(...config.adminRoles),\n\t\tsystemMutation: zCustomMutation(config.internalMutation, {\n\t\t\targs: {},\n\t\t\tinput: async (ctx) => ({ ctx: { ...wrapDB(ctx), include }, args: {} }),\n\t\t}),\n\t\tsystemAction: zCustomAction(config.internalAction, {\n\t\t\targs: {},\n\t\t\tinput: async (ctx) => ({ ctx, args: {} }),\n\t\t}),\n\t}\n}\n"],"mappings":"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"}