@vertz/server 0.2.16 → 0.2.17

package/dist/index.d.ts

@@ -1809,6 +1809,43 @@ interface RelationConfigObject<TColumnKeys extends string = string> {
 	readonly maxLimit?: number;
 }
 type EntityRelationsConfig<TRelations extends Record<string, RelationDef2> = Record<string, RelationDef2>> = { [K in keyof TRelations]? : true | false | RelationConfigObject<RelationColumnKeys<TRelations[K]>> };
+/** Extract the target table type from a RelationDef. */
+type RelationTargetTable<R> = R extends RelationDef2<infer T> ? T : TableDef;
+/** Structured expose config for a relation. Controls field, filter, sort, and nested relation exposure. */
+interface RelationExposeConfig<R extends RelationDef2 = RelationDef2> {
+	/** Which fields of the related entity to expose. */
+	readonly select: { [K in PublicColumnKeys<RelationTargetTable<R>>]? : true | AccessRule };
+	/** Which fields clients can filter on via VertzQL `where`. */
+	readonly allowWhere?: { [K in PublicColumnKeys<RelationTargetTable<R>>]? : true | AccessRule };
+	/** Which fields clients can sort on via VertzQL `orderBy`. */
+	readonly allowOrderBy?: { [K in PublicColumnKeys<RelationTargetTable<R>>]? : true | AccessRule };
+	/** Max items returned per parent row. Defaults to DEFAULT_RELATION_LIMIT. */
+	readonly maxLimit?: number;
+	/** Nested relation exposure (loosely typed — target model relations not available from RelationDef). */
+	readonly include?: Record<string, true | false | RelationExposeConfig>;
+}
+/** Controls which fields, filters, sorts, and relations are exposed through the entity API. */
+interface ExposeConfig<
+	TTable extends TableDef = TableDef,
+	TModel extends ModelDef4 = ModelDef4
+> {
+	/** Which fields of the entity to expose. Required when expose is present. */
+	readonly select: { [K in PublicColumnKeys<TTable>]? : true | AccessRule };
+	/** Which fields clients can filter on via VertzQL `where`. */
+	readonly allowWhere?: { [K in PublicColumnKeys<TTable>]? : true | AccessRule };
+	/** Which fields clients can sort on via VertzQL `orderBy`. */
+	readonly allowOrderBy?: { [K in PublicColumnKeys<TTable>]? : true | AccessRule };
+	/** Which relations to expose and how. */
+	readonly include?: { [K in keyof TModel["relations"]]? : true | false | RelationExposeConfig<TModel["relations"][K] extends RelationDef2 ? TModel["relations"][K] : RelationDef2> };
+}
+/** Extract non-hidden column keys from a table (public fields). */
+type PublicColumnKeys<TTable extends TableDef> = TTable extends TableDef<infer TCols> ? { [K in keyof TCols & string] : TCols[K] extends {
+	_meta: {
+		_annotations: {
+			hidden: true;
+		};
+	};
+} ? never : K }[keyof TCols & string] : string;
 interface EntityConfig<
 	TModel extends ModelDef4 = ModelDef4,
 	TActions extends Record<string, EntityActionDef<any, any, any, any>> = {},
@@ -1831,7 +1868,7 @@ interface EntityConfig<
 		readonly delete?: (row: TModel["table"]["$response"], ctx: EntityContext<TModel, TInject>) => void | Promise<void>;
 	};
 	readonly actions?: { readonly [K in keyof TActions] : TActions[K] };
