@edium/halifax 2.2.3 → 2.3.0

package/CHANGELOG.md

@@ -3,6 +3,139 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0]
+
+### Security
+
+- **`PrismaAdapter.upsertOne` cross-tenant write vulnerability eliminated** — the previous scoped
+  upsert path performed `findFirst({ where: { id } })` without a tenant filter, then called
+  `delegate.upsert({ where: { id } })` also without a tenant filter. The application-level
+  ownership check between the two statements created a TOCTOU window: if another tenant's record
+  appeared at that ID between the check and the upsert, Prisma's `upsert` would fire its `update`
+  branch and write into that other tenant's row. The scoped path no longer uses `delegate.upsert`.
+  It now uses a scoped `findFirst(scopedWhere)` to detect existence, `updateMany(scopedWhere)` for
+  the update branch (atomic, same fix applied to `updateOne`), and `create(stampTenant)` for the
+  create branch. The `delegate.upsert` call is retained only for the unscoped path.
+
+- **`PrismaAdapter.updateOne` and `deleteOne` unsafe fallbacks removed** — when `updateMany`
+  (for `updateOne`) or `deleteMany` (for `deleteOne`) were unavailable on the delegate, the code
+  fell back to a two-step scoped-check + unscoped-write sequence. Both halves now throw
+  `ServerError` immediately rather than proceeding with an unsafe path. Standard Prisma delegates
+  always expose both methods, so this only affects non-standard or mock delegates.
+
+- **`requiredPermissions` now uses OR semantics consistently** — all three auth strategies
+  (`JwtClaimsAuthStrategy`, `PassportJwtStrategy`, `PassportSessionStrategy`) previously used
+  `.every()` (ALL permissions required), while the fallback path in `handlerUtils.ts` correctly
+  used `.some()` (ANY single permission grants access). The strategies were wrong. All four paths
+  now delegate to a shared `checkRequiredPermissions()` utility that applies `.some()` semantics:
+  a caller who holds *any one* of the listed permissions is authorized. This matches the documented
+  behavior of `readRoles`/`writeRoles` at the field level and is a consistent read of "required
+  permissions" as an OR list. **If you relied on the undocumented ALL-must-match behavior,
+  tighten your permission model accordingly.**
+
+- **TOCTOU race in `PrismaAdapter.updateOne` under tenant scope eliminated** — the previous
+  scoped-update path did a `findFirst` ownership check and then a separate `update` call. Between
+  the two statements, a concurrent request could transfer the record to a different tenant,
+  allowing the update to land on a record the caller no longer owns. The fix uses
+  `updateMany({ where: scopedWhere })` as the primary path when the Prisma delegate supports it —
+  the tenant field is enforced atomically in a single SQL statement. A safe `findFirst`-then-update
+  fallback remains only for delegates that lack `updateMany`.
+
+### Performance
+
+- **O(n²) → O(n) field validation** — `validateSelectableFields` and `validateSortableFields`
+  previously called `.find()` inside a `.filter()`, giving O(n²) complexity per request. Both now
+  pre-build a `Map` from field names to definitions and do O(1) lookups in the filter pass.
+
+- **`makeReadableFieldFilter` factory for bulk-response field stripping** — `filterReadableFields`
+  previously rebuilt the `fieldMap` `Map` and `userRoles` `Set` for every record in a batch. A
+  new exported factory `makeReadableFieldFilter(resource, auth)` builds both structures once and
+  returns a reusable `(record) => record` function. The `readMany`, `query`, and `updateMany`
+  handlers now call the factory once before `.map()` and pass the compiled function directly,
+  eliminating O(n) redundant Map constructions for responses with up to 5000 records.
+
+- **`parseGetOneOptions` for lean GET /:id parsing** — `readOne` previously called
+  `parseListOptions`, which parses and validates `?fields=`, `?include=`, `?limit=`, `?offset=`,
+  `?order=`, and all filter fields — all of which are irrelevant to a single-record GET. A new
+  exported `parseGetOneOptions(query, resource)` in `queryString.ts` only parses and validates
+  `?fields=` and `?include=`, removing the wasted work and the silent discard of inapplicable
+  parameters on that route.
+
+### Fixed
+
+- **OpenAPI `distinct` type corrected** — the query-builder endpoint's `distinct` parameter was
+  documented as `{ type: 'boolean' }` in the generated spec. The actual type is `string[]` (an
+  array of field names to de-duplicate on). The spec now documents it as
+  `{ type: 'array', items: { type: 'string' } }` with an accurate description.
+
+- **`normalizeEnvelope` and `mergeRelationDefinitions` extracted to `fields.ts`** — both
+  utilities existed in identical form in `crudRouter.ts` and `specGenerator.ts`. They are now
+  exported from `src/core/fields.ts` alongside `mergeFieldDefinitions`, and both files import
+  from there. Behavior is unchanged.
+
+- **`checkRequiredPermissions` extracted to `src/auth/strategies/types.ts`** — the permission
+  check logic was duplicated (with incompatible `.every()` vs `.some()` semantics) across all
+  three strategy files and `handlerUtils.ts`. It is now a single exported function and all four
+  call sites use it. See the Security section above for the semantics fix.
+
+- **`DrizzleAdapter` reports `supportsIncludes: false`** — the adapter has always silently ignored
+  `?include=` requests because Drizzle has no built-in relation eager-loading surface compatible
+  with Halifax's interface. The `capabilities` property now explicitly sets `supportsIncludes:
+  false`, which causes the router to reject `?include=` with `422 Unprocessable Entity` instead
+  of silently returning records with no related data.
+
+- **`InMemoryCacheStore` memory growth bounded** — the store previously only evicted expired
+  entries lazily on reads, so a write-heavy workload with few reads could accumulate stale entries
+  without bound. The `set()` method now runs a full expired-entry sweep every 200 writes
+  (configurable via the `sweepEvery` constructor parameter). No external timers or additional
+  dependencies.
+
+- **`CacheStore.increment` — atomic cache version bumps** — `createCachingRepository` previously
+  incremented the version key with a non-atomic `GET` + `SET`, creating a race window under
+  concurrent writes on Redis. The `CacheStore` interface gains an optional `increment(key):
+  Promise<number> | number` method. `RedisCacheStore` implements it with Redis `INCR` (atomic
+  by design). `InMemoryCacheStore` implements it synchronously (race-free in Node.js's
+  single-threaded event loop). `createCachingRepository` uses `store.increment` when available
+  and falls back to the non-atomic path only for custom stores that do not implement it.
+
+- **`DrizzleAdapter.upsertOne` non-atomicity documented** — the method does a `getOne` check
+  followed by a `createOne` or `updateOne`, which is non-atomic under concurrent load. A JSDoc
+  comment now explains the race condition and recommends implementing a custom repository with a
+  database-native `INSERT … ON CONFLICT` clause when true atomicity is required.
+
+- **`PrismaAdapter` import order** — all imports were moved above function definitions and
+  consolidated into a single, alphabetized block. No behavior change.
+
+- **`parseId` dead code removed** — after `validateId(raw)` narrows `raw` to `string`, the
+  previous `typeof raw === 'string' ? parseInt(raw, 10) : raw` branch was unreachable. The
+  function now calls `parseInt(raw, 10)` directly, and the redundant type guard before the
+  UUID/ObjectId check is also removed.
+
+- **`LIKE` interior-wildcard limitation documented** — `likeToPrisma` in
+  `src/adapters/orm/prisma/astToPrisma.ts` now carries a JSDoc comment explaining that patterns
+  with an interior wildcard (e.g. `'foo%bar'`) cannot be expressed via Prisma's string operators
+  and fall through to an exact `equals` match, not a wildcard match. Use `CONTAINS`, `STARTS
+  WITH`, or `ENDS WITH` comparisons instead of `LIKE` when possible.
+
+### Documentation
+
+- **`QueryBuilder` mutability warning** — the class JSDoc now clearly states that all chaining
+  methods mutate `this` and return the same instance. A before/after code example demonstrates
+  the correct pattern (create a new `QueryBuilder` per branch) and the incorrect pattern (sharing
+  one instance and calling `.limit()` twice).
+
+- **`andGroup` / `orGroup` API design explained** — both methods require a `field`/`comparison`/
+  `value1` parent condition because the Halifax query AST attaches children to a parent filter
+  node. The JSDoc now explains this constraint, describes what the resulting predicate looks like
+  (`cond AND (children)` vs `cond OR (children)`), and suggests a workaround for expressing a
+  pure parenthesized group with no meaningful parent condition.
+
+- **`specGenerator` raw-vs-normalized resource note** — a comment in `generateOpenApiSpec`
+  explains that the function operates on raw `ResourceDefinition` objects (not the normalized
+  forms produced by `crudRouter.normalizeResource`) and therefore re-derives merged fields and
+  relations independently. This is intentional — the spec generator is also usable as a
+  standalone function outside the router.
+
 ## [2.2.3]
 
 ### Added

package/README_AUTH.md

@@ -37,7 +37,7 @@ const authStrategy = new ApiKeyAuthStrategy(process.env.API_KEY ?? '')
 const authStrategy = new ApiKeyAuthStrategy(process.env.API_KEY ?? '', 'x-token')
 ```
 
