@edium/halifax 2.1.0 → 2.2.0

package/CHANGELOG.md

@@ -3,6 +3,68 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0]
+
+### Added
+
+- **Lifecycle hooks** — inject custom logic before or after any CRUD operation by setting
+  `hooks` on `ResourceDefinition`. All 18 hooks cover every operation the auto-CRUD engine
+  exposes:
+
+  | Category        | Hooks                                 |
+  | --------------- | ------------------------------------- |
+  | Create          | `beforeCreate`, `afterCreate`         |
+  | Read (list)     | `beforeReadMany`, `afterReadMany`     |
+  | Read (single)   | `beforeReadOne`, `afterReadOne`       |
+  | Update (single) | `beforeUpdateOne`, `afterUpdateOne`   |
+  | Update (bulk)   | `beforeUpdateMany`, `afterUpdateMany` |
+  | Upsert          | `beforeUpsertOne`, `afterUpsertOne`   |
+  | Delete (single) | `beforeDeleteOne`, `afterDeleteOne`   |
+  | Delete (bulk)   | `beforeDeleteMany`, `afterDeleteMany` |
+  | Query builder   | `beforeQuery`, `afterQuery`           |
+
+  **Before hooks** can return a modified data object (replacing the incoming payload) or
+  `void` to leave it unchanged. Throwing any `Error` aborts the operation and sends the
+  correct HTTP error response — use Halifax error classes (`AuthorizationError`,
+  `BadRequestError`, `UnprocessableEntityError`, …) for precise status codes.
+
+  **After hooks** can return a modified result (replacing what is sent to the client) or
+  `void`. They run after the database write but before response field-filtering
+  (`readRoles` / `selectable`), so they see every field the DB returned.
+
+  Every hook receives a `HookContext` as its last argument: `{ auth, resource, req }`.
+
+  Common patterns: stamping `createdBy` / `updatedBy` from auth context, emitting domain
+  events, enforcing ownership checks beyond what `AuthStrategy` provides, restricting
+  query-builder results to the caller's own data, and soft-delete read interception.
+
+  See [README_HOOKS.md](./README_HOOKS.md) for the full reference and examples.
+
+- **OpenAPI 3.1 spec generation** — pass an `openapi` object to `createExpressCrudRouter` / `registerCrudApi` and Halifax generates a complete spec from your registered resources at startup. No manual annotation needed. Routes for `GET /openapi.json` and `GET /docs` (Swagger UI) are registered automatically at your mount point.
+  - Field types are introspected from the Prisma DMMF (`PrismaAdapter`) and from Drizzle column metadata (`DrizzleAdapter`) with no extra configuration. Custom / non-ORM repositories annotate individual fields with optional `type` and `format` on `FieldDefinition`.
+  - The spec documents exactly the operations your `permissions` allow — disabled actions are omitted entirely.
+  - Query-string parameters, request/response schemas, error shapes, and envelope wrapping are all reflected accurately.
+  - Auth is wired automatically: `ApiKeyAuthStrategy`, `JwtClaimsAuthStrategy`, `PassportJwtStrategy`, `Auth0JwtStrategy`, and `FirebaseJwtStrategy` each contribute the correct security scheme; `AllowAllAuthStrategy` produces no security requirement. Override with `openApiScheme()` on a custom strategy, or pass `securityScheme` directly in `openapi` options.
+  - Gate docs behind an environment check with `enabled: process.env.NODE_ENV !== 'production'` — when `enabled` is `false` (or the `openapi` key is omitted), no routes are registered and the generator is never called.
+  - Custom spec and docs paths via `specPath` and `docsPath`.
+  - `generateOpenApiSpec(resources, options)` is exported standalone for CI validation, static hosting, or piping into code generators.
+  - See [README_OPENAPI.md](./README_OPENAPI.md) for full documentation.
+
+- **`@edium/halifax-client` companion package** — a typed browser/Node client that lives alongside this package in the same repository. Zero runtime dependencies. Bring your own HTTP client (native `fetch`, axios, ky, ofetch, or superagent — each ships a ready-made transport adapter). Features: typed CRUD methods, a fluent `QueryBuilder` that compiles to the server's query AST, and full TanStack Query integration (read query options + mutation options with auto-invalidation) built directly into `ResourceClient`. See the [client README](../halifax-client/README.md) for details.
+
+- **Drizzle ORM adapter** — `DrizzleAdapter<TRecord, TCreate, TUpdate>` implements the full `Repository` interface against any Drizzle-compatible database (PostgreSQL, MySQL, SQLite, LibSQL). Import from the `@edium/halifax/drizzle` sub-path export; `drizzle-orm` is an optional peer dependency and is never required when unused.
+  - Field schema and OpenAPI types are derived automatically via `getTableColumns()` — no `fields` array needed.
+  - All Halifax query-AST operators are compiled to native Drizzle SQL expressions (never raw strings).
+  - Multi-tenant isolation via `withScope()` and full `executeQuery()` (query-builder endpoint) support.
+  - Primary key is auto-detected from the table schema; override with `config.idField` when using composite keys or non-standard names.
+  - See [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) for usage.
+
+- **Per-field role-based access control** — `FieldDefinition` gains two optional arrays:
+  - `readRoles: string[]` — callers whose `auth.roles` or `auth.permissions` contain none of these strings have the field stripped from every response (getOne, getMany, query, and the results of create/update/upsert). Applied at the response boundary — no extra DB round-trips.
+  - `writeRoles: string[]` — callers lacking a matching role have the field silently dropped from write bodies (same effect as `writable: false` for that caller). Callers with a matching role can write the field normally.
+  - Roles are matched against both `auth.roles` and `auth.permissions` for consistency with `requiredPermissions`.
+  - See [README_AUTH.md](./README_AUTH.md) for usage.
+
 ## [2.1.0]
 
 ### Added
