@edium/halifax 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -3,6 +3,75 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.4.0]
+
+### Breaking
+
+- **`RouteHandlerContext.resolveRepo` and `GraphQLResourceContext.resolveRepo` now require a
+  third `action: CrudAction` argument** — the resolver function signature has changed from
+  `(req: HttpRequest, auth: AuthContext) => Promise<Repository>` to
+  `(req: HttpRequest, auth: AuthContext, action: CrudAction) => Promise<Repository>`. The
+  `action` parameter carries the name of the CRUD operation being performed (e.g. `'readMany'`,
+  `'create'`) so that action-aware logic (such as the new admin bypass) can branch correctly
+  inside the closure. All built-in handlers and resolvers pass the correct action. Custom
+  integrations that construct a `RouteHandlerContext` or `GraphQLResourceContext` directly must
+  update their `resolveRepo` implementation to accept and handle the third argument.
+
+- **`GraphQLOptions.enabled` must now be explicitly set to `true`** — previously, supplying a
+  `graphql: { ... }` object without `enabled: false` activated the endpoint. The new default is
+  off: the endpoint is registered only when `graphql: { enabled: true, ... }` is passed. This
+  makes GraphQL a deliberate opt-in and avoids importing the optional `graphql` peer dependency
+  unless it is actually used. Existing configurations that relied on the implicit default must
+  add `enabled: true`.
+
+### Added
+
+- **GraphQL endpoint** — Halifax can now expose a full GraphQL API alongside REST. The schema
+  is built at startup from the same resource definitions that drive REST: no separate schema
+  file, no annotations. For each resource Halifax generates `get<T>`, `list<T>`, and
+  `query<T>` query fields plus `create<T>`, `createMany<T>`, `update<T>`, `updateMany<T>`,
+  `upsert<T>`, `delete<T>`, and `deleteMany<T>` mutation fields — only those allowed by
+  `resource.permissions` are included. The same auth strategy, tenant scoping, field-level
+  security (`readRoles`/`writeRoles`), lifecycle hooks, and caching that apply to REST apply
+  identically to GraphQL resolvers. Requires the optional `graphql` (≥ 16.0.0) peer dependency.
+
+  ```ts
+  createExpressCrudRouter(resources, {
+    graphql: { enabled: true, path: '/graphql', graphiql: true }
+  })
+  ```
+
+  - `GET /graphql` serves the GraphiQL browser IDE (disable with `graphiql: false`).
+  - `requireAuth: true` gates even introspection behind `authStrategy.authenticate`.
+  - Set `graphql: false` on any `ResourceDefinition` to exclude it from the schema while
+    keeping it on REST.
+  - See [README_GRAPHQL.md](./README_GRAPHQL.md) for full documentation and examples.
+
+- **Admin tenant bypass** — callers whose `auth.roles` or `auth.permissions` matches any entry
+  in `TenantOptions.bypassRoles` receive an unscoped repository for read operations
+  (`readOne`, `readMany`, `readManyWithQueryBuilder`), allowing them to query across all
+  tenants. Write operations (`create`, `updateOne`, `updateMany`, `upsertOne`, `deleteOne`,
+  `deleteMany`) are never bypassed — the tenant value on writes continues to come from
+  `resolveId`, keeping write provenance tied to authentication rather than client input.
+  Admins who want to read a single tenant's data use the standard filter syntax
+  (`?companyId=42` on REST, `filter: { companyId: 42 }` in GraphQL) rather than any special
+  override mechanism.
+
+  ```ts
+  tenant: {
+    resolveId: ({ auth }) => auth.claims?.companyId,
+    bypassRoles: ['super_admin', 'support:read-all'],   // role OR permission slug
+  }
+  ```
+
+  Per-resource override via `ResourceDefinition.bypassTenantRoles` takes precedence over the
+  API-wide list. Set it to `[]` on a resource to prevent bypass entirely for that model even
+  when a global `bypassRoles` is configured.
+
+- **`README_GRAPHQL.md`** — new reference document covering GraphQL opt-in setup, the
+  auto-generated schema (queries, mutations, types), per-resource opt-out, the GraphiQL IDE,
+  authentication, tenant bypass behaviour, and annotated query/mutation examples.
+
 ## [2.3.0]
 
 ### Security