-Wrong or missing key → 403.
+Missing header → 401 Unauthorized. Wrong key → 403 Forbidden.
 
 ### `JwtClaimsAuthStrategy`
 
@@ -194,7 +194,7 @@ class RoleBasedStrategy implements AuthStrategy {
 
   authorize({ auth, action, resource, requiredPermissions }) {
     if (auth.roles.includes('admin')) return true
-    return requiredPermissions.every((p) => auth.permissions.includes(p) || auth.roles.includes(p))
+    return requiredPermissions.some((p) => auth.permissions.includes(p) || auth.roles.includes(p))
   }
 }
 ```

package/README_AUTOCRUD.md

@@ -100,9 +100,9 @@ Each entry in `fields` accepts four optional boolean flags. All default to `true
 
 | Flag         | Effect when `false`                                                   |
 | ------------ | --------------------------------------------------------------------- |
-| `filterable` | Rejects the field as a query-string filter (`?fieldName=value`) → 400 |
-| `sortable`   | Rejects the field in `?order=` and query-builder `orderBy` → 400      |
-| `selectable` | Rejects the field in `?fields=` and query-builder `fields` → 400      |
+| `filterable` | Rejects the field as a query-string filter (`?fieldName=value`) → 422 |
+| `sortable`   | Rejects the field in `?order=` and query-builder `orderBy` → 422      |
+| `selectable` | Rejects the field in `?fields=` and query-builder `fields` → 422      |
 | `writable`   | Silently strips the field from POST / PATCH / PUT request bodies      |
 
 Example — `role` is fully locked down; `createdAt` can be read and sorted but never written or filtered:
