@everystack/api 0.4.9 → 0.4.10

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.10] - 2026-10-18
+
+### BREAKING CHANGES
+
+- an aggregate inside an embed (author(count())) answers 400 instead of being dropped, on every verb including writes that carry such a select
+- a nested embed on the join path (drizzleRelations) answers 400 instead of being dropped, on every verb including writes that carry such a select; the batch path now keeps nested embeds and accepts snake_case embed column names
+
+### Fixed
+
+- table-keyed option maps are read by own key, so a table named constructor reads no prototype value
+
 ## [0.4.9] - 2026-10-18
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/handler/index.ts

@@ -216,7 +216,11 @@ export interface AuthConfig {
   /** Ordered role hierarchy, lowest to highest privilege.
    *  Used by RPC role gating. Default: ['public', 'authenticated', 'admin'] */
   roleHierarchy?: string[];
-  /** Field in the user payload containing the role string. Used by RPC role gating. Default: 'role' */
+  /** Field in the user payload containing the role string. Default: 'role'
+   *  `roleField` must hold one string. A missing, non-string or array value is treated as
+   *  no role and fails every gate; if your tokens carry several roles, collapse them to one
+   *  in `auth.verifyToken` before the payload reaches the handler, so the RPC, ownership,
+   *  restore (`PATCH ?deleted=`) gates and your `pgSettings` all read the same value. */
   roleField?: string;
 }
 