package/README.md

@@ -17,9 +17,10 @@ The package is split into small, replaceable layers — nothing is imported into
 - 🗄️ **Two ORM adapters, six databases** — `PrismaAdapter` covers PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, and SQLite; `DrizzleAdapter` (sub-path `@edium/halifax/drizzle`) covers PostgreSQL, MySQL, SQLite, and LibSQL. Both compile to ORM calls (never raw SQL) so the same query behaves identically across engines.
 - 🔎 **Dynamic query-builder endpoint** — let the front-end compose rich filtered/sorted/paginated queries "for free" (`AND`/`OR`/nesting, `IN`, `BETWEEN`, `CONTAINS`, …) without hand-writing endpoints. Fully validated — bad fields/operators return structured `4xx` errors, never leaked DB internals.
 - 📄 **OpenAPI 3.1 generation** — zero-annotation spec generated from your resource definitions at startup. Prisma and Drizzle types are introspected automatically; custom repos annotate individual fields. Swagger UI at `/docs`, raw spec at `/openapi.json`. Disable with `enabled: false` for zero production overhead.
-- 🏢 **Multi-tenancy built in** — per-resource tenant scoping with fail-closed guarantees; one tenant can never read or write another's rows.
+- 🏢 **Multi-tenancy built in** — per-resource tenant scoping with fail-closed guarantees; one tenant can never read or write another's rows. Privileged roles (admin, super-admin) can optionally bypass scoping to read across all tenants, with per-resource granularity. See [README_MULTITENANCY.md](./README_MULTITENANCY.md).
 - ⚡ **Pluggable read-through caching** — in-memory or Redis, per-resource TTLs, never-expire mode, automatic write-invalidation, tenant-safe keys, and a `Cache-Control` bust header.