@@ -295,7 +295,7 @@ The `?where` / query-builder `children` filter lets callers nest conditions. To
 }
 ```
 
-Requests that exceed the limit receive **400 VALIDATION_ERROR**.
+Requests that exceed the limit receive **422 UNPROCESSABLE_ENTITY**.
 
 ## Error Response Shape
 
@@ -320,6 +320,7 @@ All errors follow the same envelope — an `errors` array where each item has a
 | 404    | `NOT_FOUND`              | `NotFoundError`             | Record not found                                                                                     |
 | 405    | `METHOD_NOT_ALLOWED`     | `MethodNotAllowedError`     | HTTP method not enabled for this resource                                                            |
 | 406    | `NOT_ACCEPTABLE`         | `NotAcceptableError`        | `Accept` header excludes `application/json`                                                          |
+| 409    | `CONFLICT`               | `ConflictError`             | Write rejected due to a unique constraint violation                                                  |
 | 415    | `UNSUPPORTED_MEDIA_TYPE` | `UnsupportedMediaTypeError` | Request body is not `application/json`                                                               |
 | 422    | `UNPROCESSABLE_ENTITY`   | `UnprocessableEntityError`  | Semantic validation failure — unknown field, invalid filter, sort/select restriction, depth exceeded |
 | 500    | `INTERNAL_ERROR`         | `ServerError`               | Repository misconfigured or unhandled internal error                                                 |

package/README_CACHE.md

@@ -149,6 +149,12 @@ class MyCacheStore implements CacheStore {
   async delete(key: string): Promise<void> {
     /* … */
   }
+  // Optional — implement for atomic version bumps under concurrent writes.
+  // When omitted, Halifax falls back to a non-atomic GET + SET (safe for
+  // single-process stores like InMemoryCacheStore, but not for Redis).
+  async increment(key: string): Promise<number> {
+    /* … return new integer value */
+  }
 }
 ```
 

package/README_CLASSES.md

@@ -28,13 +28,14 @@ Import: `@edium/halifax`
 Reads a request header and compares it against a static shared secret.
 
 ```ts
-new ApiKeyAuthStrategy(expectedApiKey: string, headerName?: string)
+new ApiKeyAuthStrategy(expectedApiKey: string, headerName?: string, roles?: string[])
 ```
 
-| Parameter        | Default       | Description                         |
-| ---------------- | ------------- | ----------------------------------- |
-| `expectedApiKey` | required      | The secret key callers must supply. |
-| `headerName`     | `'x-api-key'` | Header to read the key from.        |
+| Parameter        | Default       | Description                                                              |
+| ---------------- | ------------- | ------------------------------------------------------------------------ |
+| `expectedApiKey` | required      | The secret key callers must supply.                                      |
+| `headerName`     | `'x-api-key'` | Header to read the key from.                                             |
+| `roles`          | `[]`          | Role strings attached to `auth.roles` on every successfully authed call. |
 
 - Missing header → 401 Unauthorized
 - Wrong key → 403 Forbidden
