@everystack/api 0.4.8 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.9] - 2026-10-18
+
+### BREAKING CHANGES
+
+- PATCH and DELETE refuse a bad filter before running beforeUpdate or beforeDelete
+- a filter the handler cannot parse or build answers 400 instead of being dropped; a bare value, is.true, is.false and in.(..) inside an or() or and() group are refused, so @everystack/query raw maps need eq.
+- a repeated or= or and= now applies every group, ANDed, so a read or write that sent a second group matches fewer rows
+
+### Fixed
+
+- with hideSchemaErrors, an RPC 42501 and the role gate answer Forbidden without database text
+
+### Documentation
+
+- upgrade notes for strict filters, hook order and hidden RPC error text
+
 ## [0.4.8] - 2026-10-18
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "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

@@ -557,6 +557,7 @@ async function checkRoleAuth(
   requiredRole: string,
   request: Request,
   auth: AuthConfig,
+  hideSchemaErrors?: boolean,
 ): Promise<AuthResult> {
   if (requiredRole === 'public') {
     return { user: null, error: null };
@@ -577,7 +578,7 @@ async function checkRoleAuth(
   if (!hasRole(userRole, requiredRole, hierarchy)) {
     return {
       user: result.user,
-      error: json({ message: `Insufficient permissions: requires ${requiredRole} role` }, 403),
+      error: json({ message: hideSchemaErrors ? 'Forbidden' : `Insufficient permissions: requires ${requiredRole} role` }, 403),
     };
   }
 
@@ -1251,7 +1252,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
 
         // Per-RPC role check (object syntax: { fn, role })
         if (isObjectForm && entry.role && options?.auth) {
-          const roleResult = await checkRoleAuth(entry.role, request, options.auth);
+          const roleResult = await checkRoleAuth(entry.role, request, options.auth, options.hideSchemaErrors);
           if (roleResult.error) {
             await emitAuthOutage(options.onError, { requestId, kind: 'rpc', name: fnName, method }, roleResult.outage);
             return roleResult.error;
@@ -1361,6 +1362,10 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
           if (options?.hideSchemaErrors && status === 500) {
             return json({ message: 'Internal Server Error' }, 500);
           }
+          // PostgreSQL's 42501 text names functions and tables; 22023 and P0001 are the SQL author's channel and stay raw.
+          if (options?.hideSchemaErrors && pgCode === '42501') {
+            return json({ message: 'Forbidden', code: pgCode }, 403);
+          }
           return json({ message, ...(pgCode ? { code: pgCode } : {}) }, status);
         }
       }
@@ -2159,7 +2164,7 @@ function requestUsesHiddenColumn(
         return isHidden(tableName, (dot < 0 ? order : order.slice(0, dot)).trim());
       })) return true;
     } else if (key === 'or' || key === 'and') {
-      if (parseLogicalGroup(value).some(filter => isHidden(tableName, filter.column))) return true;
+      if (parseLogicalGroup(value).filters.some(filter => isHidden(tableName, filter.column))) return true;
     } else if (!RESERVED_QUERY_PARAMS.has(key) && isHidden(tableName, key)) {
       return true;
     }
@@ -2563,6 +2568,12 @@ async function handlePatch(
     if (key !== null) return json({ message: `Cannot change ownership column "${key}"` }, 403);
   }
 