-	readonly relations?: EntityRelationsConfig<TModel["relations"]>;
+	readonly expose?: ExposeConfig<TModel["table"], TModel>;
 }
 interface EntityDefinition<TModel extends ModelDef4 = ModelDef4> {
 	readonly kind: "entity";
@@ -1842,7 +1879,7 @@ interface EntityDefinition<TModel extends ModelDef4 = ModelDef4> {
 	readonly before: EntityBeforeHooks;
 	readonly after: EntityAfterHooks;
 	readonly actions: Record<string, EntityActionDef>;
-	readonly relations: EntityRelationsConfig<TModel["relations"]>;
+	readonly expose?: ExposeConfig<TModel["table"], TModel>;
 	/** DB table name (defaults to entity name). */
 	readonly table: string;
 	/** Whether CRUD auto-filters by tenantId. */
@@ -2042,4 +2079,4 @@ declare function service<
 	TInject extends Record<string, EntityDefinition> = {},
 	TActions extends Record<string, ServiceActionDef<any, any, any>> = Record<string, ServiceActionDef<any, any, any>>
 >(name: string, config: ServiceConfig<TActions, TInject>): ServiceDefinition;
-export { vertz, verifyPassword, validatePassword, validateOverrides, validateAuthModels, stripReadOnlyFields, stripHiddenFields, service, rules, resolveTenantChain, makeImmutable, isContentDescriptor, initializeAuthTables, hashPassword, google, github, getIncompatibleAddOns, generateEntityRoutes, entityErrorHandler, entity, enforceAccess, encodeAccessSet, discord, defineAccess, defaultAccess, deepFreeze, decodeAccessSet, createWebhookHandler, createStripeBillingAdapter, createServer, createPlanManager, createMiddleware, createImmutableProxy, createEnv, createEntityContext, createCrudHandlers, createBillingEventEmitter, createAuth, createAccessEventBroadcaster, createAccessContext, createAccess, content, computePlanHash, computeOverage, computeEntityAccess, computeAccessSet, checkFva, checkAddOnCompatibility, calculateBillingPeriod, authModels, WebhookHandlerConfig, WalletStore, WalletEntry, VertzException, ValidationException, UserTableEntry, UserStore, UnauthorizedException, TenantOverrides, TenantChainHop, TenantChain, SubscriptionStore, Subscription, StripeProduct, StripePrice, StripeClient, StripeBillingAdapterConfig, StoredSession, StoredPasswordReset, StoredEmailVerification, SignUpInput, SignInInput, SessionStrategy, SessionStore, SessionPayload, SessionInfo, SessionConfig, Session, ServiceUnavailableException, ServiceRequestInfo, ServiceDefinition, ServiceContext, ServiceConfig, ServiceActionDef, ServerInstance, ServerHandle, ServerConfig, ServerAdapter, RuleContext, RoleAssignmentTableEntry, RoleAssignmentStore, RoleAssignment, ResourceRef, Resource, RequestInfo, RawRequest, RateLimitStore, RateLimitResult, RateLimitConfig, PriceInterval, PlanVersionStore, PlanVersionInfo, PlanSnapshot, PlanPrice, PlanHashInput, PlanDef, Period, PasswordResetStore, PasswordResetConfig, PasswordRequirements, ParentRef, OverrideStore, OverageInput, OverageConfig, OnUserCreatedPayload, OAuthUserInfo, OAuthTokens, OAuthProviderConfig, OAuthProvider, OAuthAccountStore, NotFoundException, NamedMiddlewareDef, MiddlewareDef, MfaSetupData, MfaConfig, MfaChallengeData, MFAStore, ListenOptions, ListResult, ListOptions2 as ListOptions, LimitOverrideDef, LimitOverride, LimitDef, InternalServerErrorException, InferSchema, Infer2 as Infer, InMemoryWalletStore, InMemoryUserStore, InMemorySubscriptionStore, InMemorySessionStore, InMemoryRoleAssignmentStore, InMemoryRateLimitStore, InMemoryPlanVersionStore, InMemoryPasswordResetStore, InMemoryOverrideStore, InMemoryOAuthAccountStore, InMemoryMFAStore, InMemoryGrandfatheringStore, InMemoryFlagStore, InMemoryEmailVerificationStore, InMemoryClosureStore, HttpStatusCode, HttpMethod, HandlerCtx, GrandfatheringStore, GrandfatheringState, ForbiddenException, FlagStore, EnvConfig, EntityRouteOptions, EntityRelationsConfig, EntityRegistry, EntityOperations, EntityErrorResult, EntityDefinition, EntityDef, EntityDbAdapter2 as EntityDbAdapter, EntityContext, EntityConfig, EntityActionDef, EntitlementValue, EntitlementRegistry, EntitlementDefinition, EntitlementDef, Entitlement, EncodedAccessSet, EmailVerificationStore, EmailVerificationConfig, EmailPasswordConfig, Deps, DenialReason, DenialMeta, DefineAccessInput, DeepReadonly, DbUserStore, DbSubscriptionStore, DbSessionStore, DbRoleAssignmentStore, DbOAuthAccountStore, DbFlagStore, DbDialectName, DbClosureStore, Ctx, CrudResult, CrudHandlers, CorsConfig, CookieConfig, ContentDescriptor, ConsumeResult, ConflictException, ComputeAccessSetConfig, ClosureStore, ClosureRow, ClosureEntry, BillingPeriod, BillingEventType, BillingEventHandler, BillingEventEmitter, BillingEvent, BillingAdapter, BaseContext, BadRequestException, AuthorizationError, AuthUser, AuthTokens, AuthInstance, AuthEntityProxy, AuthDbClient, AuthContext, AuthConfig, AuthCallbackContext, AuthApi, AppConfig2 as AppConfig, AppBuilder2 as AppBuilder, AddOnRequires, AclClaim, AccumulateProvides, AccessWsData, AccessSet, AccessRule2 as AccessRule, AccessInstance, AccessEventBroadcasterConfig, AccessEventBroadcaster, AccessEvent, AccessDefinition, AccessContextConfig, AccessContext, AccessConfig, AccessCheckResult, AccessCheckData, AUTH_TABLE_NAMES };
+export { vertz, verifyPassword, validatePassword, validateOverrides, validateAuthModels, stripReadOnlyFields, stripHiddenFields, service, rules, resolveTenantChain, makeImmutable, isContentDescriptor, initializeAuthTables, hashPassword, google, github, getIncompatibleAddOns, generateEntityRoutes, entityErrorHandler, entity, enforceAccess, encodeAccessSet, discord, defineAccess, defaultAccess, deepFreeze, decodeAccessSet, createWebhookHandler, createStripeBillingAdapter, createServer, createPlanManager, createMiddleware, createImmutableProxy, createEnv, createEntityContext, createCrudHandlers, createBillingEventEmitter, createAuth, createAccessEventBroadcaster, createAccessContext, createAccess, content, computePlanHash, computeOverage, computeEntityAccess, computeAccessSet, checkFva, checkAddOnCompatibility, calculateBillingPeriod, authModels, WebhookHandlerConfig, WalletStore, WalletEntry, VertzException, ValidationException, UserTableEntry, UserStore, UnauthorizedException, TenantOverrides, TenantChainHop, TenantChain, SubscriptionStore, Subscription, StripeProduct, StripePrice, StripeClient, StripeBillingAdapterConfig, StoredSession, StoredPasswordReset, StoredEmailVerification, SignUpInput, SignInInput, SessionStrategy, SessionStore, SessionPayload, SessionInfo, SessionConfig, Session, ServiceUnavailableException, ServiceRequestInfo, ServiceDefinition, ServiceContext, ServiceConfig, ServiceActionDef, ServerInstance, ServerHandle, ServerConfig, ServerAdapter, RuleContext, RoleAssignmentTableEntry, RoleAssignmentStore, RoleAssignment, ResourceRef, Resource, RequestInfo, RelationExposeConfig, RawRequest, RateLimitStore, RateLimitResult, RateLimitConfig, PriceInterval, PlanVersionStore, PlanVersionInfo, PlanSnapshot, PlanPrice, PlanHashInput, PlanDef, Period, PasswordResetStore, PasswordResetConfig, PasswordRequirements, ParentRef, OverrideStore, OverageInput, OverageConfig, OnUserCreatedPayload, OAuthUserInfo, OAuthTokens, OAuthProviderConfig, OAuthProvider, OAuthAccountStore, NotFoundException, NamedMiddlewareDef, MiddlewareDef, MfaSetupData, MfaConfig, MfaChallengeData, MFAStore, ListenOptions, ListResult, ListOptions2 as ListOptions, LimitOverrideDef, LimitOverride, LimitDef, InternalServerErrorException, InferSchema, Infer2 as Infer, InMemoryWalletStore, InMemoryUserStore, InMemorySubscriptionStore, InMemorySessionStore, InMemoryRoleAssignmentStore, InMemoryRateLimitStore, InMemoryPlanVersionStore, InMemoryPasswordResetStore, InMemoryOverrideStore, InMemoryOAuthAccountStore, InMemoryMFAStore, InMemoryGrandfatheringStore, InMemoryFlagStore, InMemoryEmailVerificationStore, InMemoryClosureStore, HttpStatusCode, HttpMethod, HandlerCtx, GrandfatheringStore, GrandfatheringState, ForbiddenException, FlagStore, ExposeConfig, EnvConfig, EntityRouteOptions, EntityRelationsConfig, EntityRegistry, EntityOperations, EntityErrorResult, EntityDefinition, EntityDef, EntityDbAdapter2 as EntityDbAdapter, EntityContext, EntityConfig, EntityActionDef, EntitlementValue, EntitlementRegistry, EntitlementDefinition, EntitlementDef, Entitlement, EncodedAccessSet, EmailVerificationStore, EmailVerificationConfig, EmailPasswordConfig, Deps, DenialReason, DenialMeta, DefineAccessInput, DeepReadonly, DbUserStore, DbSubscriptionStore, DbSessionStore, DbRoleAssignmentStore, DbOAuthAccountStore, DbFlagStore, DbDialectName, DbClosureStore, Ctx, CrudResult, CrudHandlers, CorsConfig, CookieConfig, ContentDescriptor, ConsumeResult, ConflictException, ComputeAccessSetConfig, ClosureStore, ClosureRow, ClosureEntry, BillingPeriod, BillingEventType, BillingEventHandler, BillingEventEmitter, BillingEvent, BillingAdapter, BaseContext, BadRequestException, AuthorizationError, AuthUser, AuthTokens, AuthInstance, AuthEntityProxy, AuthDbClient, AuthContext, AuthConfig, AuthCallbackContext, AuthApi, AppConfig2 as AppConfig, AppBuilder2 as AppBuilder, AddOnRequires, AclClaim, AccumulateProvides, AccessWsData, AccessSet, AccessRule2 as AccessRule, AccessInstance, AccessEventBroadcasterConfig, AccessEventBroadcaster, AccessEvent, AccessDefinition, AccessContextConfig, AccessContext, AccessConfig, AccessCheckResult, AccessCheckData, AUTH_TABLE_NAMES };

package/dist/index.js

@@ -5992,6 +5992,15 @@ function applySelect(select, data) {
   }
   return result;
 }
+function nullGuardedFields(nulledFields, data) {
+  if (nulledFields.size === 0)
+    return data;
+  const result = {};
+  for (const [key, value] of Object.entries(data)) {
+    result[key] = nulledFields.has(key) ? null : value;
+  }
+  return result;
+}
 function stripReadOnlyFields(table, data) {
   const excludedKeys = new Set;
   for (const key of Object.keys(table._columns)) {
@@ -6241,6 +6250,10 @@ function createCrudHandlers(def, db, options) {
   const tenantChain = options?.tenantChain ?? def.tenantChain ?? null;
   const isIndirectlyScoped = tenantChain !== null;
   const queryParentIds = options?.queryParentIds ?? null;
+  const exposeSelect = def.expose?.select ? {
+    ...def.expose.select,
+    ...Object.fromEntries(Object.entries(def.expose.include ?? {}).filter(([, v]) => v !== false).map(([k]) => [k, true]))
+  } : undefined;
   function notFound(id) {
     return err4(new EntityNotFoundError2(`${def.name} with id "${id}" not found`));
   }
@@ -6311,7 +6324,7 @@ function createCrudHandlers(def, db, options) {
       const orderBy = options2?.orderBy;
       const include = options2?.include;
       const { data: rows, total } = await db.list({ where, orderBy, limit, after, include });
-      const data = rows.map((row) => narrowRelationFields(def.relations, stripHiddenFields(table, row)));
+      const data = rows.map((row) => applySelect(exposeSelect, narrowRelationFields(def.expose?.include ?? {}, stripHiddenFields(table, row))));
       const pkColumn = resolvePrimaryKeyColumn(table);
       const lastRow = rows[rows.length - 1];
       const nextCursor = limit > 0 && rows.length === limit && lastRow ? String(lastRow[pkColumn]) : null;
@@ -6333,7 +6346,7 @@ function createCrudHandlers(def, db, options) {
         return err4(accessResult.error);
       return ok4({
         status: 200,
-        body: narrowRelationFields(def.relations, stripHiddenFields(table, row))
+        body: applySelect(exposeSelect, narrowRelationFields(def.expose?.include ?? {}, stripHiddenFields(table, row)))
       });
     },
     async create(ctx, data) {
@@ -6376,7 +6389,7 @@ function createCrudHandlers(def, db, options) {
       }
       return ok4({
         status: 201,
-        body: narrowRelationFields(def.relations, strippedResult)
+        body: applySelect(exposeSelect, narrowRelationFields(def.expose?.include ?? {}, strippedResult))
       });
     },
     async update(ctx, id, data) {
@@ -6405,7 +6418,7 @@ function createCrudHandlers(def, db, options) {
       }
       return ok4({
         status: 200,
-        body: narrowRelationFields(def.relations, strippedResult)
+        body: applySelect(exposeSelect, narrowRelationFields(def.expose?.include ?? {}, strippedResult))
       });
     },
     async delete(ctx, id) {
@@ -6493,7 +6506,101 @@ function entityErrorHandler(error) {
   };
 }
 
+// src/entity/expose-evaluator.ts
+async function evaluateExposeRule(rule, ctx, options) {
+  switch (rule.type) {
+    case "public":
+      return true;
+    case "authenticated":
+      return ctx.authenticated();
+    case "role":
+      return ctx.role(...rule.roles);
+    case "entitlement": {
+      if (!options.can)
+        return false;
+      return options.can(rule.entitlement);
+    }
+    case "where":
+      return false;
+    case "all": {
+      for (const sub of rule.rules) {
+        if (!await evaluateExposeRule(sub, ctx, options))
+          return false;
+      }
+      return true;
+    }
+    case "any": {
+      for (const sub of rule.rules) {
+        if (await evaluateExposeRule(sub, ctx, options))
+          return true;
+      }
+      return false;
+    }
+    case "fva": {
+      if (options.fvaAge === undefined)
+        return false;
+      return options.fvaAge <= rule.maxAge;
+    }
+  }
+}
+async function evaluateExposeDescriptors(expose, ctx, options = {}) {
+  const allowedSelectFields = new Set;
+  const nulledFields = new Set;
+  const allowedWhereFields = new Set;
+  const allowedOrderByFields = new Set;
+  for (const [field, value] of Object.entries(expose.select)) {
+    if (value === true) {
+      allowedSelectFields.add(field);
+    } else {
+      const passed = await evaluateExposeRule(value, ctx, options);
+      if (passed) {
+        allowedSelectFields.add(field);
+      } else {
+        allowedSelectFields.add(field);
+        nulledFields.add(field);
+      }
+    }
+  }
+  if (expose.allowWhere) {
+    for (const [field, value] of Object.entries(expose.allowWhere)) {
+      if (value === true) {
+        allowedWhereFields.add(field);
+      } else {
+        const passed = await evaluateExposeRule(value, ctx, options);
+        if (passed) {
+          allowedWhereFields.add(field);
+        }
+      }
+    }
+  }
+  if (expose.allowOrderBy) {
+    for (const [field, value] of Object.entries(expose.allowOrderBy)) {
+      if (value === true) {
+        allowedOrderByFields.add(field);
+      } else {
+        const passed = await evaluateExposeRule(value, ctx, options);
+        if (passed) {
+          allowedOrderByFields.add(field);
+        }
+      }
+    }
+  }
+  return {
+    allowedSelectFields,
+    nulledFields,
+    allowedWhereFields,
+    allowedOrderByFields
+  };
+}
+
 // src/entity/vertzql-parser.ts
+function extractAllowKeys(allow) {
+  if (!allow)
+    return [];
+  if (Array.isArray(allow))
+    return allow;
+  return Object.keys(allow);
+}
 var MAX_LIMIT = 1000;
 var MAX_Q_BASE64_LENGTH = 10240;
 var ALLOWED_Q_KEYS = new Set(["select", "include", "where", "orderBy", "limit", "offset"]);
@@ -6579,30 +6686,50 @@ function getHiddenColumns(table) {
   }
   return hidden;
 }
-function validateVertzQL(options, table, relationsConfig) {
+function validateVertzQL(options, table, relationsConfig, exposeConfig, evaluatedExpose) {
   if (options._qError) {
     return { ok: false, error: options._qError };
   }
   const hiddenColumns = getHiddenColumns(table);
   if (options.where) {
+    const allowWhereSet = evaluatedExpose ? evaluatedExpose.allowedWhereFields : null;
+    const allowWhereKeys = !evaluatedExpose && exposeConfig ? extractAllowKeys(exposeConfig.allowWhere) : null;
     for (const field of Object.keys(options.where)) {
       if (hiddenColumns.has(field)) {
         return { ok: false, error: `Field "${field}" is not filterable` };
       }
+      if (allowWhereSet !== null && !allowWhereSet.has(field)) {
+        return { ok: false, error: `Field "${field}" is not filterable` };
+      }
+      if (allowWhereKeys !== null && !allowWhereKeys.includes(field)) {
+        return { ok: false, error: `Field "${field}" is not filterable` };
+      }
     }
   }
   if (options.orderBy) {
+    const allowOrderBySet = evaluatedExpose ? evaluatedExpose.allowedOrderByFields : null;
+    const allowOrderByKeys = !evaluatedExpose && exposeConfig ? extractAllowKeys(exposeConfig.allowOrderBy) : null;
     for (const field of Object.keys(options.orderBy)) {
       if (hiddenColumns.has(field)) {
         return { ok: false, error: `Field "${field}" is not sortable` };
       }
+      if (allowOrderBySet !== null && !allowOrderBySet.has(field)) {
+        return { ok: false, error: `Field "${field}" is not sortable` };
+      }
+      if (allowOrderByKeys !== null && !allowOrderByKeys.includes(field)) {
+        return { ok: false, error: `Field "${field}" is not sortable` };
+      }
     }
   }
   if (options.select) {
+    const exposeSelectKeys = exposeConfig ? extractAllowKeys(exposeConfig.select) : null;
     for (const field of Object.keys(options.select)) {
       if (hiddenColumns.has(field)) {
         return { ok: false, error: `Field "${field}" is not selectable` };
       }
+      if (exposeSelectKeys !== null && exposeSelectKeys.length > 0 && !exposeSelectKeys.includes(field)) {
+        return { ok: false, error: `Field "${field}" is not selectable` };
+      }
     }
   }
   if (options.include && relationsConfig) {
@@ -6623,35 +6750,37 @@ function validateInclude(include, relationsConfig, pathPrefix) {
       continue;
     const configObj = typeof entityConfig === "object" ? entityConfig : undefined;
     if (requested.where) {
-      if (!configObj || !configObj.allowWhere || configObj.allowWhere.length === 0) {
+      const allowWhereKeys = extractAllowKeys(configObj?.allowWhere);
+      if (!configObj || allowWhereKeys.length === 0) {
         return {
           ok: false,
           error: `Filtering is not enabled on relation '${relationPath}'. ` + "Add 'allowWhere' to the entity relations config."
         };
       }
-      const allowedSet = new Set(configObj.allowWhere);
+      const allowedSet = new Set(allowWhereKeys);
       for (const field of Object.keys(requested.where)) {
         if (!allowedSet.has(field)) {
           return {
             ok: false,
-            error: `Field '${field}' is not filterable on relation '${relationPath}'. ` + `Allowed: ${configObj.allowWhere.join(", ")}`
+            error: `Field '${field}' is not filterable on relation '${relationPath}'. ` + `Allowed: ${allowWhereKeys.join(", ")}`
           };
         }
       }
     }
     if (requested.orderBy) {
-      if (!configObj || !configObj.allowOrderBy || configObj.allowOrderBy.length === 0) {
+      const allowOrderByKeys = extractAllowKeys(configObj?.allowOrderBy);
+      if (!configObj || allowOrderByKeys.length === 0) {
         return {
           ok: false,
           error: `Sorting is not enabled on relation '${relationPath}'. ` + "Add 'allowOrderBy' to the entity relations config."
         };
       }
-      const allowedSet = new Set(configObj.allowOrderBy);
+      const allowedSet = new Set(allowOrderByKeys);
       for (const [field, dir] of Object.entries(requested.orderBy)) {
         if (!allowedSet.has(field)) {
           return {
             ok: false,
-            error: `Field '${field}' is not sortable on relation '${relationPath}'. ` + `Allowed: ${configObj.allowOrderBy.join(", ")}`
+            error: `Field '${field}' is not sortable on relation '${relationPath}'. ` + `Allowed: ${allowOrderByKeys.join(", ")}`
           };
         }
         if (dir !== "asc" && dir !== "desc") {
@@ -6718,10 +6847,27 @@ function extractRequestInfo(ctx) {
 function getParams(ctx) {
   return ctx.params ?? {};
 }
+function hasDescriptorValues(record) {
+  if (!record)
+    return false;
+  return Object.values(record).some((v) => v !== true);
+}
+function hasDescriptors(expose) {
+  return hasDescriptorValues(expose.select) || hasDescriptorValues(expose.allowWhere) || hasDescriptorValues(expose.allowOrderBy);
+}
+function applyNulling(data, nulledFields) {
+  return nullGuardedFields(nulledFields, data);
+}
 function generateEntityRoutes(def, registry, db, options) {
   const prefix = options?.apiPrefix ?? "/api";
   const basePath = `${prefix}/${def.name}`;
   const tenantChain = options?.tenantChain ?? null;
+  const exposeValidation = def.expose ? {
+    select: def.expose.select,
+    allowWhere: def.expose.allowWhere,
+    allowOrderBy: def.expose.allowOrderBy
+  } : undefined;
+  const exposeEvalConfig = def.expose ? hasDescriptors(def.expose) ? def.expose : null : null;
   const crudHandlers = createCrudHandlers(def, db, {
     tenantChain,
     queryParentIds: options?.queryParentIds
@@ -6755,8 +6901,9 @@ function generateEntityRoutes(def, registry, db, options) {
             const entityCtx = makeEntityCtx(ctx);
             const query = ctx.query ?? {};
             const parsed = parseVertzQL(query);
-            const relationsConfig = def.relations;
-            const validation = validateVertzQL(parsed, def.model.table, relationsConfig);
+            const evaluated = exposeEvalConfig ? await evaluateExposeDescriptors(exposeEvalConfig, entityCtx) : null;
+            const relationsConfig = def.expose?.include ?? {};
+            const validation = validateVertzQL(parsed, def.model.table, relationsConfig, exposeValidation, evaluated ?? undefined);
             if (!validation.ok) {
               return jsonResponse({ error: { code: "BadRequest", message: validation.error } }, 400);
             }
@@ -6772,6 +6919,9 @@ function generateEntityRoutes(def, registry, db, options) {
               const { status, body } = entityErrorHandler(result.error);
               return jsonResponse(body, status);
             }
+            if (evaluated && evaluated.nulledFields.size > 0 && result.data.body.items) {
+              result.data.body.items = result.data.body.items.map((row) => applyNulling(row, evaluated.nulledFields));
+            }
             if (parsed.select && result.data.body.items) {
               result.data.body.items = result.data.body.items.map((row) => applySelect(parsed.select, row));
             }
@@ -6798,8 +6948,9 @@ function generateEntityRoutes(def, registry, db, options) {
             select: body.select,
             include: body.include
           };
-          const relationsConfig = def.relations;
-          const validation = validateVertzQL(parsed, def.model.table, relationsConfig);
+          const evaluated = exposeEvalConfig ? await evaluateExposeDescriptors(exposeEvalConfig, entityCtx) : null;
+          const relationsConfig = def.expose?.include ?? {};
+          const validation = validateVertzQL(parsed, def.model.table, relationsConfig, exposeValidation, evaluated ?? undefined);
           if (!validation.ok) {
             return jsonResponse({ error: { code: "BadRequest", message: validation.error } }, 400);
           }
@@ -6815,6 +6966,9 @@ function generateEntityRoutes(def, registry, db, options) {
             const { status, body: errBody } = entityErrorHandler(result.error);
             return jsonResponse(errBody, status);
           }
+          if (evaluated && evaluated.nulledFields.size > 0 && result.data.body.items) {
+            result.data.body.items = result.data.body.items.map((row) => applyNulling(row, evaluated.nulledFields));
+          }
           if (parsed.select && result.data.body.items) {
             result.data.body.items = result.data.body.items.map((row) => applySelect(parsed.select, row));
           }
@@ -6848,8 +7002,9 @@ function generateEntityRoutes(def, registry, db, options) {
             const id = getParams(ctx).id;
             const query = ctx.query ?? {};
             const parsed = parseVertzQL(query);
-            const relationsConfig = def.relations;
-            const validation = validateVertzQL(parsed, def.model.table, relationsConfig);
+            const evaluated = exposeEvalConfig ? await evaluateExposeDescriptors(exposeEvalConfig, entityCtx) : null;
+            const relationsConfig = def.expose?.include ?? {};
+            const validation = validateVertzQL(parsed, def.model.table, relationsConfig, exposeValidation, evaluated ?? undefined);
             if (!validation.ok) {
               return jsonResponse({ error: { code: "BadRequest", message: validation.error } }, 400);
             }
@@ -6859,7 +7014,11 @@ function generateEntityRoutes(def, registry, db, options) {
               const { status, body: body2 } = entityErrorHandler(result.error);
               return jsonResponse(body2, status);
             }
-            const body = parsed.select ? applySelect(parsed.select, result.data.body) : result.data.body;
+            let responseBody = result.data.body;
+            if (evaluated && evaluated.nulledFields.size > 0) {
+              responseBody = applyNulling(responseBody, evaluated.nulledFields);
+            }
+            const body = parsed.select ? applySelect(parsed.select, responseBody) : responseBody;
             return jsonResponse(body, result.data.status);
           } catch (error) {
             const { status, body } = entityErrorHandler(error);
@@ -6894,7 +7053,14 @@ function generateEntityRoutes(def, registry, db, options) {
               const { status, body } = entityErrorHandler(result.error);
               return jsonResponse(body, status);
             }
-            return jsonResponse(result.data.body, result.data.status);
+            let responseBody = result.data.body;
+            if (exposeEvalConfig) {
+              const evaluated = await evaluateExposeDescriptors(exposeEvalConfig, entityCtx);
+              if (evaluated.nulledFields.size > 0) {
+                responseBody = applyNulling(responseBody, evaluated.nulledFields);
+              }
+            }
+            return jsonResponse(responseBody, result.data.status);
           } catch (error) {
             const { status, body } = entityErrorHandler(error);
             return jsonResponse(body, status);
@@ -6929,7 +7095,14 @@ function generateEntityRoutes(def, registry, db, options) {
               const { status, body } = entityErrorHandler(result.error);
               return jsonResponse(body, status);
             }
-            return jsonResponse(result.data.body, result.data.status);
+            let responseBody = result.data.body;
+            if (exposeEvalConfig) {
+              const evaluated = await evaluateExposeDescriptors(exposeEvalConfig, entityCtx);
+              if (evaluated.nulledFields.size > 0) {
+                responseBody = applyNulling(responseBody, evaluated.nulledFields);
+              }
+            }
+            return jsonResponse(responseBody, result.data.status);
           } catch (error) {
             const { status, body } = entityErrorHandler(error);
             return jsonResponse(body, status);
@@ -7447,7 +7620,7 @@ function entity(name, config) {
     before: config.before ?? {},
     after: config.after ?? {},
     actions: config.actions ?? {},
-    relations: config.relations ?? {},
+    expose: config.expose,
     table: config.table ?? name,
     tenantScoped,
     tenantChain: null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/server",
-  "version": "0.2.16",
+  "version": "0.2.17",
   "type": "module",
   "license": "MIT",
   "description": "Vertz server runtime — modules, routing, and auth",
@@ -31,10 +31,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@vertz/core": "^0.2.15",
-    "@vertz/db": "^0.2.15",
-    "@vertz/errors": "^0.2.15",
-    "@vertz/schema": "^0.2.15",
+    "@vertz/core": "^0.2.16",
+    "@vertz/db": "^0.2.16",
+    "@vertz/errors": "^0.2.16",
+    "@vertz/schema": "^0.2.16",
     "bcryptjs": "^3.0.3",
     "jose": "^6.0.11"
   },