@@ -208,7 +209,12 @@ new PrismaAdapter<TRecord, TCreate, TUpdate>(options: PrismaAdapterOptions)
 
 See `PrismaAdapterOptions` in [README_INTERFACES.md](./README_INTERFACES.md).
 
-**Static method:** `PrismaAdapter` has no static methods. For auto-generating resources from all Prisma models, use `createPrismaResources` (a standalone function).
+**Static methods:**
+
+- `PrismaAdapter.fieldsFromModel(model: ModelSchema): FieldDefinition[]` — derives a Halifax field schema from a Prisma DMMF model. Used internally by the constructor when `options.model` is provided; also callable standalone when you want to inspect or override fields before constructing the adapter.
+- `PrismaAdapter.relationsFromModel(model: ModelSchema): RelationDefinition[]` — derives relation definitions from object-kind fields in the model.
+
+For auto-generating resources from all Prisma models at once, use `createPrismaResources` (a standalone function).
 
 **Capabilities reported:**
 
@@ -314,6 +320,7 @@ Base class for all Halifax HTTP errors. Not instantiated directly.
 | `NotFoundError`             | 404    | Record with the given ID does not exist. Throw from a custom `Repository.getOne`.                              |
 | `MethodNotAllowedError`     | 405    | HTTP method not enabled for this resource. Used internally by Halifax.                                         |
 | `NotAcceptableError`        | 406    | Client `Accept` header excludes `application/json`. Used internally by Halifax.                                |
+| `ConflictError`             | 409    | Write rejected due to a unique constraint violation. Thrown by `PrismaAdapter` and `DrizzleAdapter` automatically; throw it from a custom repository for the same semantics. |
 | `UnsupportedMediaTypeError` | 415    | Body-carrying request with non-JSON `Content-Type`. Used internally by Halifax.                                |
 | `UnprocessableEntityError`  | 422    | Unknown fields in body, missing required filter, empty update payload.                                         |
 | `NotImplementedError`       | 501    | Repository does not support this operation (e.g. `upsertOne` not implemented).                                 |

package/README_INTERFACES.md