@@ -124,5 +186,6 @@ First public release.
 - **Auth & field-level security** — API key, JWT/Bearer, and Passport strategies; per-action
   required permissions; and `filterable`/`sortable`/`selectable`/`writable` field flags.
 
+[2.2.0]: https://github.com/splayfee/halifax/releases/tag/v2.2.0
+[2.1.0]: https://github.com/splayfee/halifax/releases/tag/v2.1.0
 [2.0.0]: https://github.com/splayfee/halifax/releases/tag/v2.0.0
-[1.0.0]: https://github.com/splayfee/halifax/releases/tag/v1.0.0

package/README.md

@@ -14,21 +14,25 @@ The package is split into small, replaceable layers — nothing is imported into
 - 🚀 **Zero-boilerplate CRUD** — define a resource once and get standards-compliant REST endpoints (list, read, create, update, upsert, delete, bulk) with correct status codes and a consistent error shape.
 - 🧩 **Adapter-driven & swappable** — your HTTP framework, ORM/database, and auth provider are injected, not baked in. Switch any layer without touching your resource definitions.
 - 🌐 **4 HTTP frameworks, identical behavior** — Express 4/5, Fastify, HyperExpress, and Ultimate Express, all verified against one shared conformance suite.
-- 🗄️ **Six databases, one adapter** — PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, and SQLite via [Prisma](https://www.prisma.io/). The query builder compiles to portable Prisma calls (never raw SQL), so the **same client request behaves identically on every database** — switch engines by changing one line. Every engine is verified in CI against a real database — one matrix leg each, the same suite on all.
+- 🗄️ **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.
 - ⚡ **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; and `filterable`/`sortable`/`selectable`/`writable` flags enforced on every request.
+- 🔐 **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.
+- 🪝 **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.
 
 ## Current Support
 
-| Layer          | Supported                                                                 |
-| -------------- | ------------------------------------------------------------------------- |
-| HTTP server    | Express 4/5, Fastify, HyperExpress, Ultimate Express                      |
-| ORM / database | Prisma 6 or 7 + Postgres, MySQL, MariaDB, SQL Server, CockroachDB, SQLite |
-| Auth           | API key, JWT/Bearer, Passport + JWT                                       |
-| Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)       |
+| Layer          | Supported                                                                                                            |
+| -------------- | -------------------------------------------------------------------------------------------------------------------- |
+| 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`                                              |
+| Caching        | Pluggable read-through cache (in-memory default; bring Redis, etc.)                                                  |
+| API docs       | OpenAPI 3.1 spec + Swagger UI (optional, zero overhead when disabled)                                                |
 
 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
@@ -52,6 +56,81 @@ CockroachDB, and SQLite — in CI (one matrix leg per engine) to keep that hones
 >
 > **Roadmap** — community-written adapters for Drizzle, Sequelize, etc. are also welcome.
 
+## Monorepo packages
+
+Halifax ships as two packages from the same repository:
+
+| Package                                                                        | Description                                                                 |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
+| [`@edium/halifax`](https://www.npmjs.com/package/@edium/halifax)               | Server — auto-CRUD engine, adapters, auth, caching, OpenAPI                 |
+| [`@edium/halifax-client`](https://www.npmjs.com/package/@edium/halifax-client) | Browser/Node client — typed CRUD, query builder, TanStack Query integration |
+
+## Browser Client — React & Vue
+
+[`@edium/halifax-client`](https://www.npmjs.com/package/@edium/halifax-client) is the companion
+frontend package. It ships a fully-typed resource client, a fluent query builder, and **built-in
+TanStack Query option factories** so list/detail queries and mutations wire up in a few lines —
+with automatic cache invalidation on writes.
+
+```bash
+pnpm add @edium/halifax-client
+
+# add whichever TanStack Query adapter your framework uses
+pnpm add @tanstack/react-query   # React
+pnpm add @tanstack/vue-query     # Vue
+```
+
+**React**
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { HalifaxClient } from '@edium/halifax-client'
+
+const client = new HalifaxClient({ baseUrl: '/api/v1' })
+const posts = client.resource<Post, NewPost, PatchPost>('posts')
+
+// Paginated list — queryKey is managed for you
+function usePostList(page: number) {
+  return useQuery(posts.getManyOptions({ limit: 20, offset: page * 20 }))
+}
+
+// Create with automatic list invalidation
+function useCreatePost() {
+  const qc = useQueryClient()
+  return useMutation({
+    ...posts.createOneMutation(),
+    onSuccess: () => qc.invalidateQueries({ queryKey: posts.queryKey() })
+  })
+}
+```
+
+**Vue**
+
+```ts
+import { computed, ref } from 'vue'
+import { useQuery, useMutation, useQueryClient } from '@tanstack/vue-query'
+import { HalifaxClient } from '@edium/halifax-client'
+
+const client = new HalifaxClient({ baseUrl: '/api/v1' })
+const posts = client.resource<Post, NewPost, PatchPost>('posts')
+
+// Reactive query — re-fetches automatically when page changes
+const page = ref(0)
+const postList = useQuery(computed(() => posts.getManyOptions({ limit: 20, offset: page.value * 20 })))
+
+// Mutation with cache invalidation
+const qc = useQueryClient()
+const createPost = useMutation({
+  ...posts.createOneMutation(),
+  onSuccess: () => qc.invalidateQueries({ queryKey: posts.queryKey() })
+})
+```
+
+Five HTTP transports are included out of the box: `fetch` (default), `axios`, `ky`, `ofetch`, and
+`superagent` — swap with one line. Full docs: [README_CLIENT.md](./README_CLIENT.md).
+
+---
+
 ## Install
 
 ```bash
@@ -107,15 +186,21 @@ app.listen(3000)
 
 ## Documentation
 
-| Guide                                                | Contents                                                                                      |
-| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| [README_AUTOCRUD.md](./README_AUTOCRUD.md)           | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes |
-| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 (and 6) setup, `PrismaAdapter` options, capabilities, custom repositories            |
-| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters          |
-| [README_AUTH.md](./README_AUTH.md)                   | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, custom `authorize`      |
-| [README_MULTITENANCY.md](./README_MULTITENANCY.md)   | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour |
-| [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)   | Query-builder payload, comparisons, nested filters, portable Prisma execution                 |
-| [README_CACHE.md](./README_CACHE.md)                 | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header               |
+| Guide                                                | Contents                                                                                                 |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [README_CLIENT.md](./README_CLIENT.md)               | `@edium/halifax-client` — install, transports, query builder, React & Vue TanStack Query examples       |
+| [README_AUTOCRUD.md](./README_AUTOCRUD.md)           | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes            |
+| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 (and 6) setup, `PrismaAdapter`, `DrizzleAdapter`, capabilities, custom repositories             |
+| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters                     |
+| [README_AUTH.md](./README_AUTH.md)                   | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, per-field `readRoles`/`writeRoles` |
+| [README_MULTITENANCY.md](./README_MULTITENANCY.md)   | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour            |
+| [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_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            |
+| [README_CLASSES.md](./README_CLASSES.md)             | All exported classes — auth strategies, HTTP adapters, ORM adapters, cache stores, error types           |
 
 ## Examples
 

package/README_AUTH.md

@@ -125,6 +125,44 @@ export const authStrategy = new PassportJwtStrategy({
 })
 ```
 
