@aventara/nest 1.0.0-rc.0 → 1.0.0-rc.10

package/CHANGELOG.md

@@ -1,5 +1,314 @@
 # @aventara/nest
 
+## 1.0.0-rc.10
+
+### Patch Changes
+
+- 04bb39a: `engines.node` is now `^22.23.4 || >=24.22.1`, the Node security releases of 2026-10-20 (CVE-2026-105481,
+  CVE-2026-105482, CVE-2026-105483, CVE-2026-106069, CVE-2026-106072, CVE-2026-106073, CVE-2026-106074,
+  CVE-2026-111497). The bins refuse an older Node in one sentence naming that range.
+- 587dd01: `AventaraModule` mounts `POST {api}/_access/can` on Express and Fastify when the Framework is built with `access`,
+  answered by `AvProtocol.bind(framework).handleCan` with the request's state seeded as on every other protocol route. The internal-failure log line names a `can`
+  request's failure by its question (`A3000 on access question 2 (orders update) …`) or as `the access questions`.
+- Updated dependencies [587dd01]
+- Updated dependencies [d7e7369]
+- Updated dependencies [7ee547b]
+- Updated dependencies [f52c499]
+- Updated dependencies [2907484]
+- Updated dependencies [a6bbdf0]
+- Updated dependencies [3e26549]
+- Updated dependencies [a6bbdf0]
+- Updated dependencies [6f3f6f6]
+- Updated dependencies [04bb39a]
+- Updated dependencies [d7e7369]
+- Updated dependencies [3fb3333]
+- Updated dependencies [827ccb6]
+- Updated dependencies [7f5abc3]
+- Updated dependencies [88263a1]
+- Updated dependencies [10341d5]
+- Updated dependencies [8129844]
+- Updated dependencies [88263a1]
+- Updated dependencies [3020b5c]
+- Updated dependencies [88263a1]
+- Updated dependencies [88263a1]
+  - @aventara/core@1.0.0-rc.10
+  - @aventara/mcp@1.0.0-rc.10
+
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- 8c40b81: `@aventara/nest` declares a NestJS project's layout in its manifest (`"aventara": { "host": … }`).
+  `aventara new` and `aventara init`, which now also scaffold Next.js apps, and `aventara-build` read a NestJS project's
+  paths from it, so the three always agree. A NestJS project is scaffolded exactly as before.
+- 205a379: `AventaraModule` hosts a Framework built with `access` (an access provider, from `@aventara/core`): each protocol
+  request's `ctx.$state` is seeded by the provider's `state`, called with `{ headers, request }`, the platform
+  request's headers as `Headers` and Express's `req` or Fastify's `request`. It works the same through `config`
+  (`forRoot({ config: { ...config, access } })`) and `framework`. The module's own `state` option beside `access` is
+  refused while Nest builds the application, and is a type error on a `config` that states `access`.
+- Updated dependencies [205a379]
+- Updated dependencies [a0bb05e]
+- Updated dependencies [86ab319]
+- Updated dependencies [fdf52e6]
+  - @aventara/core@1.0.0-rc.9
+  - @aventara/mcp@1.0.0-rc.9
+
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [1c8e4ee]
+  - @aventara/core@1.0.0-rc.8
+  - @aventara/mcp@1.0.0-rc.8
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+### Patch Changes
+
+- Updated dependencies [f917c1c]
+  - @aventara/core@1.0.0-rc.7
+  - @aventara/mcp@1.0.0-rc.7
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+### Patch Changes
+
+- Updated dependencies [1cf72e0]
+  - @aventara/core@1.0.0-rc.6
+  - @aventara/mcp@1.0.0-rc.6
+
+## 1.0.0-rc.5
+
+### Patch Changes
+
+- Updated dependencies [4795ff1]
+- Updated dependencies [9e178ca]
+  - @aventara/core@1.0.0-rc.5
+  - @aventara/mcp@1.0.0-rc.5
+
+## 1.0.0-rc.4
+
+### Patch Changes
+
+- Updated dependencies [e3d03a7]
+- Updated dependencies [d10639a]
+- Updated dependencies [f67e68c]
+- Updated dependencies [708556c]
+- Updated dependencies [3a0dfca]
+- Updated dependencies [99169d2]
+- Updated dependencies [0fd2608]
+- Updated dependencies [154e440]
+- Updated dependencies [2fcffdb]
+  - @aventara/core@1.0.0-rc.4
+  - @aventara/mcp@1.0.0-rc.4
+
+## 1.0.0-rc.3
+
+### Patch Changes
+
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+- Updated dependencies [b38034d]
+  - @aventara/core@1.0.0-rc.3
+  - @aventara/mcp@1.0.0-rc.3
+
+## 1.0.0-rc.2
+
+### Patch Changes
+
+- `AventaraModule.forRoot({ config })` reports a Pick layer that names what its parent hid with the sentence first, as
+  `createFramework` does: an inline `client: { exposed: false, exemptions: { resources: { Comment: true } } }` whose
+  root hid `Comment` fails at the key with
+  `Type 'true' is not assignable to type 'true & (readonly ["Error: client cannot expose 'Comment': hidden by root"] & …)'`.
+- 9366e16: MCP endpoint polish:
+
+  - A request with no bearer credentials (no `Authorization` header, or another scheme such as `Basic`) is answered
+    `401` with `WWW-Authenticate: Bearer resource_metadata="…"` and no error code, as RFC 6750 §3.1 asks; its body no
+    longer says "Missing Authorization header". A bad bearer token keeps `error="invalid_token"`.
+  - A `mcp.authorization.verify` that throws is still answered `401`, and is now reported to the `diagnostics` sink as
+    an `AvMcpDiagnostic` holding the error.
+  - With `mcp` configured and `@aventara/mcp` missing, the startup error names the command that installs it at the
+    installed `@aventara/core`'s exact version: `npm install --save-exact @aventara/mcp@<version>`.
+
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+- Updated dependencies [9366e16]
+  - @aventara/core@1.0.0-rc.2
+  - @aventara/mcp@1.0.0-rc.2
+
+## 1.0.0-rc.1
+
+### Patch Changes
+
+- 7e3d06f: Breaking: the configuration has a new shape. Every layer (the root, `application` and `client`) now holds the
+  same six keys: `exposed`, `transactionsStyle`, `limits`, `pipelines`, `resources` and `exemptions`. Everything about
+  one Resource lives under `resources.<Resource>`: its fields, and each field's `definition` and `pipelines`. The old
+  keys are refused when the framework starts, with a message that names where each one moved:
+
+  | Before (rc.0)                                           | Now (rc.1)                                                                          |
+  | ------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+  | `fields: { Post: { url: { type, nullable, … } } }`      | `resources: { Post: { fields: { url: { definition: { type, nullable, … } } } } }`   |
+  | `behaviors: { Post: { fields: { slug: { create } } } }` | `resources: { Post: { fields: { slug: { pipelines: { compute: { create } } } } } }` |
+  | `transactions: "none"`                                  | `transactionsStyle: "none"`                                                         |
+  | `restrictions`                                          | `exposed` + `exemptions` (see below)                                                |
+  | `@aventara/core/json`                                   | `@aventara/core/avz`                                                                |
+
+  Before:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactions: "interactive",
+    fields: {
+      Post: {
+        url: {
+          type: { scalar: "string" },
+          nullable: false,
+          list: false,
+          lifecycle: ["VIRTUAL"],
+        },
+      },
+    },
+    behaviors: {
+      Post: {
+        fields: {
+          url: {
+            read: {
+              dependsOn: ["slug"],
+              compute: ({ record }) => `/p/${record.slug}`,
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  After:
+
+  ```ts
+  createFramework({
+    api: "/api",
+    adapter,
+    transactionsStyle: "interactive",
+    resources: {
+      Post: {
+        fields: {
+          url: {
+            definition: {
+              type: { scalar: "string" },
+              nullable: false,
+              list: false,
+              lifecycle: ["VIRTUAL"],
+            },
+            pipelines: {
+              compute: {
+                read: {
+                  dependsOn: ["slug"],
+                  compute: ({ record }) => `/p/${record.slug}`,
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  });
+  ```
+
+  What else changed:
+
+  - A field is defined at the root only. A `definition` in `application` or `client` is refused
+    (`CONFIG_FORBIDDEN_IN_OVERLAY`). Define the field
+    at the root; `application` and `client` can still add compute stages to it.
+  - Computed values chain. When the root and an overlay both compute a field, the root's stage runs first and the
+    overlay's receives its result as `value`. A stage can no longer be turned off with `false`. Returning `undefined`
+    keeps the current value. An upsert computes its create branch with `compute.create` and its update branch with
+    `compute.update`.
+  - A discovered field keeps the adapter's facts. On a field the adapter discovered you may restate its own `type`,
+    `nullable` and `list`, and give a Json field its shape (`definition.json`). Setting a different type, any `format`
+    or any `capabilities` on it is refused. `format` is for fields you add, and it must be one of zod's named string
+    formats (`"email"`, `"url"`, `"uuid"`, …); any other name is a type error and refused at startup.
+  - A misplaced key is a type error. In a configuration written inline in `createFramework({ ... })` or
+    `AventaraModule.forRoot`, a key that has no place there (a typo, an old key, `compute` on a relation field, a field
+    name neither your schema nor the root has) is now a type error at that key, and still refused at startup.
+  - A Resource whose name starts with `$` is refused at startup (`$` names are the framework's).
+  - The Json shape builder moved from `@aventara/core/json` to `@aventara/core/avz`. Change the import; `AvZ` is
+    the same.
+
+  `exposed` and `exemptions`, which replace `restrictions`, have their own entry.
+
+- 4907afc: New: `AventaraModule.forRoot` and `forRootAsync` take a `state` option that seeds each protocol request's
+  `ctx.$state` (see `@aventara/core`'s changelog). It is called once per request with the platform's own request, so
+  what your middleware set there reaches every guard, pipe, hook and interceptor of the request:
+
+  ```ts
+  AventaraModule.forRoot({
+    config,
+    state: (req: Request) => ({ user: req.user }), // Passport's req.user, on Express
+  });
+  ```
+
+  On Express the request is Express's `req`. On Fastify it is Fastify's `request`; middleware added with `app.use`
+  writes to its Node request, `request.raw`, so read `request.raw.user` there. Fastify answers a protocol route in its
+  `onRequest` hook, so only what runs before that (`app.use` middleware, an earlier `onRequest` hook) can be read. A
+  `state` function that throws an `AvError` answers that error (`AvError("A4001", …)` is a `403`); any other throw is
+  `500 A3000`. A request the protocol refuses before running (a stale client, an unknown route) never calls it. A
+  `state` that is not a function is refused while Nest builds the application.
+
+- Breaking: the configuration's mount path is `api` (it was `entrypoint`), and the module reads `framework.api`.
+  `forRoot({ config: { api: "/api", adapter } })`. The Fastify refusal of a path with `*` now says "Change `api`, or
+  host on Express."
+
+- New: with `mcp` in the configuration, the module mounts the MCP endpoint of `@aventara/mcp` at that path (and, with
+  `mcp.authorization`, its OAuth metadata at `/.well-known/oauth-protected-resource` plus the path), on Express and on
+  Fastify, as it mounts the protocol's routes: the body read raw, the request's URL and peer address handed over, the
+  answer written as it is. The `state` option seeds each tool call's `ctx.$state`. `@aventara/mcp` is an optional peer
+  dependency, loaded only when `mcp` is configured; with `mcp` set and the package missing, the application refuses to
+  start and names it.
+
+- Fixed on Express: a request whose path matched a mounted route only because Express ignores case reached the route
+  without its body, and was answered as if it had sent none. Express matches routes case-insensitively by default,
+  while the body reader compared the path exactly. The MCP routes now answer their own path only, exactly as written,
+  so `/MCP` or `/mcp/` goes on to Nest's `404`, as on Fastify. The protocol's routes keep Express's matching (it also
+  answers the protocol under `/API` for `api: "/api"`), and the body reader now matches the `api` path the same way, so
+  `POST /API/_resources/…` gets its body.
+
+- The host's log line for an internal failure names the MCP endpoint when the endpoint itself failed
+  (`A3000 on the MCP endpoint (agent origin, request …)`).
+
+- Updated dependencies [800123b]
+- Updated dependencies [8bb1d6a]
+- Updated dependencies [68d4395]
+- Updated dependencies [7e3d06f]
+- Updated dependencies [1b5d3c0]
+- Updated dependencies [6317811]
+- Updated dependencies [6d0e5d6]
+- Updated dependencies [7a0cab9]
+- Updated dependencies [eb2a718]
+- Updated dependencies [03312c5]
+- Updated dependencies [123f6dc]
+- Updated dependencies [b65df2e]
+- Updated dependencies [c6e5010]
+- Updated dependencies [c1f9389]
+- Updated dependencies [9c52482]
+- Updated dependencies [8396148]
+- Updated dependencies [e8fbb02]
+- Updated dependencies [916e5f6]
+- Updated dependencies [6cbd158]
+  - @aventara/core@1.0.0-rc.1
+
 ## 1.0.0-rc.0
 
 ### Major Changes

package/README.md

@@ -1,16 +1,16 @@
 # `@aventara/nest`
 
-Hosts an Aventara `Framework` in a NestJS application. It does one thing: it mounts the framework's HTTP protocol —
-`AvProtocol.bind(framework)` from `@aventara/core/protocol` — on Nest's HTTP platform, and puts the `Framework` into
+Hosts an Aventara `AvFramework` in a NestJS application. It mounts the framework's HTTP protocol
+(`AvProtocol.bind(framework)` from `@aventara/core/protocol`) on Nest's HTTP platform, and puts the `AvFramework` into
 Nest's dependency injection. Every rule of the protocol (routes, decoding, statuses, envelopes, headers, absence) is
 core's; this package only translates a Nest request into the protocol's request and writes the protocol's answer back.
 
-- **Nest 12** (`@nestjs/common` and `@nestjs/core` `^12.0.0`), on **Express** (Nest's default) or **Fastify**.
-- `@aventara/core` is its one dependency.
+It runs on Nest 12 (`@nestjs/common` and `@nestjs/core` `^12.0.0`), on Express (Nest's default) or Fastify.
+`@aventara/core` is its one dependency.
 
 ## Mounting it
 
-`AventaraModule` is a global module, imported once in your root module. It takes the `Framework` in one of four forms.
+`AventaraModule` is a global module, imported once in your root module. It takes the `AvFramework` in one of four forms.
 
 ```ts
 // src/app.module.ts — the shape `aventara init` writes (`@aventara/cli`)
@@ -33,14 +33,27 @@ import { PrismaModule, PrismaService } from "./prisma.service.js";
 })
 export class AppModule {}
 
-// src/aventara.config.ts — the framework's configuration: entrypoint, restrictions, pipelines
+// src/aventara.config.ts — the framework's configuration: api, exposure, pipelines, resources
+import type { AvDiagnostic } from "@aventara/core";
 import { createPrismaAdapter } from "@aventara/prisma7-adapter";
+import { Logger } from "@nestjs/common";
 import { discovery } from "./generated/aventara/discovery.artifact.js";
 import type { PrismaService } from "./prisma.service.js";
 
+const logger = new Logger("Aventara");
+
 export async function aventaraConfig(prisma: PrismaService) {
 	return {
-		entrypoint: "/api",
+		api: "/api",
+		exposed: true,
+		// The raw error of a server failure, with its stack, in Nest's log.
+		diagnostics: (diagnostic: AvDiagnostic) => {
+			const { error } = diagnostic;
+			logger.error(
+				`${diagnostic.code} (request ${diagnostic.requestId}): raw error`,
+				(error instanceof Error && error.stack) || String(error),
+			);
+		},
 		adapter: await createPrismaAdapter({
 			client: prisma,
 			discovery,
@@ -53,15 +66,18 @@ export async function aventaraConfig(prisma: PrismaService) {
 
 | Form | When |
 |---|---|
-| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `Framework<M, Cfg>` in code. |
+| `AventaraModule.forRoot({ framework })` | You called `createFramework(config)` yourself and want your own typed `AvFramework<M, Cfg>` in code. |
 | `AventaraModule.forRoot({ config })` | The module calls `createFramework(config)` for you. |
 | `AventaraModule.forRootAsync({ imports, inject, useFactory })` resolving `{ framework }` or `{ config }` | What builds the Framework (a Prisma client, a configuration service) is itself a provider. |
 
-The `config` form is typed exactly like `createFramework`'s parameter: an annotated `FrameworkConfig<M>`, an inline
+Each form also takes `state`, which seeds every protocol request's `ctx.$state` from the platform request (see
+*Request state*).
+
+The `config` form is typed exactly like `createFramework`'s parameter: an annotated `AvConfig<M>`, an inline
 literal, an inferred constant and a `satisfies` check are all accepted, and checked against your Adapter's model.
 
-**Injecting it.** `@InjectFramework()` (or `@Inject(AVENTARA_FRAMEWORK)`) injects the `Framework`. DI carries no type
-argument, so type the parameter with your own alias:
+`@InjectFramework()` (or `@Inject(AVENTARA_FRAMEWORK)`) injects the `AvFramework`. DI carries no type argument, so type
+the parameter with your own alias:
 
 ```ts
 export type AppFramework = Awaited<ReturnType<typeof buildFramework>>;
@@ -72,23 +88,23 @@ export class ReportsService {
 }
 ```
 
-**Fails before listen.** These reject while Nest builds the application, before it listens: both or neither of
-`framework` and `config`; a `framework` value that is not a Framework; the module mounted twice in one application; a
-platform other than Express or Fastify (or none, as in `createApplicationContext`); a `FrameworkConstructionError`,
-yours or the module's own, which propagates unchanged. Nest's default `abortOnError: true` **exits the process** on a
-bootstrap error instead of rejecting; pass `abortOnError: false` to `NestFactory.create` to catch it.
+These reject while Nest builds the application, before it listens: both or neither of `framework` and `config`; a
+`framework` value that is not a Framework; a `state` option that is not a function; the module mounted twice in one application; a platform other than Express
+or Fastify (or none, as in `createApplicationContext`); an `AvConstructionError`, yours or the module's own, which
+propagates unchanged. Nest's default `abortOnError: true` exits the process on a bootstrap error instead of rejecting;
+pass `abortOnError: false` to `NestFactory.create` to catch it.
 
-**Nest's testing module works.** `Test.createTestingModule({ imports: [AppModule] }).compile()` builds the providers
-before any HTTP platform exists; the module waits for the one `createNestApplication()` supplies, and still refuses an
-unsupported platform before the application listens. A testing module initialized with no
-application at all is refused at `init()`, as a platform of `none`.
+Nest's testing module works. `Test.createTestingModule({ imports: [AppModule] }).compile()` builds the providers before
+any HTTP platform exists; the module waits for the one `createNestApplication()` supplies, and still refuses an
+unsupported platform before the application listens. A testing module initialized with no application at all is
+refused at `init()`, as a platform of `none`.
 
-**Nothing to shut down.** The module owns no resource. Your Prisma provider closes its own client — in its
+The module owns no resource, so there is nothing to shut down. Your Prisma provider closes its own client in its
 `onModuleDestroy`, with `app.enableShutdownHooks()` for signals.
 
 ## Calling it by hand
 
-Against the shape `aventara init` writes — the entrypoint `/api`, a Prisma `User` model:
+Against the shape `aventara init` writes (the `api` mount path `/api`, a Prisma `User` model):
 
 <!-- pilot-gate:curl -->
 ```bash
@@ -108,18 +124,19 @@ curl -s -X POST http://localhost:3000/api/_resources/User/find/many \
 Leave out an identity header and the answer is `400 A2000`, naming the header that is missing. The hash changes
 whenever the schema or the configuration does: fetch it again, and regenerate the client.
 
-- **Resource keys are the model names, as written.** `model User` is `User` everywhere: on the wire
-  (`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
-  lower-cased or pluralized.
-- **Results are read-only.** A list result is a `readonly` array: type it `readonly User[]`, not `User[]` —
-  `const users: readonly User[] = await avClient.User.find.many({});`.
+Resource keys are the model names, as written. `model User` is `User` everywhere: on the wire
+(`/_resources/User/find/many`) and in the generated client (`avClient.User.find.many({})`). Nothing is renamed,
+lower-cased or pluralized.
+
+Results are read-only. A list result is a `readonly` array, so type it `readonly User[]`:
+`const users: readonly User[] = await avClient.User.find.many({});`.
 
 ## What runs on a protocol route
 
-The protocol's routes are platform routes, registered from the module's `configure()`, one per
-`protocol.surface()` entry — every advertised operation, `GET <entrypoint>/_contract`, and `POST
-<entrypoint>/_transactions` only when the ClientContract advertises `interactive` — plus the absence handler for the
-rest of `<entrypoint>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
+The protocol's routes are platform routes, registered from the module's `configure()`. There is one per
+`protocol.surface()` entry (every advertised operation, `GET <api>/_contract`, and `POST
+<api>/_transactions` only when the ClientContract advertises `interactive`), plus the absence handler for the
+rest of `<api>/_*`. Nest's `RouterExplorer` does not list platform routes, so the module logs one line of its
 own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `logger: false` silences it like any other):
 
 ```text
@@ -127,16 +144,19 @@ own when it mounts them, through Nest's `Logger` (context `AventaraModule`; `log
 ```
 
 An internal failure (`A3000`–`A3004`, answered as a 500) is logged as one error line through Nest's `Logger`
-(context `Aventara`): the code, the operation, the origin and the request id, and the thrown value's class name — never
-its message, which can hold SQL or a connection string. The raw error still goes to your `diagnostics` sink, when you
-configure one:
+(context `Aventara`): the code, the operation, the origin and the request id, and the thrown value's class name. It
+never logs the message, which can hold SQL or a connection string. The raw error still goes to your `diagnostics` sink, when you
+configure one. The `aventara.config.ts` that `aventara new` and `aventara init` write has one: it logs the raw error with its
+stack through the same `Logger`, at error level, right after this line.
 
 ```text
 [Nest] ERROR [Aventara] A3001 on Post.create.one (client origin, request 3f1c…): PrismaClientValidationError. The raw error goes to the framework's diagnostics sink.
+[Nest] ERROR [Aventara] A3001 (request 3f1c…): raw error
+PrismaClientValidationError: …
 ```
 
-For `A3004` — one of your pipes returned arguments the server contract refuses — the line also names the pipe, the
-operation, the offending field and its V-code; the caller only ever sees the generic message.
+For `A3004` (one of your pipes returned arguments the server contract refuses), the line also names the pipe, the
+operation, the offending field and its V-code. The caller only ever sees the generic message.
 
 The line is added when the module builds the framework from `config`; a framework you build yourself and pass as
 `framework` keeps exactly the `diagnostics` sink you gave it.
@@ -146,42 +166,107 @@ The framework's validation is outermost:
 | | Express | Fastify |
 |---|---|---|
 | Your `app.use(...)` middleware, `app.enableCors()`, helmet | runs | runs |
-| Nest guards, interceptors, pipes (global or not) | **never** | **never** |
-| `MiddlewareConsumer` middleware | **never** | **runs** — Fastify runs Nest middleware before routing; add `.exclude("api/_*path")` (your entrypoint) to keep it off |
-| Your controller at `<entrypoint>/_contract` (or any `_` path) | never reached | the application does not start |
-| Your controller at `<entrypoint>/health` (outside `_`) | reached | reached |
+| Nest guards, interceptors, pipes (global or not) | never | never |
+| `MiddlewareConsumer` middleware | never | runs, because Fastify runs Nest middleware before routing; add `.exclude("api/_*path")` (your `api` path) to keep it off |
+| Your controller at `<api>/_contract` (or any `_` path) | never reached | the application does not start |
+| Your controller at `<api>/health` (outside `_`) | reached | reached |
+
+Authorization therefore belongs in Aventara pipelines (guards). A guard reads the request's headers as
+`ctx.$transport.headers` (lower-cased names, repeats joined), and whatever your middleware found as `ctx.$state`,
+through the module's `state` option (next section).
+
+## Request state
+
+`state` seeds each protocol request's `ctx.$state`, the one object every stage of that request reads and writes. It is
+called once per request, with the platform's own request, after the protocol has accepted it (a stale client or an
+unknown route never calls it):
+
+```ts
+declare module "@aventara/core" {
+	interface AvState {
+		user?: { id: string; roles: string[] };
+	}
+}
+
+AventaraModule.forRoot({
+	config,
+	state: (req: Request) => ({ user: req.user }), // what your auth middleware set
+});
 
-Authentication and authorization therefore belong in Aventara **pipelines** (guards), which read
-`transport.headers` — lower-cased names, repeats joined. A Passport strategy run as Nest middleware sets `req.user`,
-which a pipeline cannot see: verify the bearer token or cookie in the Aventara guard instead.
+// In the configuration: a guard reads it.
+const signedIn: AvGuard = (ctx) => ctx.$state.user !== undefined;
+```
 
-**Where it is mounted.** `FrameworkConfig.entrypoint` alone decides it. `app.setGlobalPrefix(...)` does not move the
-protocol; set the entrypoint to where you want it, and point the generated client at the same URL.
+- `forRootAsync`'s `useFactory` returns `state` beside `framework` or `config`.
+- On Express, `req` is Express's request. On Fastify it is Fastify's `request`; `app.use` middleware writes to its
+  Node request, so read `request.raw.user`. Fastify answers a protocol route from its `onRequest` hook, so only what
+  runs before it (`app.use` middleware, an earlier `onRequest` hook) has run.
+- Use `app.use(...)` for the middleware that finds the user (a Passport `authenticate` call, a session or JWT check).
+  Nest guards never run on protocol routes, and `MiddlewareConsumer` middleware does not on Express (the table above).
+- A Framework built with `access` (an access provider, see `@aventara/core`) seeds the state itself: the module calls
+  the provider's `state` with `{ headers, request }`, the platform request's headers and the request. Pass no `state`
+  beside it; the module refuses the pair while Nest builds the application, and as a type error on a `config` that
+  states `access`. It works the same through `config` and `framework`:
+  `AventaraModule.forRoot({ config: { ...config, access } })`.
+- Throw `new AvError("A4001", "…")` from `state` to refuse the request (`403`); any other throw is `500 A3000`, with the
+  error in your `diagnostics` sink.
+- A plan sent to `/_transactions` gets one state for all its steps and transaction stages. A ctx call a stage makes
+  inherits it. Compute reads it but cannot write it.
+- Server code that calls the framework in process seeds it per call:
+  `framework.application.Post.create.one(args, { state: { user } })`.
+
+`AvConfig.api` alone decides where the protocol is mounted. `app.setGlobalPrefix(...)` does not move it; set
+`api` to where you want it, and point the generated client at the same URL.
 
 ## Requests
 
-- **Bodies** on protocol routes are read raw — never through Nest's body parser — up to `limits.maxRequestBytes`; the
+- Bodies on protocol routes are read raw, never through Nest's body parser, up to `limits.maxRequestBytes`. The
   protocol's decoder answers an oversized body (`413 A2010`), another content type (`415 A2011`) and malformed JSON
   (`400 A2000`). Your own routes keep Nest's parsed `req.body`. No `NestFactory.create` option is needed.
-- **`Content-Encoding`:** `gzip`, `deflate` and `br` are inflated, and the limit counts decoded bytes. Any other coding
+- For `Content-Encoding`, `gzip`, `deflate` and `br` are inflated, and the limit counts decoded bytes. Any other coding
   answers `415 A2011`; a body that does not decode in the coding it names answers `400 A2000`. These two answers carry a
   newly minted `Aventara-Request-Id`, not the client's.
-- **The request id** is the client's `Aventara-Request-Id` as it arrived, or one core mints. A middleware that rewrites
-  `req.headers` cannot change it, and `X-Request-Id` is never copied into it — set `Aventara-Request-Id` at your proxy.
-- **A query string** is not part of the protocol path; it is ignored.
+- The request id is the client's `Aventara-Request-Id` as it arrived, or one core mints. A middleware that rewrites
+  `req.headers` cannot change it, and `X-Request-Id` is never copied into it, so set `Aventara-Request-Id` at your
+  proxy.
+- A query string is not part of the protocol path; it is ignored.
+
+## The MCP endpoint
+
+With `mcp` in the configuration, the module also mounts the MCP server of `@aventara/mcp` at that path, on Express and
+Fastify alike, and logs `Aventara mounted the MCP endpoint at /mcp (…)`. Install it beside this package, at
+`@aventara/core`'s exact version:
+
+```bash
+npm install --save-exact @aventara/mcp@<your @aventara/core version>
+```
+
+It is an optional peer dependency: an application without `mcp` does not need it, and one with `mcp` and without the
+package refuses to start, naming it and the command, with the version filled in:
+
+```text
+AventaraModule: the configuration has `mcp`, and the package that serves it, @aventara/mcp, is not installed. Install it at @aventara/core's exact version (npm install --save-exact @aventara/mcp@1.0.0-rc.10), or remove `mcp` from the configuration.
+```
+ As for the protocol's routes, the module only mounts: the endpoint's body is read
+raw, the request's URL comes from the platform's `protocol` and `host` (set `trust proxy` on Express or `trustProxy` on
+Fastify behind a proxy), and every answer is `@aventara/mcp`'s. The `state` option seeds each tool call's `ctx.$state`.
+See `@aventara/mcp`'s README for the tools, the contract resource and authorization.
 
 ## Platform differences
 
-- **Fastify cannot mount some Resource keys or entrypoints as literal routes.** A Resource key that needs `*` or a
-  reserved character (`: + # $ & , / ; = ? @`) in its route path, or an entrypoint containing `*`, is refused at startup
+- Fastify cannot mount some Resource keys or `api` paths as literal routes. A Resource key that needs `*` or a
+  reserved character (`: + # $ & , / ; = ? @`) in its route path, or an `api` path containing `*`, is refused at startup
   with a message naming it. Rename it, or host on Express, which mounts every key.
-- **Express routing is case-insensitive** by default, so it also answers the protocol under, say, `/API/_contract`;
-  Fastify's is not. That is Express's own `case sensitive routing` setting, off by default, and yours to change.
-- **Express answers `500 A3000`** to a protocol route requested with a percent-encoding a generated client never sends
-  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. A known divergence.
+- Express routing is case-insensitive by default, so it also answers the protocol under, say, `/API/_contract`;
+  Fastify's is not. That is Express's own `case sensitive routing` setting, off by default, and yours to change. The
+  MCP endpoint is the exception: on both platforms it answers its own path only, exactly as written (`/mcp`, not
+  `/MCP` or `/mcp/`).
+- Express answers `500 A3000` to a protocol route requested with a percent-encoding a generated client never sends
+  (for example `%6Eotes` for `notes`); Fastify and the in-process protocol execute it. This is a known divergence.
 - On Express the response carries Express's `X-Powered-By` header; `app.disable("x-powered-by")` removes it.
 
 ## License
 
-PolyForm Shield 1.0.0 with an additional permission — free to use, including in commercial applications; you may not
-use it to build a product that competes with Aventara itself. See `LICENSE` and `LICENSE-ADDITIONAL-PERMISSION.md`.
+PolyForm Shield 1.0.0 with an additional permission. It is free to use, including in commercial applications, but you
+may not use it to build a product that competes with Aventara itself. See `LICENSE` and
+`LICENSE-ADDITIONAL-PERMISSION.md`.

package/dist/access-state.translator.d.ts

@@ -0,0 +1,7 @@
+import type { AvFramework } from "@aventara/core";
+import type { HostState } from "./protocol-host.factory.js";
+/**
+ * The state seed of `framework`'s access provider, over a platform request;
+ * `undefined` for a Framework built without `access`.
+ */
+export declare function accessStateSeed(framework: AvFramework): HostState | undefined;

package/dist/access-state.translator.js

@@ -0,0 +1,20 @@
+import { accessProviderOf } from "@aventara/core/internal";
+function headersOf(request) {
+    const headers = new Headers();
+    const given = request?.headers;
+    for (const [name, value] of Object.entries(given ?? {})) {
+        if (value === undefined || name.startsWith(":")) {
+            continue;
+        }
+        for (const one of typeof value === "string" ? [value] : value) {
+            headers.append(name, one);
+        }
+    }
+    return headers;
+}
+export function accessStateSeed(framework) {
+    const state = accessProviderOf(framework)?.state;
+    return state === undefined
+        ? undefined
+        : (request) => state({ headers: headersOf(request), request });
+}