+  // Before the hook, so a request that will answer 400 never runs app side effects.
+  const filterResult = buildAllConditions(table, params);
+  if ('error' in filterResult) {
+    return sanitizeError(filterResult.error, 400, options);
+  }
+
   const hook = options?.hooks?.[tableName];
 
   if (hook?.beforeUpdate) {
@@ -2584,10 +2595,6 @@ async function handlePatch(
   if ('refusal' in sanitized) return sanitized.refusal;
   body = sanitized.body as Record<string, unknown>;
 
-  const filterResult = buildAllConditions(table, params);
-  if ('error' in filterResult) {
-    return sanitizeError(filterResult.error, 400, options);
-  }
   const conditions = filterResult.conditions;
 
   // Soft-delete: update live records, unless a restore role sent ?deleted=include|only
@@ -2750,6 +2757,12 @@ async function handleDelete(
     return json({ message: 'DELETE requires at least one filter to prevent accidental mass deletion' }, 400);
   }
 
+  // Before the hook, so a request that will answer 400 never runs app side effects.
+  const filterResult = buildAllConditions(table, params);
+  if ('error' in filterResult) {
+    return sanitizeError(filterResult.error, 400, options);
+  }
+
   const hook = options?.hooks?.[tableName];
 
   if (hook?.beforeDelete) {
@@ -2760,10 +2773,6 @@ async function handleDelete(
     }
   }
 
-  const filterResult = buildAllConditions(table, params);
-  if ('error' in filterResult) {
-    return sanitizeError(filterResult.error, 400, options);
-  }
   const conditions = filterResult.conditions;
 
   // Row ownership: AND WHERE <column> = user[<userField>] for IDOR protection
@@ -3089,6 +3098,7 @@ function buildCondition(table: DrizzleTable, filter: Filter): any {
     case 'is':
       if (filter.value === 'null') condition = isNull(column);
       else if (filter.value === 'not.null') condition = isNotNull(column);
+      else return { __filterError: `Invalid value for 'is': expected null or not.null` };
       break;
     case 'in':
       condition = inArray(column, values ?? parseInList(filter.value));
@@ -3162,7 +3172,7 @@ function buildOrderBy(
 
 const RESERVED_QUERY_PARAMS = new Set(['limit', 'offset', 'order', 'select', 'deleted', 'or', 'and']);
 
-function parseFilters(params: URLSearchParams): Filter[] {
+function parseFilters(params: URLSearchParams): { filters: Filter[]; error?: string } {
   const filters: Filter[] = [];
 
   for (const [key, value] of params.entries()) {
@@ -3178,7 +3188,9 @@ function parseFilters(params: URLSearchParams): Filter[] {
 
     // PostgREST format: column=operator.value
     const dotIndex = remaining.indexOf('.');
-    if (dotIndex === -1) continue;
+    if (dotIndex === -1) {
+      return { filters, error: `Invalid filter for '${key.slice(0, 100)}': expected operator.value` };
+    }
 
     const operator = remaining.substring(0, dotIndex);
     const filterValue = remaining.substring(dotIndex + 1);
@@ -3193,7 +3205,7 @@ function parseFilters(params: URLSearchParams): Filter[] {
     });
   }
 
-  return filters;
+  return { filters };
 }
 
 /** A group part reading `column.[not.]cs.` so far: a `{` here opens an array value. */
@@ -3238,16 +3250,22 @@ function splitLogicalGroup(content: string): string[] {
  * Parse a logical group value into individual filters.
  * Input: "(status.eq.draft,status.eq.pending)" → [{column:'status', operator:'eq', value:'draft'}, ...]
  */
-function parseLogicalGroup(value: string): Filter[] {
+function parseLogicalGroup(value: string): { filters: Filter[]; error?: string } {
   let content = value;
   if (content.startsWith('(') && content.endsWith(')')) {
     content = content.slice(1, -1);
   }
 
   const filters: Filter[] = [];
+  if (content === '') return { filters };
+  let error: string | undefined;
+  const memberError = 'Invalid filter group: every member must be column.operator.value';
   for (const part of splitLogicalGroup(content)) {
     const dotIndex = part.indexOf('.');
-    if (dotIndex === -1) continue;
+    if (dotIndex === -1) {
+      error = memberError;
+      continue;
+    }
 
     const column = part.substring(0, dotIndex);
     const rest = part.substring(dotIndex + 1);
@@ -3260,7 +3278,10 @@ function parseLogicalGroup(value: string): Filter[] {
     }
 
     const opDot = remaining.indexOf('.');
-    if (opDot === -1) continue;
+    if (opDot === -1) {
+      error = memberError;
+      continue;
+    }
 
     const operator = remaining.substring(0, opDot);
     const filterValue = remaining.substring(opDot + 1);
@@ -3273,7 +3294,7 @@ function parseLogicalGroup(value: string): Filter[] {
       ...(jsonPath ? { jsonPath } : {}),
     });
   }
-  return filters;
+  return error ? { filters, error } : { filters };
 }
 
 function isFilterError(x: unknown): x is { __filterError: string } {
@@ -3286,36 +3307,27 @@ function isFilterError(x: unknown): x is { __filterError: string } {
  * Returns { conditions } on success, { error } on validation failure.
  */
 function buildAllConditions(table: DrizzleTable, params: URLSearchParams): { conditions: any[] } | { error: string } {
-  const filters = parseFilters(params);
-  const rawResults = filters.map(f => buildCondition(table, f));
+  const parsed = parseFilters(params);
+  if (parsed.error) return { error: parsed.error };
+  const rawResults = parsed.filters.map(f => buildCondition(table, f));
   for (const r of rawResults) {
     if (isFilterError(r)) return { error: r.__filterError };
   }
   const conditions = rawResults.filter(Boolean);
 
-  const orParam = params.get('or');
-  if (orParam) {
-    const orFilters = parseLogicalGroup(orParam);
-    const orRawResults = orFilters.map(f => buildCondition(table, f));
-    for (const r of orRawResults) {
-      if (isFilterError(r)) return { error: r.__filterError };
-    }
-    const orConditions = orRawResults.filter(Boolean);
-    if (orConditions.length > 0) {
-      conditions.push(or(...orConditions));
-    }
-  }
-
-  const andParam = params.get('and');
-  if (andParam) {
-    const andFilters = parseLogicalGroup(andParam);
-    const andRawResults = andFilters.map(f => buildCondition(table, f));
-    for (const r of andRawResults) {
-      if (isFilterError(r)) return { error: r.__filterError };
-    }
-    const andConditions = andRawResults.filter(Boolean);
-    if (andConditions.length > 0) {
-      conditions.push(and(...andConditions));
+  // getAll: the client appends, so `.or(a).or(b)` sends the key twice; dropping one widens the request.
+  for (const [key, combine] of [['or', or], ['and', and]] as const) {
+    for (const value of params.getAll(key)) {
+      const group = parseLogicalGroup(value);
+      if (group.error) return { error: group.error };
+      const groupRawResults = group.filters.map(f => buildCondition(table, f));
+      for (const r of groupRawResults) {
+        if (isFilterError(r)) return { error: r.__filterError };
+      }
+      const groupConditions = groupRawResults.filter(Boolean);
+      if (groupConditions.length > 0) {
+        conditions.push(combine(...groupConditions));
+      }
     }
   }
 
@@ -3324,9 +3336,8 @@ function buildAllConditions(table: DrizzleTable, params: URLSearchParams): { con
 
 /**
  * True when the request's own filters build no SQL condition, so the write would run
- * with no WHERE. A param that parses but builds nothing (`or=`, `or=()`, `and=junk`,
- * `id=is.x`) is not a filter. Only user filters count: the soft-delete and ownership
- * clauses the handler adds are not part of this test. A filter error is left to the
+ * with no WHERE. An empty group (`or=`, `or=()`) is not a filter. Only user filters
+ * count: the soft-delete and ownership clauses the handler adds are not part of this test. A filter error is left to the
  * caller's own buildAllConditions, which reports it.
  */
 function buildsNoFilter(table: DrizzleTable, params: URLSearchParams): boolean {