+## Per-Field Role-Based Access Control
+
+`FieldDefinition` supports two optional arrays for column-level visibility:
+
+```ts
+const postResource: ResourceDefinition = {
+  routePrefix: 'posts',
+  repository: new PrismaAdapter({ delegate: prisma.post }),
+  fields: [
+    { name: 'id' },
+    { name: 'title' },
+    { name: 'content' },
+    // Only users with role 'editor' or 'admin' can read or write the `status` field.
+    { name: 'status', readRoles: ['editor', 'admin'], writeRoles: ['editor', 'admin'] },
+    // Any authenticated user can read `authorId`, but only admins can set it.
+    { name: 'authorId', writeRoles: ['admin'] },
+    // `internalNote` is invisible to everyone except admins.
+    { name: 'internalNote', readRoles: ['admin'], writeRoles: ['admin'] }
+  ]
+}
+```
+
+### `readRoles`
+
+When a field has `readRoles`, it is **stripped from every response** for any caller whose `auth.roles` and `auth.permissions` contain none of the listed values. This applies uniformly across `getOne`, `getMany`, `query`, and the records returned by `createOne`, `updateOne`, and `upsertOne` — no extra configuration per operation. The field is never sent to the database `SELECT`; it is removed at the response boundary after the auth context is resolved.
+
+### `writeRoles`
+
+When a field has `writeRoles`, callers without a matching role have the field **silently dropped** from write bodies before the repository sees them. The effect is identical to `writable: false` for that caller. Callers with a matching role can write the field normally.
+
+### Role matching
+
+Both `readRoles` and `writeRoles` are matched against both `auth.roles` and `auth.permissions` — a caller needs at least one match in either array. This is consistent with how `requiredPermissions` works.
+
+### Primary key note
+
+The primary key is protected by `writable: false` by default regardless of `writeRoles`. Setting `writeRoles` on the primary key has no additional effect.
+
 ## Per-Action Permission Requirements
 
 `requiredPermissions` on a resource maps each CRUD action to a list of roles or permission strings. The authenticated user must possess at least one entry from the list (matched against both `auth.roles` and `auth.permissions`).

