@stacksjs/orm 0.70.293 → 0.70.296

package/dist/auto-crud.d.ts

@@ -137,14 +137,53 @@ declare function safeJSONOrEmpty(_s: string): unknown;
  * read path) now gets its casts instead of leaking raw SQLite `"1"`s.
  */
 export declare function applyCasts(record: Record<string, any> | null | undefined, casts: Record<string, string | { get: (v: unknown) => unknown, set: (v: unknown) => unknown }> | null | undefined, direction: 'get' | 'set'): any;
+export declare function validateWriteBody(data: Record<string, any>, model: any, hook: 'creating' | 'updating'): WriteValidationResult;
+/**
+ * A route path with every parameter name flattened to `{}`.
+ *
+ * The "user routes win" guard compared paths literally, so an app's own
+ * `/api/sites/{siteId}` did not suppress the ORM's `/api/sites/{id}` — the two
+ * strings differ, so BOTH were registered and the ORM copy carried none of the
+ * app's authorization. The app had declared the endpoint and still got a second,
+ * unguarded one it never wrote (stacksjs/stacks#2224).
+ *
+ * The parameter's NAME is the app's business. The shape is what decides whether
+ * this URL is already claimed.
+ */
+export declare function routeShape(path: string): string;
 /**
  * Resolve middleware lists for a model's `useApi` trait value (which may be
  * `true` or `{ uri, routes, middleware }`).
  *
- * Secure-by-default: mutating routes (store/update/destroy) get `auth`
- * unless the model explicitly declares `useApi.middleware` — an explicit
- * `middleware: []` is a deliberate opt-out and is honored (with a startup
- * warning at the call site). Read routes stay public unless declared.
+ * Secure-by-default on BOTH sides: with no declared `useApi.middleware`, read
+ * and mutating routes alike get `auth`.
+ *
+ * #1949 gave the mutating routes that default and deliberately left reads
+ * public, reasoning that catalog tables (products, posts) want anonymous
+ * browsing. The cost of that default landed on models that are not catalogs: a
+ * model opting into the trait without declaring middleware published
+ * `GET /api/{uri}` and `GET /api/{uri}/{id}` to anyone. In one real app that
+ * was `GET /api/users` returning the full customer list — only `password` was
+ * `hidden`, so names and emails came back — and the app's own security tests
+ * could not see it, because the route was never declared in its route files
+ * (stacksjs/stacks#2224).
+ *
+ * A wrong "public" default is a data breach; a wrong "private" default is a 401
+ * on the first request in development. Only one of those is recoverable, so the
+ * default is now `auth` and a public read is something an app asks for.
+ *
+ * Three declaration shapes, so asking is always possible:
+ *
+ *   `middleware: ['auth']`              both sides get the list (unchanged)
+ *   `middleware: []`                    both sides public — deliberate opt-out,
+ *                                       warned about at the call site
+ *   `middleware: { read, write }`       per-side lists
+ *
+ * The split form exists because the secure default would otherwise make the
+ * most common real shape — public catalog reads, authenticated writes —
+ * inexpressible: a flat `middleware: []` is the only way to open reads, and it
+ * opens writes at the same time. That is a worse trade than the bug being fixed,
+ * so `{ read: [], write: ['auth'] }` says it exactly.
  */
 export declare function resolveApiMiddleware(useApi: unknown): { read: string[], write: string[], declared: boolean };
 /**
@@ -268,3 +307,22 @@ export declare interface IndexPaginator {
   first_page_url?: string
   last_page_url?: string
 }
+/**
+ * Run each declared `validation.rule` against a write payload.
+ *
+ * Returns `{ valid: true }` or `{ valid: false, errors }`. Per-attribute custom
+ * messages from `validation.message` override the rule's default text.
+ *
+ * Fields the caller never sent are skipped on the `updating` hook, so a partial
+ * update does not trip a `required` rule on a sibling field it never touched.
+ *
+ * Lives here rather than in `../routes.ts` so BOTH write paths can reach it.
+ * It used to be a local function in that module, which meant the declared rules
+ * ran on the generated REST routes and nowhere else: `Model.create()`,
+ * `.update()` and `.save()` went straight to the driver, and an over-length
+ * value first got noticed by Postgres as a 22001, surfacing as a 500 on
+ * whichever endpoint performed the write (stacksjs/stacks#2233). Importing it
+ * from `routes.ts` was not an option — that module registers routes on import.
+ */
+export type WriteValidationResult = | { valid: true }
+  | { valid: false, errors: Record<string, string[]> }

package/dist/define-model.d.ts

@@ -22,6 +22,17 @@ export type { ModelDefinition, InferRelationNames, ModelAttributes, InferModelAt
  * ```
  */
 export declare function withoutEvents<T>(fn: () => T | Promise<T>): Promise<T>;
+/**
+ * Run a callback with model validation suppressed for its entire duration.
+ *
+ * @example
+ * ```ts
+ * await User.withoutValidation(async () => {
+ *   for (const row of legacyRows) await User.create(row) // rules do not run
+ * })
+ * ```
+ */
+export declare function withoutValidation<T>(fn: () => T | Promise<T>): Promise<T>;
 export declare function defineModel<const TDef extends ModelDefinition>(definition: TDef): StacksModelStatic<TDef>;
 /**
  * Normalize a ModelInstance (or array of them, or already-plain row) into
@@ -49,7 +60,13 @@ declare interface StacksModelDefinition extends Omit<BQBModelDefinition, 'attrib
   table: string
   primaryKey?: string
   autoIncrement?: boolean
-  traits?: NonNullable<BQBModelDefinition['traits']> & Record<string, unknown>
+  traits?: Omit<NonNullable<BQBModelDefinition['traits']>, 'useApi'> & {
+    useApi?: boolean | {
+      readonly uri?: string
+      readonly routes?: readonly string[]
+      readonly middleware?: any
+    }
+  } & Record<string, unknown>
   indexes?: Array<{ name: string, columns: string[], unique?: boolean, where?: string }>
   casts?: Record<string, CastType | CasterInterface>
   attributes: {
@@ -146,6 +163,23 @@ export type StacksModelStatic<TDef extends ModelDefinition> = OrmModelStatic<TDe
   forceCreate: (data: Record<string, unknown>) => ReturnType<OrmModelStatic<TDef>['create']>
   delete: (id: number | string) => Promise<boolean>
   withoutEvents: <T>(fn: () => T | Promise<T>) => Promise<T>
+  /** Run `fn` with declared `validation.rule`s suppressed (bulk imports, backfills). */
+  withoutValidation: <T>(fn: () => T | Promise<T>) => Promise<T>
+}
+/**
+ * Thrown when a direct write fails a declared `validation.rule`.
+ *
+ * Carries `status = 422` and a per-field `errors` map, matching the shape the
+ * generated REST routes already return, so a handler that catches this can
+ * respond with the same body it would have produced through auto-CRUD. It is
+ * duck-typed by `mapWriteError`, which preserves any integer `status` in
+ * 400-599 — so an over-length value now surfaces as a 422 instead of the
+ * driver's raw 22001 becoming a 500 (stacksjs/stacks#2233).
+ */
+export declare class ModelValidationError extends Error {
+  readonly status: number;
+  readonly errors: Record<string, string[]>;
+  constructor(modelName: string, errors: Record<string, string[]>);
 }
 /**
  * Thrown by `Model.findOrFail(id)` (and other strict lookups) when no row matches.