-- 🔐 **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action permissions; `filterable`/`sortable`/`selectable`/`writable` field flags; and per-field `readRoles`/`writeRoles` for role-based column visibility.
+- 🔐 **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action permissions (matched against roles OR permission slugs); `filterable`/`sortable`/`selectable`/`writable` field flags; and per-field `readRoles`/`writeRoles` for role-based column visibility.
+- 🔷 **GraphQL endpoint** — opt-in GraphQL API auto-generated from the same resource definitions as REST. Every query, mutation, filter, sort, and field-level permission works identically. Includes a GraphiQL IDE, per-resource opt-out, and full tenant bypass support. See [README_GRAPHQL.md](./README_GRAPHQL.md).
 - 🪝 **Lifecycle hooks** — inject custom logic before or after any CRUD operation per resource (`beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, …). Stamp audit fields, emit events, enforce ownership, or transform results without writing a custom repository. See [README_HOOKS.md](./README_HOOKS.md).
 - 📦 **Companion browser client** — [`@edium/halifax-client`](https://www.npmjs.com/package/@edium/halifax-client) is a typed, zero-dependency client with a fluent query builder and built-in TanStack Query helpers (queries + mutation auto-invalidation). Bring your own HTTP library (fetch, axios, ky, ofetch, superagent).
 - 🧪 **Type-safe & battle-tested** — strict TypeScript, ESM, ships full `.d.ts`; hundreds of unit tests plus the full integration suite run against six real databases + Redis in CI.
@@ -30,9 +31,10 @@ The package is split into small, replaceable layers — nothing is imported into
 | -------------- | -------------------------------------------------------------------------------------------------------------------- |
 | HTTP server    | Express 4/5, Fastify, HyperExpress, Ultimate Express                                                                 |
 | ORM / database | Prisma 6 or 7 (Postgres, MySQL, MariaDB, SQL Server, CockroachDB, SQLite); Drizzle (Postgres, MySQL, SQLite, LibSQL) |
-| Auth           | API key, JWT/Bearer, Passport + JWT; per-field `readRoles`/`writeRoles`                                              |
+| Auth           | API key, JWT/Bearer, Passport + JWT; per-field `readRoles`/`writeRoles`; role or permission slug                     |
 | Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)                                                  |
 | API docs       | OpenAPI 3.1 spec + Swagger UI (optional, zero overhead when disabled)                                                |
+| GraphQL        | Auto-generated schema from resource definitions; opt-in; GraphiQL IDE; requires `graphql` ≥ 16 peer dep             |
 
 Every HTTP adapter is interchangeable and behaves identically — same routes, status codes,
 error-body shape, and content negotiation — so you can switch frameworks without touching
@@ -168,6 +170,7 @@ app.listen(3000)
 | [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)                                                  | Query-builder payload, comparisons, nested filters, portable execution                                   |
 | [README_CACHE.md](./README_CACHE.md)                                                                | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header                          |
 | [README_HOOKS.md](./README_HOOKS.md)                                                                | Lifecycle hooks: `beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, and every other hook    |
+| [README_GRAPHQL.md](./README_GRAPHQL.md)                                                            | GraphQL endpoint: opt-in setup, auto-generated schema, GraphiQL IDE, auth, tenant bypass for admins      |
 | [README_OPENAPI.md](./README_OPENAPI.md)                                                            | OpenAPI 3.1 spec generation, Swagger UI, type introspection, security schemes, programmatic use          |
 | [README_TYPES.md](./README_TYPES.md)                                                                | All exported type aliases, enums (`SqlComparison`, `SqlOperator`, `SqlOrder`), and constants             |
 | [README_INTERFACES.md](./README_INTERFACES.md)                                                      | All exported interfaces — resource, auth, HTTP, repository, cache, Prisma, Drizzle, query AST            |

package/README_GRAPHQL.md

@@ -0,0 +1,352 @@
+# Halifax GraphQL
+
+Halifax can automatically expose a GraphQL API alongside your REST endpoints. The schema is generated at startup from the same resource definitions that drive REST — no extra annotation or separate schema file required.
+
+GraphQL is **opt-in**: nothing happens unless you explicitly set `enabled: true`.
+
+## Contents
+
+- [Installation](#installation)
+- [Enabling GraphQL](#enabling-graphql)
+- [What gets generated](#what-gets-generated)
+- [Per-resource opt-out](#per-resource-opt-out)
+- [GraphiQL IDE](#graphiql-ide)
+- [Authentication](#authentication)
+- [Tenant scoping and admin bypass](#tenant-scoping-and-admin-bypass)
+- [Query examples](#query-examples)
+- [Mutation examples](#mutation-examples)
+- [Types reference](#types-reference)
+
+---
+
+## Installation
+
+The `graphql` package is a peer dependency — install it alongside Halifax:
+
+```bash
+npm install graphql
+# or
+pnpm add graphql
+```
+
+Halifax is tested against `graphql` v16.
+
+---
+
+## Enabling GraphQL
+
+Pass `graphql: { enabled: true }` to `registerCrudApi` (or `createExpressCrudRouter`):
+
+```ts
+import { createExpressCrudRouter } from '@edium/halifax'
+
+const app = createExpressCrudRouter(resources, {
+  graphql: {
+    enabled: true,          // required — GraphQL is off by default
+    path: '/graphql',       // default: '/graphql'
+    graphiql: true,         // default: true — serve the GraphiQL IDE at GET /graphql
+    requireAuth: false,     // default: false — set true to require auth before any operation
+    title: 'My API'         // browser tab title in GraphiQL
+  }
+})
+```
+
+Two routes are registered:
+
+| Route | Purpose |
+|---|---|
+| `POST /graphql` | Execute GraphQL queries and mutations |
+| `GET /graphql` | GraphiQL browser IDE (disable with `graphiql: false`) |
+
+---
+
+## What gets generated
+
+For every resource Halifax generates:
+
+**Query fields**
+
+| Field | REST equivalent | Description |
+|---|---|---|
+| `get<Resource>(id: ID!)` | `GET /<resource>/:id` | Fetch one record by ID |
+| `list<Resource>(filter, limit, offset, orderBy, include)` | `GET /<resource>` | Paginated list with equality filters |
+| `query<Resource>(where, fields, distinct, limit, offset, orderBy, include)` | `POST /<resource>/query` | Advanced query with full filter expressions |
+
+**Mutation fields**
+
+| Field | REST equivalent | Description |
+|---|---|---|
+| `create<Resource>(input)` | `POST /<resource>` | Create one record |
+| `createMany<Resource>(input)` | `POST /<resource>` (array body) | Create multiple records |
+| `update<Resource>(id, input)` | `PATCH /<resource>/:id` | Partial update |
+| `updateMany<Resource>(where, update)` | `PATCH /<resource>` | Bulk update |
+| `upsert<Resource>(id, input)` | `PUT /<resource>/:id` | Create or replace |
+| `delete<Resource>(id)` | `DELETE /<resource>/:id` | Delete one record |
+| `deleteMany<Resource>(where)` | `DELETE /<resource>` | Bulk delete |
+
+Only operations allowed by `resource.permissions` are included. If `allowDeleteMany: false`, no `deleteMany<Resource>` mutation is generated.
+
+---
+
+## Per-resource opt-out
+
+Set `graphql: false` on any resource to exclude it from the GraphQL schema entirely:
+
+```ts
+const resources = [
+  {
+    routePrefix: 'users',
+    repository: userRepo,
+    // visible in REST and GraphQL (default)
+  },
+  {
+    routePrefix: 'audit-logs',
+    repository: auditRepo,
+    graphql: false,  // REST only — excluded from GraphQL
+  }
+]
+```
+
+---
+
+## GraphiQL IDE
+
+When `graphiql: true` (the default), visiting `GET /graphql` in a browser opens the GraphiQL IDE. You can explore the auto-generated schema using introspection, run queries interactively, and inspect the full type system.
+
+To disable the IDE (e.g. in production):
+
+```ts
+graphql: { enabled: true, graphiql: false }
+```
+
+---
+
+## Authentication
+
+GraphQL uses the same `authStrategy` as REST. Every resolver calls `authenticate` before executing, so your JWT/API-key validation fires automatically.
+
+To require authentication before even responding to introspection queries, set `requireAuth: true`:
+
+```ts
+graphql: { enabled: true, requireAuth: true }
+```
+
+Fine-grained permissions (`resource.requiredPermissions`) apply per resolver, identical to REST. Per-field `readRoles`/`writeRoles` restrictions are also enforced — restricted fields are stripped from resolver results.
+
+---
+
+## Tenant scoping and admin bypass
+
+The GraphQL endpoint respects the same tenant isolation that REST does. Each resolver resolves the tenant from the caller's auth context (JWT claims, session, etc.) and scopes the repository automatically — regular users can only see their own tenant's data. The tenant value is **always derived from auth**, never from client-supplied input.
+
+### Admin bypass
+
+Admins who need to query across all tenants can be granted bypass access by listing their roles or permission slugs in `TenantOptions.bypassRoles` (API-wide default) or `ResourceDefinition.bypassTenantRoles` (per-resource override).
+
+```ts
+createExpressCrudRouter(resources, {
+  tenant: {
+    resolveId: (ctx) => ctx.auth.claims?.companyId,
+    bypassRoles: ['super_admin', 'support:read-all'],  // role OR permission slug
+  }
+})
+```
+
+**How it works:**
+
+- **Bypass role → all records.** An admin whose `auth.roles` or `auth.permissions` matches any entry in `bypassRoles` gets an unscoped read — all rows across all tenants.
+- **No bypass role → normal scoping.** Regular users are always scoped to their tenant. The bypass path is unreachable for them.
+- **Writes are never bypassed.** Write operations always resolve the tenant through `resolveId`. An admin whose token carries a `companyId` writes to that company; one without a tenant receives 403 (unless `strict: false`). The tenant field on writes always comes from auth — never from the client.
+
+**Narrowing to a single tenant (admin reads):**
+
+When an admin wants to see just one tenant's data, they use the same filter mechanism as any other caller — the tenant field is just another filterable column:
+
+```graphql
+# All tenants (bypass active, no filter)
+{ listOrders { count results { id companyId total } } }
+
+# One specific tenant — admin narrows with a filter
+{ listOrders(filter: { companyId: 42 }) { count results { id companyId total } } }
+
+# Or with the full query builder
+{
+  queryOrders(where: [
+    { field: "companyId", comparison: "=", value1: 42 }
+  ]) { count results { id companyId total } }
+}
+```
+
+On REST it works the same way:
+```
+# All tenants
+GET /orders
+
+# One tenant
+GET /orders?companyId=42
+```
+
+No special header or query parameter needed — the normal filter API handles it.
+
+#### Per-resource bypass override
+
+Override the global `bypassRoles` for a single resource — or disable bypass entirely for sensitive models:
+
+```ts
+const resources = [
+  {
+    routePrefix: 'orders',
+    repository: orderRepo,
+    // inherits bypassRoles from TenantOptions
+  },
+  {
+    routePrefix: 'payment-methods',
+    repository: paymentRepo,
+    bypassTenantRoles: [],           // no one bypasses tenant on this resource
+  },
+  {
+    routePrefix: 'users',
+    repository: userRepo,
+    bypassTenantRoles: ['super_admin'],  // only super_admin, not support:read-all
+  }
+]
+```
+
+---
+
+## Query examples
+
+### Fetch one record
+
+```graphql
+query {
+  getUser(id: "42") {
+    id
+    name
+    email
+  }
+}
+```
+
+### Paginated list with filters
+
+```graphql
+query {
+  listUsers(
+    filter: { status: "active" }
+    limit: 20
+    offset: 0
+    orderBy: [{ field: "createdAt", direction: desc }]
+  ) {
+    count
+    results {
+      id
+      name
+      email
+    }
+  }
+}
+```
+
+### Advanced query (full filter expressions)
+
+```graphql
+query {
+  queryUsers(
+    where: [
+      { field: "status", comparison: "IN", value1: ["active", "trial"] },
+      { operator: "AND" },
+      { field: "createdAt", comparison: ">=", value1: "2025-01-01" }
+    ]
+    orderBy: [{ field: "name", direction: asc }]
+    limit: 50
+  ) {
+    count
+    results {
+      id
+      name
+      email
+    }
+  }
+}
+```
+
+### With variables
+
+```graphql
+query ListActiveUsers($status: String!, $limit: Int) {
+  listUsers(filter: { status: $status }, limit: $limit) {
+    count
+    results { id name }
+  }
+}
+```
+
+Variables payload:
+```json
+{ "status": "active", "limit": 10 }
+```
+
+---
+
+## Mutation examples
+
+### Create
+
+```graphql
+mutation {
+  createUser(input: { name: "Alice", email: "alice@example.com" }) {
+    id
+    name
+    email
+  }
+}
+```
+
+### Partial update
+
+```graphql
+mutation {
+  updateUser(id: "42", input: { name: "Alice Smith" }) {
+    id
+    name
+  }
+}
+```
+
+### Bulk update
+
+```graphql
+mutation {
+  updateManyUser(
+    where: [{ field: "status", comparison: "=", value1: "trial" }]
+    update: { status: "active" }
+  ) {
+    updated
+  }
+}
+```
+
+### Delete
+
+```graphql
+mutation {
+  deleteUser(id: "42")
+}
+```
+
+---
+
+## Types reference
+
+| Type | Description |
+|---|---|
+| `GraphQLOptions` | Configuration object passed to `registerCrudApi` / `createExpressCrudRouter` |
+| `GraphQLResourceContext` | Internal per-resource context (available if building custom integrations) |
+| `GraphQLResolverContext` | The `contextValue` available in every resolver: `{ req: HttpRequest }` |
+
+All types are re-exported from `@edium/halifax`:
+
+```ts
+import type { GraphQLOptions, GraphQLResourceContext, GraphQLResolverContext } from '@edium/halifax'
+```

package/README_INTERFACES.md

@@ -27,6 +27,8 @@ Full definition of a Halifax resource. Pass an array of these to `createExpressC
 | `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.                                                                                                                                |
+| `graphql`             | `boolean`                               | no       | When `false`, excludes this resource from the auto-generated GraphQL schema while keeping it on REST. Defaults to `true` when GraphQL is enabled.                                                                                           |
+| `bypassTenantRoles`   | `string[]`                              | no       | Roles or permission slugs whose holders bypass tenant scoping for read operations on this resource. Overrides `TenantOptions.bypassRoles`. Set to `[]` to prevent bypass on this resource even when a global list is configured.            |
 
 ---
 
@@ -232,9 +234,10 @@ Configures multi-tenant isolation API-wide. Set on `CrudApiOptions.tenant`.
 
 | Property    | Type                                                         | Default      | Description                                                                                                                                                         |
 | ----------- | ------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `resolveId` | `(ctx: TenantResolveContext) => unknown \| Promise<unknown>` | required     | Resolves the tenant key from the auth context and request. Must come from the token/session — never from client input. Return `null`/`undefined` when none applies. |
-| `field`     | `string`                                                     | `'tenantId'` | Default column name for auto-detection: resources with a field of this name are automatically scoped on it.                                                         |
-| `strict`    | `boolean`                                                    | `true`       | When `true`, a tenant-scoped resource whose `resolveId` returns no value rejects with 403 rather than serving unscoped.                                             |
+| `resolveId`   | `(ctx: TenantResolveContext) => unknown \| Promise<unknown>` | required     | Resolves the tenant key from the auth context and request. Must come from the token/session — never from client input. Return `null`/`undefined` when none applies. |
+| `field`       | `string`                                                     | `'tenantId'` | Default column name for auto-detection: resources with a field of this name are automatically scoped on it.                                                         |
+| `strict`      | `boolean`                                                    | `true`       | When `true`, a tenant-scoped resource whose `resolveId` returns no value rejects with 403 rather than serving unscoped.                                             |
+| `bypassRoles` | `string[]`                                                   | —            | Roles or permission slugs (matched against `auth.roles` OR `auth.permissions`) whose holders receive unscoped reads across all tenants. Writes are never bypassed. Per-resource `ResourceDefinition.bypassTenantRoles` takes precedence. |
 
 ---
 

package/README_MULTITENANCY.md

@@ -84,6 +84,11 @@ interface TenantOptions {
   field?: string
   /** Fail-closed when no tenant resolves. Defaults to true. */
   strict?: boolean
+  /**
+   * Roles or permission slugs whose holders bypass tenant scoping on read operations.
+   * See "Admin bypass" below.
+   */
+  bypassRoles?: string[]
 }
 ```
 
@@ -113,6 +118,88 @@ createPrismaResources(prisma, models, {
 })
 ```
 
+## Admin bypass
+
+Sometimes a super-admin or support role needs to read across all tenants — for reporting,
+debugging, or backoffice tooling — without being confined to a single company's data.
+
+### Enabling bypass
+
+Add `bypassRoles` to `TenantOptions`. Any caller whose `auth.roles` **or** `auth.permissions`
+matches at least one entry is granted an unscoped read:
+
+```ts
+createExpressCrudRouter(resources, {
+  tenant: {
+    resolveId: ({ auth }) => auth.claims?.companyId,
+    bypassRoles: ['super_admin', 'support:read-all'],
+  }
+})
+```
+
+Values are matched against both `auth.roles` and `auth.permissions` — either paradigm works.
+
+### What bypass does (and does not do)
+
+| Operation | Behaviour with bypass |
+| --- | --- |
+| `GET /resource` — list | Returns rows from **all** tenants (unscoped) |
+| `GET /resource/:id` | Returns the record regardless of which tenant owns it |
+| `POST /resource/query` (query builder) | Returns rows from all tenants |
+| `POST /resource` (create) | **Not bypassed** — tenant value still comes from `resolveId` |
+| `PATCH`, `PUT`, `DELETE` | **Not bypassed** — tenant value still comes from `resolveId` |
+
+Writes are deliberately excluded. Tenant on writes comes from the authenticated session —
+never from the client and never from the bypass path. An admin writing through the API either has a `companyId` in their token (and writes to that company) or receives 403.
+
+### Narrowing a bypass read to one tenant
+
+When a super-admin wants data for a specific company they use the **normal filter mechanism**
+— the tenant field is just another filterable column from their perspective. No special header or query parameter is needed:
+
+```
+# All tenants (bypass active, no filter)
+GET /orders
+
+# One specific tenant
+GET /orders?companyId=42
+```
+
+In GraphQL:
+
+```graphql
+# All tenants
+{ listOrders { count results { id companyId total } } }
+
+# One tenant
+{ listOrders(filter: { companyId: 42 }) { count results { id companyId total } } }
+```
+
+### Per-resource bypass override
+
+`ResourceDefinition.bypassTenantRoles` overrides the global `bypassRoles` for one resource.
+Set it to `[]` to prevent bypass on a particularly sensitive model:
+
+```ts
+const resources = [
+  {
+    routePrefix: 'orders',
+    repository: orderRepo,
+    // inherits bypassRoles from TenantOptions → super_admin gets all
+  },
+  {
+    routePrefix: 'payment-methods',
+    repository: paymentRepo,
+    bypassTenantRoles: [],           // always scoped — even super_admin sees only their tenant
+  },
+  {
+    routePrefix: 'users',
+    repository: userRepo,
+    bypassTenantRoles: ['super_admin'],  // only super_admin bypasses; support:read-all does not
+  }
+]
+```
+
 ## Security model
 
 Tenant scoping is designed to **fail closed**. The guarantees:

package/README_OPENAPI.md

@@ -240,7 +240,7 @@ The body combines `QueryOptions` fields (to select records) with an `update` key
 
 ```json
 {
-  "where": [{ "field": "status", "comparison": "=", "value": "draft" }],
+  "where": [{ "field": "status", "comparison": "=", "value1": "draft" }],
   "update": { "status": "archived" }
 }
 ```
@@ -274,13 +274,13 @@ The query builder endpoint accepts a `QueryOptions` body for full-featured filte
 ```json
 {
   "where": [
-    { "field": "published", "comparison": "=", "value": true },
-    { "field": "createdAt", "comparison": ">=", "value": "2024-01-01T00:00:00Z" },
+    { "field": "published", "comparison": "=", "value1": true },
+    { "field": "createdAt", "comparison": ">=", "value1": "2024-01-01T00:00:00Z" },
     {
       "operator": "OR",
       "children": [
-        { "field": "title", "comparison": "CONTAINS", "value": "Halifax" },
-        { "field": "title", "comparison": "STARTS WITH", "value": "Hello" }
+        { "field": "title", "comparison": "CONTAINS", "value1": "Halifax" },
+        { "field": "title", "comparison": "STARTS WITH", "value1": "Hello" }
       ]
     }
   ],
@@ -318,12 +318,12 @@ Flat `where` arrays use **AND-precedence over OR** (same as SQL). Use `children`
 ```json
 {
   "where": [
-    { "field": "active", "comparison": "=", "value": true },
+    { "field": "active", "comparison": "=", "value1": true },
     {
       "operator": "OR",
       "children": [
-        { "field": "role", "comparison": "=", "value": "admin" },
-        { "field": "role", "comparison": "=", "value": "moderator" }
+        { "field": "role", "comparison": "=", "value1": "admin" },
+        { "field": "role", "comparison": "=", "value1": "moderator" }
       ]
     }
   ]