@@ -339,7 +343,8 @@ export interface HandlerOptions {
   drizzleRelations?: Record<string, unknown>;
   /** Compute PostgreSQL session variables from the authenticated user.
    *  When provided, queries are wrapped in a transaction with set_config() calls
-   *  so RLS policies can reference the user context. */
+   *  so RLS policies can reference the user context.
+   *  Read the same field `roleField` names. Do not derive the database role from a different claim. */
   pgSettings?: (user: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Record<string, string>;
   /** Per-table lifecycle hooks for mutations. */
   hooks?: Record<string, HookConfig>;
@@ -637,7 +642,7 @@ function stripProtectedFields(
   tableName: string,
   options?: HandlerOptions,
 ): unknown {
-  const fields = options?.protectedFields?.[tableName];
+  const fields = ownEntry(options?.protectedFields, tableName);
   if (!fields || fields.length === 0) return body;
   if (Array.isArray(body)) return body.map(row => stripProtectedFields(row, tableName, options));
   if (body === null || typeof body !== 'object') {
@@ -655,7 +660,7 @@ function stripHiddenColumns(
   tableName: string,
   options?: HandlerOptions,
 ): unknown {
-  const columns = options?.hiddenColumns?.[tableName];
+  const columns = ownEntry(options?.hiddenColumns, tableName);
   if (!columns || columns.length === 0) return data;
 
   const strip = (row: Record<string, unknown>): Record<string, unknown> => {
@@ -928,7 +933,7 @@ function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | und
     const sameColumn = (field: string): boolean => (table
       ? getColumn(table, field) !== null && getColumn(table, field) === getColumn(table, colName)
       : toSnakeCase(field) === toSnakeCase(colName));
-    if (roles.length > 0 && (options?.protectedFields?.[tableName] ?? []).some(sameColumn)) {
+    if (roles.length > 0 && (ownEntry(options?.protectedFields, tableName) ?? []).some(sameColumn)) {
       throw new Error(
         `[everystack/api] softDelete.restore.${tableName}: the soft-delete column "${colName}" is in protectedFields.${tableName}, so every restore body is stripped to {}. Remove it from protectedFields.${tableName} or remove the restore entry.`,
       );
@@ -942,7 +947,7 @@ function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | und
  * non-string role claim is not a member.
  */
 function mayRestore(tableName: string, options: HandlerOptions | undefined, user: Record<string, unknown> | null): boolean {
-  const roles = options?.softDelete?.restore?.[tableName];
+  const roles = ownEntry(options?.softDelete?.restore, tableName);
   if (!roles?.length || !user) return false;
   const role = readRoleClaim(user, options?.auth?.roleField ?? 'role');
   return role !== '' && roles.includes(role);
@@ -1453,15 +1458,22 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
 
       // A part with parentheses is an aggregate or a declared embed. Anything
       // else cannot be honored, so refuse it rather than drop it from the rows.
+      // An aggregate inside an embed cannot be honored either, nor can a nested
+      // embed on the JOIN path: its `with` clause is one level deep.
       const tableRelations = ownEntry(options?.relations, tableName);
       if (!queryError) {
+        const joinPath = relationalQueryAvailable(routedDb, tableName, options);
         for (const selectParam of url.searchParams.getAll('select')) {
-          const { undeclared } = parseSelectParam(selectParam, tableRelations, options?.relations);
+          const { undeclared, embedAggregate, nestedEmbed } = parseSelectParam(selectParam, tableRelations, options?.relations);
           if (undeclared !== undefined) {
             queryError = undeclaredSelectPartMessage(undeclared);
             queryErrorEchoesInput = true;
             break;
           }
+          if (embedAggregate || (nestedEmbed && joinPath)) {
+            queryError = 'Invalid query';
+            break;
+          }
         }
       }
 
@@ -1583,6 +1595,14 @@ function columnPropertyName(table: DrizzleTable | undefined, name: string): stri
     ?? columns.find(([, value]) => (value as DrizzleColumn).name === name)?.[0];
 }
 
+/**
+ * A read with embeds takes the JOIN path when this holds. The pre-DB refusal of
+ * a nested embed and handleGet both ask it, so the two cannot disagree.
+ */
+function relationalQueryAvailable(db: DrizzleDb, tableName: string, options?: HandlerOptions): boolean {
+  return Boolean(ownEntry(options?.relations, tableName) && options?.drizzleRelations && (db as any).query?.[tableName]);
+}
+
 /** Build each relation's projection before Drizzle reads its values. */
 function buildWithClause(
   embeds: EmbedRequest[],
@@ -1600,7 +1620,7 @@ function buildWithClause(
     if (!relation) continue;
     hasEmbedded = true;
     const table = schema[relation.table];
-    const names = new Set(options?.hiddenColumns?.[relation.table] ?? []);
+    const names = new Set(ownEntry(options?.hiddenColumns, relation.table) ?? []);
     const hidden = new Set(table ? Object.keys(getTableColumns(table)).filter(name => names.has(name)) : []);
     const config: Record<string, any> = {};
     if (embed.columns !== null) {
@@ -1829,10 +1849,7 @@ async function handleGet(
 
   // Detect if Drizzle relational query (JOINs) should be used
   const tableRelations = ownEntry(options?.relations, tableName);
-  const useRelationalQuery = embeds.length > 0
-    && tableRelations
-    && options?.drizzleRelations
-    && (db as any).query?.[tableName];
+  const useRelationalQuery = embeds.length > 0 && relationalQueryAvailable(db, tableName, options);
 
   let rows: unknown[];
   const isHidden = (column: string): boolean => isHiddenColumn(schema, tableName, column, options);
@@ -1983,7 +2000,7 @@ function parseSelectParam(
   selectParam: string | null,
   tableRelations?: Record<string, RelationConfig>,
   allRelations?: Record<string, Record<string, RelationConfig>>,
-): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[]; undeclared?: string } {
+): { columns: string[] | null; embeds: EmbedRequest[]; aggregates: AggregateField[]; undeclared?: string; embedAggregate?: true; nestedEmbed?: true } {
   if (!selectParam) {
     return { columns: null, embeds: [], aggregates: [] };
   }
@@ -1995,6 +2012,11 @@ function parseSelectParam(
   // The first part with parentheses that is neither an aggregate nor a declared
   // embed, at any depth. The caller refuses the select; it is never a column.
   let undeclared: string | undefined;
+  // Aggregates exist at the top level only. One inside an embed, at any depth,
+  // cannot be honored, so the caller refuses the select.
+  let embedAggregate = false;
+  // An embed inside an embed, at any depth. The JOIN path cannot honour one yet.
+  let nestedEmbed = false;
 
   // Parse: split on commas, but respect parentheses
   const parts = splitSelectParam(selectParam);
@@ -2019,6 +2041,8 @@ function parseSelectParam(
       const targetRelations = ownEntry(allRelations, targetTableName);
       const inner = parseSelectParam(innerSelect, targetRelations, allRelations);
       undeclared ??= inner.undeclared;
+      if (inner.aggregates.length > 0 || inner.embedAggregate) embedAggregate = true;
+      if (inner.embeds.length > 0) nestedEmbed = true;
       embeds.push({
         name,
         columns: inner.columns,
@@ -2038,6 +2062,8 @@ function parseSelectParam(
     embeds,
     aggregates,
     ...(undeclared === undefined ? {} : { undeclared }),
+    ...(embedAggregate ? { embedAggregate: true as const } : {}),
+    ...(nestedEmbed ? { nestedEmbed: true as const } : {}),
   };
 }
 
@@ -2172,6 +2198,20 @@ function requestUsesHiddenColumn(
   return false;
 }
 
+/** The relation an embed names, when its target table and key exist. resolveEmbeds skips any other. */
+function resolveEmbedTarget(
+  schema: Schema,
+  tableRelations: Record<string, RelationConfig> | undefined,
+  name: string,
+): { relationConfig: RelationConfig; targetTable: DrizzleTable; targetColumn: DrizzleColumn } | null {
+  const relationConfig = ownEntry(tableRelations, name);
+  if (!relationConfig) return null;
+  const targetTable = schema[relationConfig.table];
+  if (!targetTable) return null;
+  const targetColumn = getColumn(targetTable, relationConfig.to);
+  return targetColumn ? { relationConfig, targetTable, targetColumn } : null;
+}
+
 /**
  * Resolve relation embeds by fetching related rows and nesting them.
  */
@@ -2190,14 +2230,18 @@ async function resolveEmbeds(
   const result = rows.map(r => ({ ...r }));
 
   for (const embed of embeds) {
-    const relationConfig = tableRelations[embed.name];
-    if (!relationConfig) continue;
-
-    const targetTable = schema[relationConfig.table];
-    if (!targetTable) continue;
-
-    const targetColumn = getColumn(targetTable, relationConfig.to);
-    if (!targetColumn) continue;
+    const target = resolveEmbedTarget(schema, tableRelations, embed.name);
+    if (!target) continue;
+    const { relationConfig, targetTable, targetColumn } = target;
+
+    // Rows are keyed by schema property, so pick by property name, as
+    // buildWithClause does. A nested embed is kept only when it resolves: an
+    // unresolved one is skipped below, and its name may be a real column.
+    const nestedRelations = ownEntry(options.relations, relationConfig.table);
+    const picked = embed.columns && [
+      ...embed.columns.map(name => columnPropertyName(targetTable, name)).filter((name): name is string => name !== undefined),
+      ...embed.embeds.filter(nested => resolveEmbedTarget(schema, nestedRelations, nested.name)).map(nested => nested.name),
+    ];
 
     // Build soft-delete filter for the target table
     const targetSdCol = isSoftDeleteTable(relationConfig.table, targetTable, options)
@@ -2238,9 +2282,7 @@ async function resolveEmbeds(
       for (const row of result) {
         const sourceVal = row[relationConfig.from];
         const matched = relatedRows.filter(r => r[relationConfig.to] === sourceVal);
-        row[embed.name] = embed.columns
-          ? matched.map(r => pickColumns(r, embed.columns!))
-          : matched;
+        row[embed.name] = picked ? matched.map(r => pickColumns(r, picked)) : matched;
       }
     } else {
       // Many-to-one: source.from is the FK, target.to is the PK
@@ -2285,7 +2327,7 @@ async function resolveEmbeds(
           row[embed.name] = null;
         } else {
           const related = index.get(fkVal) || null;
-          row[embed.name] = related && embed.columns ? pickColumns(related, embed.columns) : related;
+          row[embed.name] = related && picked ? pickColumns(related, picked) : related;
         }
       }
     }
@@ -2371,10 +2413,10 @@ function sanitizeWriteBody(
   at: { requestId?: string; name: string; method: string },
   deferred: Deferred[],
 ): { body: unknown; changed: string[] } | { refusal: Response } {
-  const columns = options?.sanitizeColumns?.[tableName];
+  const columns = ownEntry(options?.sanitizeColumns, tableName);
   if (!columns?.length) return { body, changed: [] };
   const keys = [...new Set(columns.map(name => columnPropertyName(table, name)!))];
-  const hidden = new Set((options?.hiddenColumns?.[tableName] ?? []).map(name => columnPropertyName(table, name)));
+  const hidden = new Set((ownEntry(options?.hiddenColumns, tableName) ?? []).map(name => columnPropertyName(table, name)));
   const refuse = (message: string, column: string): { refusal: Response } => {
     const fault: HandlerFault = {
       ...at, kind: 'rest', status: 500, table: sqlNameOf(table)!, column, message,
@@ -2456,7 +2498,7 @@ async function handlePost(
     throw err;
   }
 
-  const hook = options?.hooks?.[tableName];
+  const hook = ownEntry(options?.hooks, tableName);
 
   if (hook?.beforeCreate) {
     try {
@@ -2550,7 +2592,7 @@ async function handlePatch(
 
   // With the ownership backstop lifted, an unfiltered PATCH would write every row the
   // role's RLS allows. Refuse it, the same filter test DELETE applies to every caller.
-  const ownership = options?.rowOwnership?.[tableName];
+  const ownership = ownEntry(options?.rowOwnership, tableName);
   if (user && options && ownership && isOwnershipExempt(ownership, user, options)
     && buildsNoFilter(table, params)) {
     return json({ message: 'PATCH requires at least one filter when the ownership backstop is lifted for your role' }, 400);
@@ -2574,7 +2616,7 @@ async function handlePatch(
     return sanitizeError(filterResult.error, 400, options);
   }
 
-  const hook = options?.hooks?.[tableName];
+  const hook = ownEntry(options?.hooks, tableName);
 
   if (hook?.beforeUpdate) {
     try {
@@ -2666,7 +2708,7 @@ function unbackedExemptionRefusal(
   settings: Record<string, string> | undefined,
 ): string | null {
   if (method !== 'PATCH' && method !== 'DELETE') return null;
-  const ownership = options?.rowOwnership?.[tableName];
+  const ownership = ownEntry(options?.rowOwnership, tableName);
   if (!options || !ownership || !user || !isOwnershipExempt(ownership, user, options)) return null;
   if (settings?.['role']) return null;
   const message = `rowOwnership.${tableName}.exceptRoles: pgSettings returned no role for this request, so SET LOCAL ROLE did not run and no RLS policy backs the exemption. Write refused.`;
@@ -2714,7 +2756,7 @@ function ownershipScope(
   options: HandlerOptions | undefined,
   user: Record<string, unknown> | null,
 ): OwnershipScope {
-  const ownership = options?.rowOwnership?.[tableName];
+  const ownership = ownEntry(options?.rowOwnership, tableName);
   if (!options || !ownership) return { condition: null };
   if (!user) {
     return { refusal: json({ message: 'Unauthorized: this table requires an authenticated owner' }, 401) };
@@ -2763,7 +2805,7 @@ async function handleDelete(
     return sanitizeError(filterResult.error, 400, options);
   }
 
-  const hook = options?.hooks?.[tableName];
+  const hook = ownEntry(options?.hooks, tableName);
 
   if (hook?.beforeDelete) {
     try {