package/README_AUTOCRUD.md

@@ -158,11 +158,11 @@ createExpressCrudRouter(resources, { authStrategy, envelope: 'data' })
 
 The wrap is **uniform** — it nests the entire body, it does not reshape it:
 
-| Endpoint        | Bare (default)            | `envelope: 'data'`                    |
-| --------------- | ------------------------- | ------------------------------------- |
-| List / query    | `{ count, results }`      | `{ data: { count, results } }`        |
-| Read / create   | `{ id, ... }`             | `{ data: { id, ... } }`               |
-| Delete one      | `{ deleted: true }`       | `{ data: { deleted: true } }`         |
+| Endpoint      | Bare (default)       | `envelope: 'data'`             |
+| ------------- | -------------------- | ------------------------------ |
+| List / query  | `{ count, results }` | `{ data: { count, results } }` |
+| Read / create | `{ id, ... }`        | `{ data: { id, ... } }`        |
+| Delete one    | `{ deleted: true }`  | `{ data: { deleted: true } }`  |
 
 Notes:
 

package/README_CLASSES.md

@@ -0,0 +1,322 @@
+# Classes — `@edium/halifax`
+
+All publicly exported TypeScript classes. Type aliases are in [README_TYPES.md](./README_TYPES.md); interfaces are in [README_INTERFACES.md](./README_INTERFACES.md).
+
+---
+
+## Auth strategies
+
+All auth strategy classes implement `AuthStrategy`. Pass an instance to `CrudApiOptions.authStrategy`.
+
+### `AllowAllAuthStrategy`
+
+Import: `@edium/halifax`
+
+Passes every request through without any authentication check. Returns `{ isAuthenticated: true }` for every caller. Suitable for public APIs or local development only.
+
+```ts
+import { AllowAllAuthStrategy } from '@edium/halifax'
+createExpressCrudRouter(resources, { authStrategy: new AllowAllAuthStrategy() })
+```
+
+---
+
+### `ApiKeyAuthStrategy`
+
+Import: `@edium/halifax`
+
+Reads a request header and compares it against a static shared secret.
+
+```ts
+new ApiKeyAuthStrategy(expectedApiKey: string, headerName?: string)
+```
+
+| Parameter        | Default       | Description                         |
+| ---------------- | ------------- | ----------------------------------- |
+| `expectedApiKey` | required      | The secret key callers must supply. |
+| `headerName`     | `'x-api-key'` | Header to read the key from.        |
+
+- Missing header → 401 Unauthorized
+- Wrong key → 403 Forbidden
+- OpenAPI: documents `apiKey` in header (uses the configured `headerName`).
+
+---
+
+### `JwtClaimsAuthStrategy`
+
+Import: `@edium/halifax`
+
+Extracts a Bearer token from the `Authorization` header and passes it to your verify callback. No Passport dependency — use this for any JWT library (`jsonwebtoken`, `jose`, etc.).
+
+```ts
+new JwtClaimsAuthStrategy(
+  verifyToken: (token: string, req: HttpRequest) => AuthContext | Promise<AuthContext>
+)
+```
+
+The verify callback receives the raw token string and must return an `AuthContext`. Throw any error to reject (→ 401). The built-in `authorize` checks `requiredPermissions` against `auth.roles` and `auth.permissions`.
+
+OpenAPI: documents `http` bearer JWT.
+
+---
+
+### `PassportJwtStrategy`
+
+Import: `@edium/halifax`
+
+Delegates JWT verification to a Passport strategy already registered on your Passport instance. Use when you have an existing `passport-jwt` setup.
+
+```ts
+new PassportJwtStrategy(options: PassportJwtStrategyOptions)
+```
+
+See `PassportJwtStrategyOptions` in [README_INTERFACES.md](./README_INTERFACES.md). The built-in `authorize` checks `requiredPermissions` against `auth.roles` and `auth.permissions`.
+
+OpenAPI: documents `http` bearer JWT.
+
+---
+
+### `PassportSessionStrategy`
+
+Import: `@edium/halifax`
+
+Authenticates using Passport session cookies. Reads `req.raw.user` (populated by Passport's session middleware running before Halifax).
+
+```ts
+new PassportSessionStrategy(mapUser?: (user: unknown) => AuthContext)
+```
+
+| Parameter | Description                                                                                                                     |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `mapUser` | Optional function to map the raw session user object to an `AuthContext`. Default reads `sub`/`id`, `roles`, and `permissions`. |
+
+**Prerequisites** — add before mounting Halifax:
+
+```ts
+app.use(session({ secret: '...' }))
+app.use(passport.initialize())
+app.use(passport.session())
+```
+
+Missing `req.user` (session expired or not logged in) → 401.
+
+OpenAPI: documents `apiKey` in cookie (`connect.sid`).
+
+---
+
+### `PassportAuthStrategy`
+
+Import: `@edium/halifax`
+
+Generic Passport wrapper. Takes a function that calls your Passport strategy and returns an `AuthContext`. Use when neither `PassportJwtStrategy` nor `PassportSessionStrategy` fits.
+
+```ts
+new PassportAuthStrategy(
+  authenticateWithPassport: (req: HttpRequest) => AuthContext | Promise<AuthContext>
+)
+```
+
+---
+
+### `Auth0JwtStrategy`
+
+Import: `@edium/halifax`
+
+Alias of `JwtClaimsAuthStrategy`. Identical in every way — the name signals intent when your tokens come from Auth0.
+
+```ts
+new Auth0JwtStrategy(verifyToken)
+```
+
+---
+
+### `FirebaseJwtStrategy`
+
+Import: `@edium/halifax`
+
+Alias of `JwtClaimsAuthStrategy`. Identical in every way — the name signals intent when your tokens are Firebase ID tokens.
+
+```ts
+new FirebaseJwtStrategy(verifyToken)
+```
+
+---
+
+## HTTP server adapters
+
+Each adapter wraps a framework app instance and implements `HttpServer`. Pass to `registerCrudApi`, or use the corresponding `create*CrudRouter` / `create*CrudPlugin` helper instead.
+
+### `ExpressHttpServer`
+
+Import: `@edium/halifax`
+
+Wraps an Express (4 or 5) `Application` or `Router`. Used internally by `createExpressCrudRouter`.
+
+```ts
+new ExpressHttpServer(app: ExpressAppLike)
+```
+
+---
+
+### `FastifyHttpServer`
+
+Import: `@edium/halifax`
+
+Wraps a Fastify instance. Used internally by `createFastifyCrudPlugin`.
+
+```ts
+new FastifyHttpServer(app: FastifyAppLike)
+```
+
+---
+
+### `HyperExpressHttpServer`
+
+Import: `@edium/halifax`
+
+Wraps a HyperExpress `Server` instance. Used internally by `createHyperExpressCrudRouter`.
+
+```ts
+new HyperExpressHttpServer(app: HyperExpressAppLike)
+```
+
+---
+
+### `UltimateExpressHttpServer`
+
+Import: `@edium/halifax`
+
+Wraps an Ultimate Express `App` instance. Used internally by `createUltimateExpressCrudRouter`.
+
+```ts
+new UltimateExpressHttpServer(app: UltimateExpressAppLike)
+```
+
+---
+
+## Repository adapters
+
+### `PrismaAdapter<TRecord, TCreate, TUpdate>`
+
+Import: `@edium/halifax`
+
+Implements the full `Repository` interface against any Prisma-supported database. Supports all nine CRUD operations, the query-builder endpoint, multi-tenant scoping (`withScope`), and relation eager-loading (`?include=`). Field schema and OpenAPI types are auto-derived from the Prisma DMMF when a `model` is provided.
+
+```ts
+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).
+
+**Capabilities reported:**
+
+- `supportsIncludes: true`
+- `supportsCreateManyReturn: <returnCreated option>`
+
+---
+
+### `DrizzleAdapter<TRecord, TCreate, TUpdate>`
+
+Import: `@edium/halifax/drizzle`
+
+Implements the full `Repository` interface against any Drizzle-compatible database (PostgreSQL, MySQL, SQLite, LibSQL). Field schema and OpenAPI types are auto-derived from the Drizzle table definition via `getTableColumns()`. Supports the query-builder endpoint (`executeQuery`), multi-tenant scoping (`withScope`), and field projection. `drizzle-orm` is a required peer dependency when this adapter is used.
+
+```ts
+import { DrizzleAdapter } from '@edium/halifax/drizzle'
+
+new DrizzleAdapter<TRecord, TCreate, TUpdate>(
+  db: AnyDrizzleDB,
+  table: Table,
+  config?: DrizzleAdapterConfig,
+  scope?: TenantScope | null
+)
+```
+
+See `DrizzleAdapterConfig` in [README_INTERFACES.md](./README_INTERFACES.md).
+
+**Static method:**
+
+```ts
+DrizzleAdapter.fieldsFromTable(table: Table, idField?: string): FieldDefinition[]
+```
+
+Derives a Halifax field schema from a Drizzle table without constructing a full adapter instance. Useful for inspecting or overriding the derived fields before passing them to a `ResourceDefinition`.
+
+---
+
+## Cache stores
+
+Both implement `CacheStore`. Pass to `CrudApiOptions.cache.store`.
+
+### `InMemoryCacheStore`
+
+Import: `@edium/halifax`
+
+Process-local in-memory cache. The default when no `store` is configured. Simple and zero-dependency, but does not persist across restarts and is not shared across processes or instances.
+
+```ts
+new InMemoryCacheStore()
+```
+
+---
+
+### `RedisCacheStore`
+
+Import: `@edium/halifax`
+
+Redis-backed distributed cache store. Accepts any Redis client satisfying `RedisLikeClient` — `redis` v4 works directly.
+
+```ts
+new RedisCacheStore(client: RedisLikeClient)
+```
+
+```ts
+import { createClient } from 'redis'
+import { RedisCacheStore } from '@edium/halifax'
+
+const redis = createClient({ url: process.env.REDIS_URL })
+await redis.connect()
+
+createExpressCrudRouter(resources, {
+  cache: { store: new RedisCacheStore(redis), ttlSeconds: 60 }
+})
+```
+
+---
+
+## Error classes
+
+All error classes extend `HttpError`. Throw these inside a custom `AuthStrategy` or `Repository` to return the corresponding HTTP status with a structured `{ errors: [...] }` body. Halifax catches `HttpError` subclasses at the route boundary and serializes them automatically.
+
+### `HttpError` (abstract)
+
+Import: `@edium/halifax`
+
+Base class for all Halifax HTTP errors. Not instantiated directly.
+
+| Property  | Type      | Description                                             |
+| --------- | --------- | ------------------------------------------------------- |
+| `status`  | `number`  | HTTP status code.                                       |
+| `message` | `string`  | Human-readable error message.                           |
+| `details` | `unknown` | Optional structured details included in the error body. |
+
+---
+
+### Error subclasses
+
+| Class                       | Status | When to throw                                                                                                  |
+| --------------------------- | ------ | -------------------------------------------------------------------------------------------------------------- |
+| `AuthenticationError`       | 401    | Missing or invalid credentials. Throw from `AuthStrategy.authenticate`.                                        |
+| `AuthorizationError`        | 403    | Valid credentials but insufficient permissions. Throw from `AuthStrategy.authenticate` or `authorize`.         |
+| `BadRequestError`           | 400    | Malformed input — invalid ID format, bad query params, bad body structure.                                     |
+| `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.                                |
+| `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).                                 |
+| `ServerError`               | 500    | Unexpected internal error. Halifax uses this as a catch-all; throw it from a custom adapter for explicit 500s. |
+
+All constructors accept `(message: string, details?: unknown)`.