@edium/halifax 2.2.3 → 2.4.0

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' };

package/dist/auth/strategies/PassportStrategies.js

@@ -1,4 +1,5 @@
 import { AuthenticationError } from '../../errors/AuthenticationError.js';
+import { checkRequiredPermissions } from './types.js';
 /**
  * Extracts `userId`, `roles`, `permissions`, and `claims` from a raw Passport user payload.
  * @param user - The raw user object returned by Passport (typically a decoded JWT payload).
@@ -17,13 +18,6 @@ function defaultMapUser(user) {
         ctx.userId = userId;
     return ctx;
 }
-function checkPermissions(auth, requiredPermissions) {
-    if (!requiredPermissions.length)
-        return true;
-    const permissions = new Set(auth.permissions ?? []);
-    const roles = new Set(auth.roles ?? []);
-    return requiredPermissions.every((p) => permissions.has(p) || roles.has(p));
-}
 /** Delegates authentication to a caller-provided Passport authenticate wrapper. */
 export class PassportAuthStrategy {
     authenticateWithPassport;
@@ -85,7 +79,7 @@ export class PassportJwtStrategy {
      * @returns `true` when all required permissions are satisfied, `false` otherwise.
      */
     authorize(params) {
-        return checkPermissions(params.auth, params.requiredPermissions);
+        return checkRequiredPermissions(params.auth, params.requiredPermissions);
     }
     openApiScheme() {
         return { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' };
@@ -129,7 +123,7 @@ export class PassportSessionStrategy {
      * @returns `true` when all required permissions are satisfied, `false` otherwise.
      */
     authorize(params) {
-        return checkPermissions(params.auth, params.requiredPermissions);
+        return checkRequiredPermissions(params.auth, params.requiredPermissions);
     }
     openApiScheme() {
         return {

package/dist/auth/strategies/types.d.ts

@@ -45,6 +45,13 @@ export type SecurityScheme = {
     scheme: 'basic';
     description?: string;
 };
+/**
+ * Checks whether an auth context satisfies `requiredPermissions`.
+ * Semantics: **any single match** in `auth.permissions` OR `auth.roles` grants access
+ * (i.e. the list is an OR — "user must have at least one of these"). This mirrors
+ * the documented behaviour of `FieldDefinition.readRoles` / `writeRoles`.
+ */
+export declare function checkRequiredPermissions(auth: AuthContext, requiredPermissions: string[]): boolean;
 /** Contract for pluggable authentication and authorisation strategies. */
 export interface AuthStrategy {
     /**

package/dist/auth/strategies/types.js

@@ -1 +1,13 @@
-export {};
+/**
+ * Checks whether an auth context satisfies `requiredPermissions`.
+ * Semantics: **any single match** in `auth.permissions` OR `auth.roles` grants access
+ * (i.e. the list is an OR — "user must have at least one of these"). This mirrors
+ * the documented behaviour of `FieldDefinition.readRoles` / `writeRoles`.
+ */
+export function checkRequiredPermissions(auth, requiredPermissions) {
+    if (!requiredPermissions.length)
+        return true;
+    const permissions = new Set(auth.permissions ?? []);
+    const roles = new Set(auth.roles ?? []);
+    return requiredPermissions.some((p) => permissions.has(p) || roles.has(p));
+}

package/dist/core/cache/CacheStore.d.ts

@@ -22,4 +22,16 @@ export interface CacheStore {
      * @param key - Cache key to remove.
      */
     delete(key: string): Promise<void> | void;
+    /**
+     * Atomically increment an integer counter and return the new value.
+     * When the key does not exist, it is initialised to `0` before incrementing.
+     *
+     * Implementing this method is **strongly recommended** for multi-process stores
+     * (e.g. Redis) — without it, `createCachingRepository` falls back to a non-atomic
+     * read-then-write version-bump that can lose invalidations under concurrent writes.
+     *
+     * Single-process stores (`InMemoryCacheStore`) can implement this synchronously and
+     * are immune to the race regardless, but should still implement it for correctness.
+     */
+    increment?(key: string): Promise<number> | number;
 }

package/dist/core/cache/createCachingRepository.js

@@ -34,7 +34,16 @@ export function createCachingRepository(repo, options) {
         return typeof v === 'number' ? v : 0;
     };
     const bumpVersion = async () => {
-        await store.set(versionKey, (await readVersion()) + 1);
+        // Use store.increment when available (atomic on Redis via INCR; race-free on
+        // InMemoryCacheStore because Node.js is single-threaded). Fall back to a non-atomic
+        // read-then-write only when the store does not expose increment — acceptable for
+        // custom single-process stores where concurrent writes cannot interleave.
+        if (store.increment) {
+            await store.increment(versionKey);
+        }
+        else {
+            await store.set(versionKey, (await readVersion()) + 1);
+        }
     };
     const keyFor = async (op, payload) => `${namespace}:v${await readVersion()}:${op}:${stableStringify(payload)}`;
     const cachedRead = async (op, payload, run) => {

package/dist/core/cache/in-memory/InMemoryCacheStore.d.ts

@@ -5,15 +5,28 @@ import type { CacheStore } from '../CacheStore.js';
  * Suitable for single-process deployments and tests. For multi-instance deployments,
  * inject a shared store (e.g. `RedisCacheStore`) instead so cache and invalidation are
  * consistent across processes.
+ *
+ * Expired entries are lazily evicted on reads. To prevent unbounded accumulation under
+ * write-heavy workloads, a sweep of all expired entries runs automatically every
+ * `sweepEvery` writes (default: 200). Adjust via the constructor option.
  */
 export declare class InMemoryCacheStore implements CacheStore {
     private readonly now;
     private readonly map;
+    private setCount;
+    private readonly sweepEvery;
     /**
      * @param now - Clock function (ms epoch). Injectable for tests; defaults to `Date.now`.
+     * @param sweepEvery - Run a full expired-entry sweep every N `set` calls. Defaults to 200.
      */
-    constructor(now?: () => number);
+    constructor(now?: () => number, sweepEvery?: number);
     get(key: string): unknown;
     set(key: string, value: unknown, ttlSeconds?: number): void;
     delete(key: string): void;
+    /**
+     * Atomically increments an integer counter and returns the new value.
+     * Because Node.js is single-threaded this is race-free without a lock.
+     */
+    increment(key: string): number;
+    private purgeExpired;
 }

package/dist/core/cache/in-memory/InMemoryCacheStore.js

@@ -4,15 +4,23 @@
  * Suitable for single-process deployments and tests. For multi-instance deployments,
  * inject a shared store (e.g. `RedisCacheStore`) instead so cache and invalidation are
  * consistent across processes.
+ *
+ * Expired entries are lazily evicted on reads. To prevent unbounded accumulation under
+ * write-heavy workloads, a sweep of all expired entries runs automatically every
+ * `sweepEvery` writes (default: 200). Adjust via the constructor option.
  */
 export class InMemoryCacheStore {
     now;
     map = new Map();
+    setCount = 0;
+    sweepEvery;
     /**
      * @param now - Clock function (ms epoch). Injectable for tests; defaults to `Date.now`.
+     * @param sweepEvery - Run a full expired-entry sweep every N `set` calls. Defaults to 200.
      */
-    constructor(now = () => Date.now()) {
+    constructor(now = () => Date.now(), sweepEvery = 200) {
         this.now = now;
+        this.sweepEvery = sweepEvery;
     }
     get(key) {
         const entry = this.map.get(key);
@@ -27,8 +35,28 @@ export class InMemoryCacheStore {
     set(key, value, ttlSeconds) {
         const expiresAt = ttlSeconds && ttlSeconds > 0 ? this.now() + ttlSeconds * 1000 : null;
         this.map.set(key, { value, expiresAt });
+        if (++this.setCount % this.sweepEvery === 0)
+            this.purgeExpired();
     }
     delete(key) {
         this.map.delete(key);
     }
+    /**
+     * Atomically increments an integer counter and returns the new value.
+     * Because Node.js is single-threaded this is race-free without a lock.
+     */
+    increment(key) {
+        const entry = this.map.get(key);
+        const current = typeof entry?.value === 'number' ? entry.value : 0;
+        const next = current + 1;
+        this.map.set(key, { value: next, expiresAt: null });
+        return next;
+    }
+    purgeExpired() {
+        const now = this.now();
+        for (const [key, entry] of this.map) {
+            if (entry.expiresAt !== null && entry.expiresAt <= now)
+                this.map.delete(key);
+        }
+    }
 }

package/dist/core/cache/redis/RedisCacheStore.d.ts

@@ -25,4 +25,10 @@ export declare class RedisCacheStore implements CacheStore {
     get(key: string): Promise<unknown>;
     set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
     delete(key: string): Promise<void>;
+    /**
+     * Atomically increments the integer stored at `key` (using Redis `INCR`) and returns
+     * the new value. Falls back to a non-atomic get-then-set when the underlying client
+     * does not expose `incr` — this should not occur with standard Redis clients.
+     */
+    increment(key: string): Promise<number>;
 }

package/dist/core/cache/redis/RedisCacheStore.js

@@ -39,4 +39,18 @@ export class RedisCacheStore {
     async delete(key) {
         await this.client.del(this.prefix + key);
     }
+    /**
+     * Atomically increments the integer stored at `key` (using Redis `INCR`) and returns
+     * the new value. Falls back to a non-atomic get-then-set when the underlying client
+     * does not expose `incr` — this should not occur with standard Redis clients.
+     */
+    async increment(key) {
+        if (this.client.incr) {
+            return await this.client.incr(this.prefix + key);
+        }
+        const raw = await this.client.get(this.prefix + key);
+        const next = (raw !== null ? parseInt(raw, 10) : 0) + 1;
+        await this.client.set(this.prefix + key, String(next));
+        return next;
+    }
 }

package/dist/core/cache/redis/RedisLikeClient.d.ts

@@ -9,4 +9,6 @@ export interface RedisLikeClient {
         EX?: number;
     }): Promise<unknown>;
     del(key: string): Promise<unknown>;
+    /** Atomic integer increment — maps to Redis `INCR`. Optional but strongly recommended. */
+    incr?(key: string): Promise<number>;
 }

package/dist/core/crudRouter.d.ts

@@ -1,6 +1,7 @@
 import { type AuthContext, type AuthStrategy } from '../auth/AuthStrategy.js';
 import { type CacheStore } from '../core/cache/index.js';
 import { type OpenApiOptions } from '../openapi/index.js';
+import { type GraphQLOptions } from '../graphql/index.js';
 import { type ResourceDefinition } from '../core/types.js';
 import type { HttpRequest, HttpServer } from '../core/types.js';
 import { normalizeError } from '../core/handlerUtils.js';
@@ -40,6 +41,29 @@ export interface TenantOptions {
      * cross-tenant ("god mode") access for callers with no tenant.
      */
     strict?: boolean;
+    /**
+     * Roles or permission slugs whose holders may bypass tenant scoping for **read** operations
+     * (`getOne`, `getMany`, and the query builder), allowing them to see records across all tenants.
+     * Any single match in `auth.roles` or `auth.permissions` grants the bypass.
+     *
+     * When a bypass caller wants to see only one tenant's data they use the normal filter
+     * mechanism — `?companyId=42` on REST or `filter: { companyId: 42 }` in GraphQL.
+     * No special header or query parameter is needed; the tenant field is just another filterable
+     * column from the admin's perspective.
+     *
+     * Write operations (create / update / delete) are **never** bypassed: the tenant value
+     * continues to come from `resolveId`, keeping write provenance tied to auth — never to
+     * client-supplied input. An admin whose token carries no tenant will receive 403 on writes
+     * unless `strict` is `false`.
+     *
+     * Per-resource {@link ResourceDefinition.bypassTenantRoles} takes precedence over this list.
+     *
+     * @example
+     * ```ts
+     * bypassRoles: ['super_admin', 'support:read-all']
+     * ```
+     */
+    bypassRoles?: string[];
 }
 /** Options for {@link registerCrudApi} / {@link createExpressCrudRouter}. */
 export interface CrudApiOptions {
@@ -60,6 +84,20 @@ export interface CrudApiOptions {
      * additional routes: `GET /openapi.json` (raw spec) and `GET /docs` (Swagger UI).
      */
     openapi?: OpenApiOptions;
+    /**
+     * Enable a GraphQL endpoint. GraphQL is **disabled by default** — you must set
+     * `enabled: true` to activate it. When enabled, Halifax registers `POST <path>` (execution)
+     * and optionally `GET <path>` (GraphiQL IDE). The schema is auto-generated from all
+     * resources that have `graphql !== false`. Requires the `graphql` peer dependency.
+     *
+     * See [README_GRAPHQL.md](./README_GRAPHQL.md) for full docs and examples.
+     *
+     * @example
+     * ```ts
+     * graphql: { enabled: true, path: '/graphql', graphiql: true }
+     * ```
+     */
+    graphql?: GraphQLOptions;
     /**
      * API-wide read-through caching. Provide a `store` (defaults to an in-process
      * {@link InMemoryCacheStore}) and/or a default `ttlSeconds` applied to every resource that

package/dist/core/crudRouter.js

@@ -1,12 +1,14 @@
 import { AllowAllAuthStrategy } from '../auth/AuthStrategy.js';
+import { checkRequiredPermissions } from '../auth/strategies/types.js';
 import { createCachingRepository, InMemoryCacheStore } from '../core/cache/index.js';
 import { generateOpenApiSpec, generateDocsHtml } from '../openapi/index.js';
+import { registerGraphqlRoute } from '../graphql/index.js';
 import { defaultCrudPermissions } from '../core/types.js';
 import { ServerError } from '../errors/ServerError.js';
 import { AuthorizationError } from '../errors/AuthorizationError.js';
 import { MethodNotAllowedError } from '../errors/MethodNotAllowedError.js';
 import { normalizeError, sendError, wantsCacheBust } from '../core/handlerUtils.js';
-import { mergeFieldDefinitions } from '../core/fields.js';
+import { mergeFieldDefinitions, mergeRelationDefinitions, normalizeEnvelope } from '../core/fields.js';
 import { registerCreate } from '../core/handlers/create.js';
 import { registerReadMany } from '../core/handlers/readMany.js';
 import { registerReadOne } from '../core/handlers/readOne.js';
@@ -53,17 +55,6 @@ function resolveFields(resource, idField) {
         ...(field.writeRoles?.length ? { writeRoles: field.writeRoles } : {})
     }));
 }
-/**
- * Merges the repository's relation schema with the resource's own relations, by name.
- */
-function resolveRelations(resource) {
-    const byName = new Map();
-    for (const relation of resource.repository?.relations ?? [])
-        byName.set(relation.name, relation);
-    for (const relation of resource.relations ?? [])
-        byName.set(relation.name, relation);
-    return [...byName.values()];
-}
 /**
  * Produces a fully-resolved resource: `name` filled in, and `fields`/`relations` resolved
  * from the repository schema + the resource's own entries. Every downstream stage operates
@@ -75,16 +66,9 @@ function normalizeResource(resource) {
         ...resource,
         name: resource.name ?? deriveResourceName(resource.routePrefix),
         fields: resolveFields(resource, idField),
-        relations: resolveRelations(resource)
+        relations: mergeRelationDefinitions(resource)
     };
 }
-/**
- * Resolves the effective envelope key. A non-empty string enables wrapping; `null`, `undefined`,
- * and `''` all mean "no envelope".
- */
-function normalizeEnvelope(value) {
-    return typeof value === 'string' && value.length > 0 ? value : null;
-}
 /**
  * Determines the column a resource is tenant-scoped on, with this precedence:
  * explicit `resource.tenant` (or `false` to opt out) → auto-detect the API's default
@@ -102,6 +86,8 @@ function effectiveTenantField(resource, tenant) {
 }
 /** Matches a safe SQL identifier — tenant fields are interpolated into SQL on bulk paths. */
 const safeIdentifier = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/** Read-only actions that admin bypass applies to. Writes always enforce tenant scoping. */
+const READ_ACTIONS = new Set(['readOne', 'readMany', 'readManyWithQueryBuilder']);
 /**
  * Registers all CRUD routes for every resource on the given HTTP server.
  *
@@ -150,10 +136,16 @@ export function registerCrudApi(server, resources, options = {}) {
                 bust
             })
             : repo;
-        const resolveRepo = async (req, auth) => {
+        const resolveRepo = async (req, auth, action) => {
             const bust = cachingEnabled && wantsCacheBust(req, bustHeader);
             if (!tenantField || !options.tenant)
                 return withCache(repository, 'global', bust);
+            // Admin bypass: callers with a privileged role/permission get unscoped reads.
+            // Writes always fall through to resolveId — tenant on writes comes from auth, never bypass.
+            const bypassRoles = resource.bypassTenantRoles ?? options.tenant.bypassRoles ?? [];
+            if (READ_ACTIONS.has(action) && bypassRoles.length > 0 && checkRequiredPermissions(auth, bypassRoles)) {
+                return withCache(repository, 'global', bust);
+            }
             const value = await options.tenant.resolveId({ auth, req, resource });
             if (value === undefined || value === null || value === '') {
                 if (options.tenant.strict !== false)
@@ -217,6 +209,48 @@ export function registerCrudApi(server, resources, options = {}) {
             });
         }
     });
+    // ─── GraphQL endpoint ──────────────────────────────────────────────────────
+    if (options.graphql?.enabled === true) {
+        // Build per-resource contexts carrying the already-resolved resolveRepo closures.
+        // We re-iterate resources to capture the closure variables that were set up above.
+        const graphqlContexts = resources.map((rawResource) => {
+            const resource = normalizeResource(rawResource);
+            const repository = rawResource.repository;
+            const tenantField = effectiveTenantField(resource, options.tenant);
+            const cacheTtl = resource.cache === false
+                ? undefined
+                : (resource.cache?.ttlSeconds ?? options.cache?.ttlSeconds);
+            const cachingEnabled = cacheTtl !== undefined;
+            const withCacheLocal = (repo, scopeKey, bust) => cachingEnabled
+                ? createCachingRepository(repo, {
+                    store: cacheStore,
+                    ttlSeconds: cacheTtl,
+                    namespace: `${resource.name}:${scopeKey}`,
+                    bust
+                })
+                : repo;
+            const resolveRepoLocal = async (req, auth, action) => {
+                const bust = cachingEnabled && wantsCacheBust(req, bustHeader);
+                if (!tenantField || !options.tenant)
+                    return withCacheLocal(repository, 'global', bust);
+                const bypassRoles = resource.bypassTenantRoles ?? options.tenant.bypassRoles ?? [];
+                if (READ_ACTIONS.has(action) && bypassRoles.length > 0 && checkRequiredPermissions(auth, bypassRoles)) {
+                    return withCacheLocal(repository, 'global', bust);
+                }
+                const value = await options.tenant.resolveId({ auth, req, resource });
+                if (value === undefined || value === null || value === '') {
+                    if (options.tenant.strict !== false)
+                        throw new AuthorizationError('No tenant is associated with this request.');
+                    return withCacheLocal(repository, 'global', bust);
+                }
+                return withCacheLocal(repository.withScope({ field: tenantField, value }), String(value), bust);
+            };
+            const hooks = resource.hooks;
+            return { resource, authStrategy, hooks, resolveRepo: resolveRepoLocal };
+        });
+        registerGraphqlRoute(server, graphqlContexts, options.graphql, authStrategy);
+    }
+    // ─── OpenAPI spec + docs ───────────────────────────────────────────────────
     if (options.openapi && options.openapi.enabled !== false) {
         const specPath = options.openapi.specPath ?? '/openapi.json';
         const docsPath = options.openapi.docsPath ?? '/docs';