@@ -24,7 +24,7 @@ Full definition of a Halifax resource. Pass an array of these to `createExpressC
 | `requiredPermissions` | `Partial<Record<CrudAction, string[]>>` | no       | Permission strings per action checked by the auth strategy.                                                                                                                                                                                |
 | `defaultLimit`        | `number`                                | no       | Default page size when caller omits `?limit=`. Defaults to `DEFAULT_PAGE_LIMIT` (5000). `0` disables the default bound.                                                                                                                    |
 | `maxLimit`            | `number`                                | no       | Hard cap on page size. Defaults to `MAX_PAGE_LIMIT` (5000). `0` removes the cap.                                                                                                                                                           |
-| `maxFilterDepth`      | `number`                                | no       | Maximum nesting depth for `where` clause children. Defaults to 3.                                                                                                                                                                          |
+| `maxFilterDepth`      | `number`                                | no       | Maximum nesting depth for `where` clause children. Defaults to 4.                                                                                                                                                                          |
 | `cache`               | `ResourceCacheConfig \| false`          | no       | Per-resource cache TTL. `false` disables caching even when an API-wide default is set.                                                                                                                                                     |
 | `envelope`            | `string \| null`                        | no       | Wraps every success response body under this key (e.g. `'data'`). Overrides the API-wide `envelope` option.                                                                                                                                |
 
@@ -404,11 +404,12 @@ Import: `@edium/halifax`
 
 Contract for pluggable cache backends. Implement this to use Redis, Memcached, or any other store.
 
-| Method   | Signature                                            | Description                                                      |
-| -------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| `get`    | `(key: string) => Promise<unknown> \| unknown`       | Read a cached value. Returns `undefined` when absent or expired. |
-| `set`    | `(key, value, ttlSeconds?) => Promise<void> \| void` | Write a value. `ttlSeconds` `0` or omitted means no expiry.      |
-| `delete` | `(key: string) => Promise<void> \| void`             | Delete a cached value.                                           |
+| Method      | Signature                                             | Description                                                                                                          |
+| ----------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `get`       | `(key: string) => Promise<unknown> \| unknown`        | Read a cached value. Returns `undefined` when absent or expired.                                                     |
+| `set`       | `(key, value, ttlSeconds?) => Promise<void> \| void`  | Write a value. `ttlSeconds` `0` or omitted means no expiry.                                                          |
+| `delete`    | `(key: string) => Promise<void> \| void`              | Delete a cached value.                                                                                               |
+| `increment` | `(key: string) => Promise<number> \| number` *(opt.)* | Atomically increment an integer key and return the new value. Implement this for safe concurrent version bumps (e.g. Redis `INCR`). When omitted, Halifax falls back to a non-atomic `get`+`set`. |
 
 ---
 
@@ -433,11 +434,12 @@ Import: `@edium/halifax`
 
 Minimal structural type for a Redis client. `RedisCacheStore` uses this interface so no specific Redis package is a hard dependency. `redis` v4's `get`, `set`, and `del` satisfy it directly.
 
-| Method | Signature                                    | Description                                    |
-| ------ | -------------------------------------------- | ---------------------------------------------- |
-| `get`  | `(key: string) => Promise<string \| null>`   | Read a key.                                    |
-| `set`  | `(key, value, options?) => Promise<unknown>` | Write a key. `options.EX` sets TTL in seconds. |
-| `del`  | `(key: string) => Promise<unknown>`          | Delete a key.                                  |
+| Method | Signature                                          | Description                                                                         |
+| ------ | -------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `get`  | `(key: string) => Promise<string \| null>`         | Read a key.                                                                         |
+| `set`  | `(key, value, options?) => Promise<unknown>`       | Write a key. `options.EX` sets TTL in seconds.                                      |
+| `del`  | `(key: string) => Promise<unknown>`                | Delete a key.                                                                       |
+| `incr` | `(key: string) => Promise<number>` *(optional)*    | Atomically increment a key. Used by `RedisCacheStore.increment` for version bumps when the client exposes this method. |
 
 ---
 

package/README_OPENAPI.md

@@ -284,7 +284,7 @@ The query builder endpoint accepts a `QueryOptions` body for full-featured filte
       ]
     }
   ],
-  "orderBy": [{ "field": "createdAt", "direction": "desc" }],
+  "orderBy": [{ "field": "createdAt", "order": "DESC" }],
   "limit": 20,
   "offset": 0,
   "fields": ["id", "title", "createdAt"],

package/README_REPO_ADAPTERS.md

@@ -186,6 +186,8 @@ A resource always needs a field schema — it's the allow-list that powers filte
 
 Halifax's `peerDependencies` allow `@prisma/client >=6.0.0`, so it runs on **Prisma 6 or Prisma 7**. `PrismaAdapter` is database- and version-agnostic: it imports nothing from `@prisma/client` and only calls standard model-delegate methods (`findMany`, `findUnique`, `findFirst`, `create`, `createMany`, `update`, `updateMany`, `delete`, `deleteMany`, `upsert`, `count`) that behave identically across both majors. **You** construct the client and pass `prisma.<model>` as the `delegate` — Halifax never touches the parts that differ between the versions.
 
+**Tenant-scoped paths require `updateMany` and `deleteMany` on the delegate.** When multi-tenant isolation is active, `updateOne` uses `updateMany(scopedWhere)` for an atomic ownership-enforced write, and `deleteOne` uses `deleteMany(scopedWhere)` for the same reason. If the delegate does not expose these methods, both operations throw `ServerError`. Standard Prisma delegates always expose them; this only affects non-standard or mock delegates.
+
 > **Caveats.** Halifax's CI matrix exercises **Prisma 7 only** — Prisma 6 is supported on the strength of that stable delegate surface, not a dedicated CI leg, so treat it as best-effort and pin/test your own app against it. Prisma 7 is the recommended path; the main reason to stay on (or drop to) Prisma 6 today is **MongoDB**, which Prisma 7 does not yet support. When Prisma 7 restores MongoDB, prefer upgrading over remaining on 6.
 
 What you implement differently on Prisma 6 (everything below is your project's Prisma setup — no Halifax code changes):
@@ -306,6 +308,14 @@ new DrizzleAdapter(db, table, config?, scope?)
 | `config.idField` | `string` (optional)   | Primary key field name. Defaults to auto-detecting the first column marked `.primaryKey()`. Set explicitly for composite PKs or non-standard names. |
 | `scope`          | `TenantScope \| null` | Tenant scope. Set by `withScope()` internally — do not pass directly.                                                                               |
 
+### Relation includes
+
+`DrizzleAdapter` does **not** support `?include=` (relation eager-loading). It reports
+`capabilities.supportsIncludes: false`, so the router rejects `?include=` requests with
+`422 Unprocessable Entity` rather than silently returning records with no related data.
+If you need related records, fetch them with a second query or use `PrismaAdapter` for
+the resource that requires includes.
+
 ### Multi-tenancy
 
 `DrizzleAdapter` supports per-resource tenant scoping via `withScope()` exactly like `PrismaAdapter`. See [README_MULTITENANCY.md](./README_MULTITENANCY.md) for how to configure it on the resource.

package/dist/adapters/orm/drizzle/DrizzleAdapter.d.ts

@@ -88,6 +88,11 @@ export declare class DrizzleAdapter<TRecord = Record<string, unknown>, TCreate =
     private readonly table;
     readonly fields: FieldDefinition[];
     readonly idField: string;
+    /** Drizzle uses `.returning()` for inserts/updates, so it always returns created records. */
+    readonly capabilities: {
+        supportsIncludes: boolean;
+        supportsCreateManyReturn: boolean;
+    };
     private readonly columns;
     private readonly scope;
     constructor(db: AnyDrizzleDB, table: Table, config?: DrizzleAdapterConfig, scope?: TenantScope | null);

package/dist/adapters/orm/drizzle/DrizzleAdapter.js

@@ -68,6 +68,8 @@ export class DrizzleAdapter {
     table;
     fields;
     idField;
+    /** Drizzle uses `.returning()` for inserts/updates, so it always returns created records. */
+    capabilities = { supportsIncludes: false, supportsCreateManyReturn: true };
     columns;
     scope;
     constructor(db, table, config = {}, scope = null) {
@@ -237,6 +239,12 @@ export class DrizzleAdapter {
         }
     }
     async upsertOne(id, data) {
+        // Non-atomic: the getOne check and the subsequent write are separate statements.
+        // Under concurrent load, two simultaneous upserts for the same absent ID can both
+        // pass the getOne check and then race on createOne — the loser gets a ConflictError.
+        // Drizzle has no single portable INSERT…ON CONFLICT across all databases, so this
+        // is the safest cross-provider implementation. Callers that need true atomicity
+        // should implement a custom repository using a database-specific ON CONFLICT clause.
         const existing = await this.getOne(id);
         if (existing) {
             const updated = await this.updateOne(id, data);
@@ -285,6 +293,6 @@ export class DrizzleAdapter {
         return { count: total, results: rows };
     }
     withScope(scope) {
-        return new DrizzleAdapter(this.db, this.table, { idField: this.idField }, scope ?? null);
+        return new DrizzleAdapter(this.db, this.table, { idField: this.idField }, scope);
     }
 }

package/dist/adapters/orm/prisma/PrismaAdapter.d.ts

@@ -1,6 +1,5 @@
 import type { IQueryOptions } from '@edium/halifax-types';
-import type { Repository, RepositoryCapabilities, DeleteManyResult, ListOptions, ListResult, QueryResult, TenantScope, UpdateManyResult } from '../../../core/types.js';
-import type { FieldDefinition, RelationDefinition, ModelSchema } from '../../../core/types.js';
+import type { DeleteManyResult, FieldDefinition, ListOptions, ListResult, ModelSchema, QueryResult, RelationDefinition, Repository, RepositoryCapabilities, TenantScope, UpdateManyResult } from '../../../core/types.js';
 import type { PrismaAdapterOptions } from './types.js';
 /**
  * PrismaAdapter is a generic repository implementation that uses Prisma delegates to perform

package/dist/adapters/orm/prisma/PrismaAdapter.js

@@ -1,8 +1,9 @@
 import { ConflictError } from '../../../errors/ConflictError.js';
-import { NotImplementedError } from '../../../errors/NotImplementedError.js';
 import { NotFoundError } from '../../../errors/NotFoundError.js';
+import { NotImplementedError } from '../../../errors/NotImplementedError.js';
 import { ServerError } from '../../../errors/ServerError.js';
-import { astToPrismaWhere, astToPrismaOrderBy } from './astToPrisma.js';
+import { astToPrismaOrderBy, astToPrismaWhere } from './astToPrisma.js';
+import { toInclude, toOrderBy, toSelect } from './helpers.js';
 /** Returns true for Prisma's P2025 "record not found" error. */
 function isNotFoundError(error) {
     return (typeof error === 'object' &&
@@ -17,7 +18,19 @@ function isDuplicateError(error) {
         'code' in error &&
         error.code === 'P2002');
 }
-import { toSelect, toInclude, toOrderBy } from './helpers.js';
+/**
+ * Returns true for SQL Server's "IDENTITY_INSERT is set to OFF" error (code 544).
+ * MSSQL IDENTITY columns reject any explicit-value INSERT via the driver adapter rather
+ * than surfacing a P2002 duplicate — so this must be caught separately.
+ */
+function isIdentityInsertError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const cause = error.cause;
+    return (typeof cause === 'object' &&
+        cause !== null &&
+        cause.code === 544);
+}
 function prismaTypeToOpenApi(prismaType) {
     switch (prismaType) {
         case 'Int':
@@ -293,19 +306,24 @@ export class PrismaAdapter {
      * @throws ServerError if the Prisma delegate does not support the update method.
      */
     async updateOne(id, data) {
-        // When scoped, confirm the row belongs to the caller's tenant before touching it,
-        // and strip the tenant field from the payload so the row can't be moved tenants.
         if (this.scope) {
-            if (!this.delegate.findFirst) {
-                throw new ServerError('Prisma delegate does not support findFirst (required for tenant scoping).');
+            const scopedWhere = this.scopedWhere({ [this.idField]: id });
+            // Preferred path: delegate.updateMany lets us do a single atomic statement whose
+            // WHERE enforces the tenant boundary, eliminating the TOCTOU window.
+            if (this.delegate.updateMany && this.delegate.findFirst) {
+                const { count } = await this.delegate.updateMany({
+                    where: scopedWhere,
+                    data: this.stripTenant(data)
+                });
+                if (count === 0)
+                    return null;
+                return (await this.delegate.findFirst({ where: scopedWhere }));
             }
-            const owned = await this.delegate.findFirst({
-                where: this.scopedWhere({ [this.idField]: id }),
-                select: { [this.idField]: true }
-            });
-            if (!owned)
-                return null;
-            data = this.stripTenant(data);
+            // updateMany is unavailable — we cannot perform a single atomic scoped update.
+            // A two-step findFirst + unscoped update would introduce a TOCTOU window where a
+            // record could be transferred to another tenant between the check and the write.
+            // Refuse rather than risk a cross-tenant modification.
+            throw new ServerError('Prisma delegate does not support updateMany (required for safe tenant-scoped updateOne).');
         }
         try {
             return (await this.delegate.update({ where: { [this.idField]: id }, data }));
@@ -355,35 +373,95 @@ export class PrismaAdapter {
      * @throws ServerError if the Prisma delegate does not support the required methods for upserting records.
      */
     async upsertOne(id, data) {
-        if (!this.delegate.upsert) {
-            throw new NotImplementedError('Prisma delegate does not support upsert.');
-        }
-        // When scoped, an upsert keyed on a unique id could otherwise overwrite a row owned
-        // by another tenant. Reject that case (hidden as "not found"), stamp the tenant on
-        // create, and forbid reassigning the tenant on update.
+        // Scoped upsert: do NOT use delegate.upsert with a bare id where-clause — Prisma's upsert
+        // would execute its `update` branch against any matching record regardless of tenant, giving
+        // a cross-tenant write if a race places another tenant's row at that id. Instead we decompose
+        // into a scoped findFirst + a scoped updateMany (create on miss) so the tenant constraint is
+        // enforced at every statement.
         if (this.scope) {
             if (!this.delegate.findFirst) {
                 throw new ServerError('Prisma delegate does not support findFirst (required for tenant scoping).');
             }
+            const scopedWhere = this.scopedWhere({ [this.idField]: id });
             const existing = (await this.delegate.findFirst({
-                where: { [this.idField]: id }
+                where: scopedWhere
             }));
+            // Defense-in-depth: even though scopedWhere already filters by tenant, verify the
+            // returned record actually belongs to this tenant before treating it as owned.
             if (existing && existing[this.scope.field] !== this.scope.value) {
                 throw new NotFoundError();
             }
+            if (existing) {
+                // Record exists for this tenant — update it atomically via updateMany(scopedWhere)
+                // so the tenant constraint is enforced in the same SQL statement as the write.
+                if (this.delegate.updateMany) {
+                    const { count } = await this.delegate.updateMany({
+                        where: scopedWhere,
+                        data: this.stripTenant(data)
+                    });
+                    if (count === 0) {
+                        // Deleted in the tiny window between findFirst and updateMany — treat as a
+                        // fresh create so the caller gets a record back (consistent with upsert semantics).
+                        try {
+                            return (await this.delegate.create({
+                                data: this.stampTenant({ ...data, [this.idField]: id })
+                            }));
+                        }
+                        catch (error) {
+                            if (isDuplicateError(error))
+                                throw new ConflictError();
+                            if (isIdentityInsertError(error)) {
+                                const anyMatch = await this.delegate.findFirst({ where: { [this.idField]: id } });
+                                if (anyMatch)
+                                    throw new ConflictError();
+                                return (await this.delegate.create({ data: this.stampTenant(data) }));
+                            }
+                            throw error;
+                        }
+                    }
+                    return (await this.delegate.findFirst({ where: scopedWhere }));
+                }
+                // Fallback when updateMany is unavailable (non-standard delegate). The update is still
+                // scoped via the earlier findFirst; the TOCTOU window here is only closeable with a
+                // transaction, which we cannot guarantee across providers.
+                try {
+                    return (await this.delegate.update({
+                        where: { [this.idField]: id },
+                        data: this.stripTenant(data)
+                    }));
+                }
+                catch (error) {
+                    if (isNotFoundError(error))
+                        throw new NotFoundError();
+                    if (isDuplicateError(error))
+                        throw new ConflictError();
+                    throw error;
+                }
+            }
+            // Record does not exist for this tenant — create it with the tenant stamped.
             try {
-                return (await this.delegate.upsert({
-                    where: { [this.idField]: id },
-                    create: this.stampTenant(data),
-                    update: this.stripTenant(data)
+                return (await this.delegate.create({
+                    data: this.stampTenant({ ...data, [this.idField]: id })
                 }));
             }
             catch (error) {
                 if (isDuplicateError(error))
                     throw new ConflictError();
+                if (isIdentityInsertError(error)) {
+                    // MSSQL IDENTITY columns reject any explicit-ID insert. Probe to distinguish a
+                    // cross-tenant ID collision (another tenant owns this ID → ConflictError) from a
+                    // genuinely new row (let the DB assign the ID instead).
+                    const anyMatch = await this.delegate.findFirst({ where: { [this.idField]: id } });
+                    if (anyMatch)
+                        throw new ConflictError();
+                    return (await this.delegate.create({ data: this.stampTenant(data) }));
+                }
                 throw error;
             }
         }
+        if (!this.delegate.upsert) {
+            throw new NotImplementedError('Prisma delegate does not support upsert.');
+        }
         try {
             return (await this.delegate.upsert({
                 where: { [this.idField]: id },
@@ -416,15 +494,9 @@ export class PrismaAdapter {
                 });
                 return (result?.count ?? 0) > 0;
             }
-            if (!this.delegate.findFirst) {
-                throw new ServerError('Prisma delegate does not support deleteMany or findFirst (required for tenant scoping).');
-            }
-            const owned = await this.delegate.findFirst({
-                where: this.scopedWhere({ [this.idField]: id }),
-                select: { [this.idField]: true }
-            });
-            if (!owned)
-                return false;
+            // deleteMany is unavailable — we cannot do an atomic scoped delete. A two-step
+            // findFirst + unscoped delete would introduce a TOCTOU cross-tenant deletion risk.
+            throw new ServerError('Prisma delegate does not support deleteMany (required for safe tenant-scoped deleteOne).');
         }
         try {
             await this.delegate.delete({ where: { [this.idField]: id } });

package/dist/adapters/orm/prisma/astToPrisma.js

@@ -3,6 +3,12 @@ import { SqlComparison, SqlOperator, SqlOrder } from '@edium/halifax-types';
  * Splits a `LIKE` pattern into a Prisma string operator based on its `%` wildcards.
  * `%x%` → `contains`, `x%` → `startsWith`, `%x` → `endsWith`, and a wildcard-free value
  * collapses to `equals` (matching SQL `LIKE 'x'` semantics).
+ *
+ * **Known limitation:** interior wildcards (`'foo%bar'`) cannot be expressed with Prisma's
+ * string operators — they fall through to `equals`, which is an exact match, not a
+ * wildcard match. Prisma has no `matches`/`glob` operator without raw SQL. Use `CONTAINS`,
+ * `STARTS WITH`, or `ENDS WITH` comparisons instead of `LIKE` when possible.
+ *
  * @param value - The raw LIKE pattern.
  * @returns A Prisma string-filter object.
  */

package/dist/auth/strategies/JwtClaimsAuthStrategy.js

@@ -1,4 +1,5 @@
 import { AuthenticationError } from '../../errors/AuthenticationError.js';
+import { checkRequiredPermissions } from './types.js';
 /** Authenticates via a Bearer JWT and authorises using roles/permissions embedded in its claims. */
 export class JwtClaimsAuthStrategy {
     verifyToken;
@@ -31,14 +32,7 @@ export class JwtClaimsAuthStrategy {
      * @returns `true` when all required permissions are satisfied, `false` otherwise.
      */
     authorize(params) {
-        if (!params.requiredPermissions.length) {
-            return true;
-        }
-        const permissions = new Set(params.auth.permissions ?? []);
-        const roles = new Set(params.auth.roles ?? []);
-        return params.requiredPermissions.every((permission) => {
-            return permissions.has(permission) || roles.has(permission);
-        });
+        return checkRequiredPermissions(params.auth, params.requiredPermissions);
     }
     openApiScheme() {
         return { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' };