@croutonian/with-openapi 0.2.0 → 0.4.0

package/README.md

@@ -6,7 +6,8 @@
 [![CI](https://github.com/croutonian/with-openapi/actions/workflows/ci.yml/badge.svg)](https://github.com/croutonian/with-openapi/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-OpenAPI middleware for [`@supabase/middleware`](https://github.com/supabase/middleware).
+OpenAPI middleware for
+[`@supabase/middleware`](https://github.com/supabase/middleware).
 
 An OpenAPI document already says what your API accepts. This makes it say it at
 runtime: every request is matched to an Operation Object, optionally refused if
@@ -24,7 +25,8 @@ export default {
     [withOpenApi({ document, reference: true })],
     async (_req, ctx) => {
       if (!ctx.openapi.matched) return new Response(null, { status: 404 })
-      // Already validated, already coerced: `limit` is a number.
+      // Already validated and coerced, so this holds the number 10 — though
+      // its static type is `unknown`; see Parameters.
       const { limit } = ctx.openapi.params.query
       return Response.json({ operation: ctx.openapi.operationId, limit })
     },
@@ -68,17 +70,35 @@ A discriminated union on `matched`:
 ```ts
 if (ctx.openapi.matched) {
   ctx.openapi.route //  '/users/{id}' — the path template, not the pathname
-  ctx.openapi.method //  'get'
   ctx.openapi.operation //  the Operation Object, `$ref` already followed
   ctx.openapi.operationId //  'getUser'
   ctx.openapi.security //  the operation's, falling back to the document's
   ctx.openapi.params //  { path, query, header, cookie }, deserialized + coerced
-  ctx.openapi.body //  the parsed request body
-  ctx.openapi.mediaType //  the `content` key that matched
-  ctx.openapi.validated //  false when `validate: false`
+  ctx.openapi.mediaType //  which `content` key matched
 }
 ```
 
+`params` is `unknown` here. Give the middleware a document whose type survived
+and it narrows to that operation's own parameters — see
+[Typed against your document](#typed-against-your-document).
+
+Everything here is something only this middleware knows. What you already have,
+it does not hand back: not the `document` you passed in, not the method
+(`req.method`), not whether you configured `validate: false`, and not the parsed
+body — `req.json()` is one call and reading it here does not consume it.
+
+The parsed body is **not** here. Reading it in the middleware does not consume
+it — the framework hands every layer a buffered request — so the handler calls
+`req.json()` and gets the very bytes this middleware validated, without a second
+copy on `ctx` to keep in step with it.
+
+`mediaType` is contributed because it is the reverse case: it names which
+`content` key matched, and so which schema ran, and repeating that takes
+resolving a `$ref` on `requestBody` and reimplementing the exact / `type/*` /
+`*/*` precedence. It is **not** the request's content type — a `*/*` range
+matches anything — so a handler deciding how to parse should read the header,
+which is what this middleware does too.
+
 With the defaults, the handler only ever sees `matched: true` — anything else
 was already answered with a `404` or a `405`. The narrowing matters once you set
 `onUnknownRoute` or `onUnknownMethod` to `'pass'`, or pass a `skip`; then the
@@ -129,6 +149,16 @@ callback before that response is built:
 | `unsupported_media_type` | 415    | The body's content type is not in the operation's `content`.            |
 | `validation_failed`      | 400    | A parameter or body failed its schema.                                  |
 
+`route_not_found` says which of its two causes it was, because they are the same
+status and very different mistakes — a `basePath` nothing starts with turns
+every route into a 404, and blaming the document sends you looking for a path
+that is already in it:
+
+```
+no operation in the API description matches "/nope"
+the pathname "/users/me" is outside basePath "/api/v1"
+```
+
 The default body:
 
 ```json
@@ -154,10 +184,10 @@ path to the property that failed.
 
 ### Descriptions
 
-`message` is the validator's, and says what is mechanically wrong.
-`description` is the **document's own prose** for whatever failed, and is
-usually the half a caller can act on. You wrote it once; there is no reason for
-an error response to throw it away.
+`message` is the validator's, and says what is mechanically wrong. `description`
+is the **document's own prose** for whatever failed, and is usually the half a
+caller can act on. You wrote it once; there is no reason for an error response
+to throw it away.
 
 It is resolved from the most specific place that has it:
 
@@ -182,14 +212,14 @@ body                     Instance does not have required property "name".
 That third row is the one worth pointing at: `required` fails against the
 _object_, so the obvious implementation describes the object — "A person with
 access to the workspace" — which says nothing about what is missing. The
-property is named only inside the validator's message, so it is read from
-there, and falls back to the container's prose if that wording ever changes.
+property is named only inside the validator's message, so it is read from there,
+and falls back to the container's prose if that wording ever changes.
 
 A field with nothing written about it simply has no `description`. Set
-`validate: { describe: false }` to leave them all off — descriptions are
-written for a document's consumers, who are the same people reading these
-errors, but turn it off if yours carries notes you would rather not return in
-a response body.
+`validate: { describe: false }` to leave them all off — descriptions are written
+for a document's consumers, who are the same people reading these errors, but
+turn it off if yours carries notes you would rather not return in a response
+body.
 
 To answer in your own error envelope:
 
@@ -213,7 +243,16 @@ handy for customizing one kind and leaving the rest alone.
 entry in the document:
 
 - `GET /reference` — the HTML page
-- `GET /reference/openapi.json` — the document, for the page to load
+- `GET /openapi.json` — the document, for the page to load
+
+Both defaults are derived from `basePath`, so under `basePath: '/api'` they are
+`/api/reference` and `/api/openapi.json`. A reference outside the mount is
+usually unreachable rather than merely unconventional: a host that routes only
+`/api/*` to this handler can never produce a pathname of `/reference`.
+
+The document path is derived from the mount, **not** from `path` — the document
+is the artifact and the page is one view of it, so moving the page to `/docs`
+leaves the document where it was.
 
 ```ts
 withOpenApi({
@@ -238,14 +277,55 @@ entirely:
 
 ```ts
 reference: {
-  html: ({ documentPath }) => myOwnPage(documentPath)
+  html: ({ documentPath, documentUrl }) => myOwnPage(documentUrl)
 }
 ```
 
-The reference paths are absolute — they are **not** relative to `basePath`.
+A path you give explicitly is taken **literally** — `basePath` is not applied to
+it, so an API under `/api/v1` can still put its docs at `/docs`:
+
+```ts
+withOpenApi({ document, basePath: '/api/v1', reference: { path: '/docs' } })
+// -> /docs, not /api/v1/docs
+```
+
+Only the default is derived from the mount.
+
+### Behind a gateway that rewrites the path
+
+`documentPath` is matched against the pathname this middleware is handed.
+`documentUrl` is what the page tells the browser to fetch. They default to the
+same string, which is right until something rewrites the path in front of you —
+and then no single value works: one spelling never serves the JSON, the other
+renders a page that loads and immediately reports that it could not load the
+document.
+
+Supabase Edge Functions is that case by default. The platform routes on
+`/functions/v1/<fn>/...`, strips `/functions/v1`, and hands the worker
+`/<fn>/...`:
+
+```ts
+withOpenApi({
+  document,
+  // What the worker sees — not the public URL, and not `servers[0].url`.
+  basePath: '/api',
+  reference: {
+    path: '/api/reference',
+    documentPath: '/api/openapi.json', // where this middleware serves it
+    documentUrl: '/functions/v1/api/openapi.json', // where a browser fetches it
+  },
+})
+```
 
 ## Parameters
 
+Every parameter is typed `unknown`, whatever its schema says. The document is
+data this middleware reads at runtime, and turning a schema into a TypeScript
+type needs code generation, which is not something this package does. So the
+_value_ is coerced and checked — `params.query.limit` holds the number `10` —
+while the _type_ you hover is `unknown`, and narrowing it is yours. Anything
+stronger would be a type that lies when a document changes without a rebuild.
+
 `style` and `explode` are honored, so the document decides how a value is
 spelled:
 
@@ -284,18 +364,121 @@ the request says it is:
 | `multipart/form-data`                | object, with parts left as `File`  | no        |
 | anything else                        | not read at all                    | no        |
 
-Multipart parts are `File` objects, which no JSON Schema describes, so the body
-is parsed onto `ctx` but not schema-checked. Binary media types are never
-buffered — there is no shape to check, and reading a large upload to ignore it
-is pure cost. `required` is enforced for both.
+Multipart parts are `File` objects, which no JSON Schema describes, so a
+multipart body is parsed — enough to reject a malformed one and to enforce
+`required` — but never schema-checked. Binary media types are never buffered:
+there is no shape to check, and reading a large upload to ignore it is pure
+cost.
+
+Two consequences of the body not being contributed, both worth knowing: reading
+it here does not consume it, so `req.json()` in the handler returns the same
+value that was validated; and the coercion in the urlencoded row is applied for
+validation and then dropped, so a handler reading that body itself sees the
+original text.
+
+## Typed against your document
+
+`ctx.openapi.params` is `unknown` by default, because the middleware reads
+whatever document it is handed at runtime. Hand it a document whose type
+survived, though, and it narrows to that document's own operations:
+
+```ts
+import { pipeline } from '@supabase/middleware'
+import { withOpenApi, defineDocument } from '@croutonian/with-openapi'
+
+const document = defineDocument({
+  openapi: '3.1.0',
+  info: { title: 'Acme', version: '1' },
+  paths: {
+    '/users/{id}': {
+      get: {
+        operationId: 'getUser',
+        parameters: [
+          {
+            name: 'id',
+            in: 'path',
+            required: true,
+            schema: { type: 'integer' },
+          },
+        ],
+        responses: { '200': { description: 'ok' } },
+      },
+    },
+    '/users': {
+      get: {
+        operationId: 'listUsers',
+        parameters: [
+          { name: 'limit', in: 'query', schema: { type: 'integer' } },
+        ],
+        responses: { '200': { description: 'ok' } },
+      },
+    },
+  },
+})
+
+export default {
+  fetch: pipeline([withOpenApi({ document })], async (_req, ctx) => {
+    if (!ctx.openapi.matched) return new Response(null, { status: 404 })
+
+    if (ctx.openapi.operationId === 'getUser') {
+      ctx.openapi.params.path.id //  number
+    }
+    if (ctx.openapi.operationId === 'listUsers') {
+      ctx.openapi.params.query.limit //  number | undefined
+    }
+    return Response.json({})
+  }),
+}
+```
+
+`ctx.openapi` becomes one branch per declared operation, discriminated by
+`operationId` (or `route`). Narrowing is all it takes — no cast, no route
+argument, no runtime guard, and the compiler knows when you have handled every
+operation.
+
+### The document has to keep its type
+
+```ts
+withOpenApi({ document: { /* literal inline */ } })   // ✅
+const document = defineDocument({ ... })              // ✅ in its own module
+const document = { ... } satisfies OpenAPIObject      // ⚠️  see below
+const document: OpenAPIObject = { ... }               // ❌ falls back to unknown
+import document from './openapi.json'                 // ❌ fails to compile
+```
+
+`defineDocument` is an identity function whose only job is its `const` type
+parameter. `satisfies` gets close — route names and schemas survive it — but it
+still lets leaf values widen where the target type says `string`, so
+`servers[0].url` comes back as `string` rather than the URL you wrote.
+
+An annotation is the one that costs you silently: `paths` widens to an index
+signature, and the contribution **falls back to the unspecialized shape**, so
+everything keeps working and `params` stays `unknown`. That fallback is
+deliberate — it is what makes this additive rather than breaking. A `.json`
+import fails earlier and louder: its values widen too, so `in: string` no
+longer narrows to a `ParameterLocation` and the document fails the constraint.
+
+### What the projections cover
+
+A deliberate subset of JSON Schema, not an implementation of it — the runtime
+validator remains the authority. Covered: `$ref` into `#/components/schemas`
+and `#/components/parameters`, `const`, `enum`, `string` / `integer` /
+`number` / `boolean` / `null`, arrays via `items`, objects via `properties`
+with `required` driving optionality, and Path Item parameters merged into every
+operation beneath them. `$ref` chains are followed eight levels deep, so a
+recursive schema terminates.
+
+Not interpreted: `allOf`, `oneOf`, `anyOf`. Those resolve to `unknown`, which
+is what the untyped path gives you anyway — guessing at them is how a type
+starts disagreeing with the validator that actually runs.
 
-Reading the body here does not consume it. The framework hands every layer a
-buffered request, so the handler can still call `req.json()`.
+`RoutesOf`, `MethodsOf`, `OperationIdsOf`, `OperationOf`, `ParamsFor` and
+`FromSchema` are exported for reading the same document yourself.
 
 ## CORS
 
-An OpenAPI document already knows most of a CORS policy. `cors` derives it,
-per route:
+An OpenAPI document already knows most of a CORS policy. `cors` derives it, per
+route:
 
 ```ts
 withOpenApi({
@@ -323,15 +506,15 @@ comes from.
 Three things worth knowing:
 
 - **`origin` is required and never derived.** A document says where an API
-  lives, not who may call it — `servers` is not an allowlist, and treating it
-  as one would be a security decision made from the wrong data. Same for
+  lives, not who may call it — `servers` is not an allowlist, and treating it as
+  one would be a security decision made from the wrong data. Same for
   `credentials`.
 - **Rejections are stamped too.** An unstamped `400` reaches a browser as an
   opaque CORS error rather than the violations it is carrying.
 - **The document is the source of truth for headers.** A request header the API
   reads but the document does not declare will be refused by the browser. That
-  is usually the document being wrong; `allowedHeaders` is the escape hatch
-  when it genuinely is not.
+  is usually the document being wrong; `allowedHeaders` is the escape hatch when
+  it genuinely is not.
 
 Preflights are answered after the route match but before the method lookup —
 otherwise the `OPTIONS` no document declares an operation for would come back
@@ -368,11 +551,11 @@ Worth knowing before you wire this into something:
   translating it. A 3.0 document falls back to draft 4, which gets
   `exclusiveMinimum` and `required` right but does **not** translate `nullable`.
   Convert to 3.1 for full fidelity.
-- **Local `$ref`s only.** External and remote references are not fetched.
-  Bundle the document first.
+- **Local `$ref`s only.** External and remote references are not fetched. Bundle
+  the document first.
 - **Requests only.** Responses are not validated. That is the framework's model,
-  not an omission: a middleware runs before the handler, and response shape stays
-  under the handler's ownership.
+  not an omission: a middleware runs before the handler, and response shape
+  stays under the handler's ownership.
 - **`deepObject` is one level deep**, matching what the specification defines.
 - **Trailing slashes are normalized**, so `/users` and `/users/` are one route.
 - Indexing the document for validation stamps each node with its own absolute
@@ -391,8 +574,8 @@ Three, and each is load-bearing:
 - **`@cfworker/json-schema`** — the validator. Zero dependencies, and it
   _interprets_ schemas rather than compiling them to JavaScript, which is what
   lets it run on Cloudflare Workers and anywhere else `new Function` is
-  unavailable. The document is walked once at construction and every subschema in
-  it validated against that one index, so `$ref` — recursive ones included —
+  unavailable. The document is walked once at construction and every subschema
+  in it validated against that one index, so `$ref` — recursive ones included —
   resolves without inlining anything.
 - **`@supabase/middleware`** — the composition engine.
 
@@ -451,7 +634,7 @@ What it configures, and why each is needed:
 | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | A **GitHub App** with Contents and Pull requests write, installed on the repo, as `GH_APP_ID` + `GH_APP_PRIVATE_KEY` | release-please has to open a PR, and this org does not let GitHub Actions do that. An App is not GitHub Actions, so the policy does not cover it — and unlike `GITHUB_TOKEN`, its pushes trigger workflows, so the release PR gets CI. |
 | The **pkg.pr.new App** installed on the repo                                                                         | Branch previews. Without it the preview job warns and skips rather than failing.                                                                                                                                                       |
-| An **npm trusted publisher** for `@croutonian/with-openapi`                                                          | Publishing without a stored credential.                                                                                                                                                                                                |
+| An **npm trusted publisher** for `@croutonian/with-openapi`, with direct publish allowed                             | Publishing without a stored credential. Configurations created after 3 Sep 2026 default to staging only, and `release.yml` runs `npm publish` — stage-only would leave every release waiting in a staging area.                        |
 | The **JSR package** linked to this repository                                                                        | Same, on the JSR side.                                                                                                                                                                                                                 |
 
 To do it by hand instead, the same steps are in the comments at the top of
@@ -465,10 +648,10 @@ resolves that by publishing from your machine — your npm login, your 2FA, no
 token created and none stored. CI takes over from the next release.
 
 `release.yml` also accepts an `NPM_TOKEN` secret, but it is not a general
-answer: a token cannot answer a one-time password, and npm asks for one on
-every write unless the account's two-factor setting is _Authorization only_.
-Where 2FA covers writes, a CI publish fails with `EOTP` and the first version
-has to come from a human.
+answer: a token cannot answer a one-time password, and npm asks for one on every
+write unless the account's two-factor setting is _Authorization only_. Where 2FA
+covers writes, a CI publish fails with `EOTP` and the first version has to come
+from a human.
 
 Between releases, every branch push and pull request publishes an installable
 preview to [pkg.pr.new](https://pkg.pr.new):

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FetchHandler, Middleware } from "@supabase/middleware";
+import { FetchHandler, Middleware, SingleKeyEntry } from "@supabase/middleware";
 import { SchemaDraft } from "@cfworker/json-schema";
 import { OpenAPIObject, OperationObject, ParameterLocation, ParameterStyle, ReferenceObject, SchemaObject, SecurityRequirementObject } from "openapi3-ts/oas31";
 
@@ -124,6 +124,8 @@ declare const SCALAR_CDN_URL = "https://cdn.jsdelivr.net/npm/@scalar/api-referen
 interface ScalarHtmlInput {
   /** Absolute path the document JSON is served from. */
   readonly documentPath: string;
+  /** URL the page should fetch the document from. */
+  readonly documentUrl: string;
   /** Page `<title>`. */
   readonly title: string;
   /** Script URL for Scalar's standalone build. */
@@ -137,15 +139,44 @@ interface ScalarReferenceOptions {
    * Path the HTML page is served from. Matched exactly, and *before* the
    * document's own routes, so it does not need to appear in the document.
    *
-   * @defaultValue `'/reference'`
+   * Given explicitly it is taken literally — `basePath` is **not** applied,
+   * so an API under `/api/v1` can still put its docs at `/docs`. The default
+   * is derived from `basePath` instead, because a reference sitting outside
+   * the mount is usually unreachable rather than merely unconventional: on a
+   * host that routes only `/api/*` to this handler, nothing can produce a
+   * pathname of `/reference`.
+   *
+   * @defaultValue `` `${basePath}/reference` ``, or `'/reference'` unmounted
    */
   path?: string;
   /**
-   * Path the document JSON is served from.
+   * Path the document JSON is served from. Matched against the pathname this
+   * middleware is handed.
+   *
+   * Derived from `basePath`, not from {@link path}: the document is the
+   * artifact and the page is one view of it, so moving the page does not move
+   * the document, and the conventional `/openapi.json` is where people —
+   * and tooling — look for it.
    *
-   * @defaultValue `` `${path}/openapi.json` ``
+   * @defaultValue `` `${basePath}/openapi.json` ``, or `'/openapi.json'`
    */
   documentPath?: string;
+  /**
+   * URL the page tells the browser to fetch the document from.
+   *
+   * Defaults to {@link documentPath}, which is correct whenever the pathname
+   * this middleware is handed is the one a browser can reach. Behind a gateway
+   * that rewrites the path, it is not, and the two have to be set separately:
+   * on Supabase Edge Functions the platform routes on
+   * `/functions/v1/<fn>/...` and hands the worker `/<fn>/...`, so the document
+   * is *served* at `/api/openapi.json` and *fetched* from
+   * `/functions/v1/api/openapi.json`. No single value satisfies both -- set
+   * one and the JSON never serves, set the other and the page loads and then
+   * reports that it could not load the document.
+   *
+   * @defaultValue {@link documentPath}
+   */
+  documentUrl?: string;
   /** Page title. @defaultValue the document's `info.title`, or `'API Reference'` */
   title?: string;
   /** Script URL for Scalar's standalone build. @defaultValue {@link SCALAR_CDN_URL} */
@@ -153,7 +184,7 @@ interface ScalarReferenceOptions {
   /**
    * Extra options merged into the `Scalar.createApiReference` config — theme,
    * `darkMode`, `proxyUrl`, and anything else Scalar accepts. `url` is set
-   * from {@link documentPath} and can be overridden here.
+   * from {@link documentUrl} and can be overridden here.
    *
    * @see https://scalar.com/products/api-references/configuration
    */
@@ -167,7 +198,16 @@ interface ScalarReferenceOptions {
 //#region src/types.d.ts
 /** Where a parameter was declared. */
 type ParameterIn = 'path' | 'query' | 'header' | 'cookie';
-/** Deserialized, coerced parameters, grouped by where they came from. */
+/**
+ * Deserialized, coerced parameters, grouped by where they came from.
+ *
+ * `unknown` rather than the schema's type: the document is read at runtime, and
+ * lifting a schema into a TypeScript type needs code generation, which this
+ * package does not do. The value is coerced and checked; narrowing the type is
+ * the consumer's. Pinned by `N5` in `type-tests/negative.ts`, so widening this
+ * to `any` — which would compile and look safer while checking nothing — fails
+ * the build.
+ */
 interface OpenApiParams {
   readonly path: Readonly<Record<string, unknown>>;
   readonly query: Readonly<Record<string, unknown>>;
@@ -208,6 +248,13 @@ interface OpenApiRejection {
   readonly method: string;
   /** The request's pathname, before `basePath` is stripped. */
   readonly pathname: string;
+  /**
+   * A more specific explanation than the kind's stock wording, when there is
+   * one to give. `route_not_found` uses it to say whether the pathname missed
+   * `basePath` or matched no template under it, which are the same status and
+   * very different mistakes.
+   */
+  readonly message?: string;
   /** Path template that matched, when one did. */
   readonly route?: string;
   /** Methods the route does declare. Set on `method_not_allowed`. */
@@ -229,7 +276,7 @@ interface OpenApiValidateOptions {
   cookie?: boolean;
   /**
    * Check — and therefore read and parse — the request body. With this off,
-   * `ctx.openapi.body` is `undefined` and the handler reads the body itself.
+   * the body is never read here and reaches the handler unexamined.
    *
    * @defaultValue `true`
    */
@@ -316,7 +363,7 @@ interface WithOpenApiConfig {
   /**
    * Serve a Scalar API reference and the document JSON. `true` takes every
    * default — the page at `/reference`, the document at
-   * `/reference/openapi.json`.
+   * `/openapi.json`.
    *
    * @defaultValue off
    */
@@ -354,54 +401,119 @@ interface WithOpenApiConfig {
    */
   reject?: (rejection: OpenApiRejection, req: Request) => Response | undefined | Promise<Response | undefined>;
 }
-/** `ctx.openapi` when an operation in the document describes the request. */
+/**
+ * `ctx.openapi` when an operation in the document describes the request.
+ *
+ * Every field here is something a consumer would otherwise have to derive from
+ * the document itself. What the caller already holds — the document, the
+ * method, the validate config, the request body — is deliberately absent.
+ */
 interface OpenApiMatched {
   readonly matched: true;
-  /** The document, as passed to `withOpenApi`. */
-  readonly document: OpenAPIObject;
-  /** Path template that matched, e.g. `'/users/{id}'`. */
+  /**
+   * Path template that matched, e.g. `'/users/{id}'`.
+   *
+   * The label to group a request under. A pathname cannot be used for that —
+   * `/users/1` and `/users/2` are separate series — so this is what metrics,
+   * traces, rate-limit buckets and audit logs key on.
+   */
   readonly route: string;
-  /** Lowercase method the operation was declared under. */
-  readonly method: HttpMethod;
-  /** The Operation Object, with its own `$ref` (if any) already followed. */
+  /**
+   * The Operation Object, with its own `$ref` (if any) already followed.
+   *
+   * How a consumer drives behaviour off the document: `x-` extensions
+   * (`operation['x-rate-limit']`, `x-required-scope`), `deprecated` to stamp a
+   * sunset header, `tags` to attribute a request to the team that owns it.
+   *
+   * Here rather than left to a `document.paths` lookup because a Path Item can
+   * itself be a `$ref`, so that lookup is not reliably an Operation Object.
+   */
   readonly operation: OperationObject;
+  /**
+   * A name for this operation that survives the path changing, which `route`
+   * does not — so it is the stable key for a permission check, a handler
+   * dispatch table, or a log field you intend to query next year.
+   *
+   * Read through from {@link operation}, so it adds no information; it is here
+   * because it is the field consumers reach for most.
+   */
   readonly operationId: string | undefined;
   /**
    * Security requirements in force — the operation's, falling back to the
-   * document's. Contributed for a downstream auth middleware to act on; this
-   * middleware never enforces them.
+   * document's. Never enforced here; contributed so a downstream auth layer
+   * can enforce it without a route table of its own, and tell a public
+   * operation (`[]`) from one that needs a credential.
+   *
+   * The fallback is the reason this is not left to the consumer: reading
+   * `operation.security` alone treats a document-secured operation as public,
+   * which fails open.
    */
   readonly security: SecurityRequirementObject[] | undefined;
-  /** Deserialized and (unless turned off) coerced parameters. */
+  /**
+   * Deserialized and (unless turned off) coerced parameters, keyed by
+   * location.
+   *
+   * The one that saves real work: `params.query.limit` holds a number, already
+   * checked against its `maximum`, with `style`/`explode` honoured, so
+   * `?ids=1,2,3` arrives as an array and `?filter[a]=b` as an object. Without
+   * it every handler re-reads `URLSearchParams` and re-coerces by hand.
+   *
+   * Values only — every entry is typed `unknown`. See {@link OpenApiParams}.
+   */
   readonly params: OpenApiParams;
   /**
-   * The parsed request body. `undefined` when the operation declares none,
-   * when none was sent, when body validation is off, or when the media type
-   * is binary and was deliberately left unread.
+   * Which `content` key matched, and so which Media Type Object's schema the
+   * body was checked against.
+   *
+   * Worth having when an operation declares more than one: it tells a handler
+   * which contract it is serving (`application/json` against
+   * `application/vnd.acme.v2+json`, say), and tells telemetry which declared
+   * variant clients actually send, which is what you need before deprecating
+   * one.
+   *
+   * Not a substitute for the request's own `Content-Type`: a catch-all range
+   * matches anything, so this says which *declaration* applied, not what was
+   * actually sent. A handler choosing how to parse wants the header — which is
+   * what this middleware reads too.
+   *
+   * Contributed because it is the one decision made here that a consumer
+   * cannot cheaply repeat: it takes resolving a `$ref` on `requestBody` and
+   * reimplementing the exact / type-wildcard / catch-all precedence, and a
+   * reimplementation that drifted would disagree about which schema ran. The
+   * parsed body is not contributed for the opposite reason — reading it here
+   * does not consume it, so `req.json()` in the handler is one call away and
+   * returns the same value this middleware validated.
    */
-  readonly body: unknown;
-  /** The `content` key that matched the request's content type. */
   readonly mediaType: string | undefined;
-  /** `false` when `validate: false` — the request was matched, not checked. */
-  readonly validated: boolean;
 }
-/** `ctx.openapi` when the document does not describe the request. */
+/**
+ * `ctx.openapi` when the document does not describe the request.
+ *
+ * Only reachable with `onUnknownRoute`/`onUnknownMethod` set to `'pass'`, or a
+ * `skip` — which is how you put this middleware in front of an existing API
+ * and watch what it *would* have refused before letting it refuse anything.
+ */
 interface OpenApiUnmatched {
   readonly matched: false;
-  /** Why nothing matched. */
+  /**
+   * Which kind of miss it was, so an observer can tell them apart: `no_route`
+   * is a path the document does not describe (an undocumented endpoint, or
+   * someone probing), `no_operation` is a path it does describe reached with a
+   * verb it does not, and `skipped` is the consumer's own `skip` firing. Three
+   * different follow-up actions, and nothing else records which happened.
+   */
   readonly reason: 'skipped' | 'no_route' | 'no_operation';
-  readonly document: OpenAPIObject;
   /** Set when the path matched but the method was not declared under it. */
   readonly route: string | undefined;
-  /** The request's method, as sent. */
-  readonly method: string;
   readonly operation: undefined;
   readonly operationId: undefined;
   readonly security: undefined;
+  /**
+   * Always empty here. Kept uniform across both branches so the field every
+   * consumer reaches for does not need a `matched` guard.
+   */
   readonly params: OpenApiParams;
-  readonly body: undefined;
   readonly mediaType: undefined;
-  readonly validated: false;
 }
 /**
  * What lands at `ctx.openapi`.
@@ -413,7 +525,172 @@ interface OpenApiUnmatched {
  */
 type OpenApiContribution = OpenApiMatched | OpenApiUnmatched;
 //#endregion
+//#region src/document-types.d.ts
+/**
+ * Collapse an intersection of mapped types into one object type.
+ *
+ * Splitting `properties` by `required` produces `{ a: A } & { b?: B }`, which
+ * is assignable both ways but is not the *same* type — so an exact-equality
+ * test fails, and hovering it shows the intersection rather than the shape.
+ * Both matter here: the point of these projections is what the editor tells
+ * you.
+ */
+type Simplify<T> = { [K in keyof T]: T[K] } & {};
+/** How deep `$ref` chains and nested schemas are followed before giving up. */
+type MaxDepth = 8;
+type Deeper<D extends unknown[]> = [...D, unknown];
+type LocalRef<Document, Ref extends string, Bucket extends string> = Ref extends `#/components/${Bucket}/${infer Name}` ? Document extends {
+  components: { [K in Bucket]: Record<Name, infer Target> };
+} ? Target : unknown : unknown;
+/**
+ * A Schema Object as a TypeScript type.
+ *
+ * Covers `$ref` into `#/components/schemas`, `const`, `enum`, the primitive
+ * types, arrays, and objects with `required` driving optionality. Composition
+ * keywords (`allOf`, `oneOf`, `anyOf`) are not interpreted — they resolve to
+ * `unknown`, because guessing at them is how a type starts disagreeing with
+ * the validator.
+ */
+type FromSchema<Schema, Document, Depth extends unknown[] = []> = Depth['length'] extends MaxDepth ? unknown : Schema extends {
+  $ref: infer Ref extends string;
+} ? FromSchema<LocalRef<Document, Ref, 'schemas'>, Document, Deeper<Depth>> : Schema extends {
+  const: infer Value;
+} ? Value : Schema extends {
+  enum: ReadonlyArray<infer Member>;
+} ? Member : Schema extends {
+  type: 'string';
+} ? string : Schema extends {
+  type: 'integer' | 'number';
+} ? number : Schema extends {
+  type: 'boolean';
+} ? boolean : Schema extends {
+  type: 'null';
+} ? null : Schema extends {
+  type: 'array';
+} ? FromArraySchema<Schema, Document, Depth> : Schema extends {
+  type: 'object';
+} ? FromObjectSchema<Schema, Document, Depth> : unknown;
+type FromArraySchema<Schema, Document, Depth extends unknown[]> = Schema extends {
+  items: infer Items;
+} ? Array<FromSchema<Items, Document, Deeper<Depth>>> : unknown[];
+type FromObjectSchema<Schema, Document, Depth extends unknown[]> = Schema extends {
+  properties: infer Props;
+} ? Schema extends {
+  required: ReadonlyArray<infer Required extends string>;
+} ? Optionalize<Props, Required, Document, Depth> : Optionalize<Props, never, Document, Depth> : Record<string, unknown>;
+/** Split `properties` by whether `required` names them. */
+type Optionalize<Props, Required extends string, Document, Depth extends unknown[]> = Simplify<{ [K in keyof Props as K extends Required ? K : never]: FromSchema<Props[K], Document, Deeper<Depth>> } & { [K in keyof Props as K extends Required ? never : K]?: FromSchema<Props[K], Document, Deeper<Depth>> }>;
+/** The path templates the document declares. */
+type RoutesOf<Document> = Document extends {
+  paths: infer Paths;
+} ? Extract<keyof Paths, string> : never;
+type PathItemOf<Document, Route extends string> = Document extends {
+  paths: Record<Route, infer Item>;
+} ? Item : never;
+/** HTTP methods the document declares under `Route`. */
+type MethodsOf<Document, Route extends string> = Extract<keyof PathItemOf<Document, Route>, 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace'>;
+/** The Operation Object at `Route` + `Method`. */
+type OperationOf<Document, Route extends string, Method extends string> = PathItemOf<Document, Route> extends Record<Method, infer Operation> ? Operation : never;
+/** Every `operationId` the document declares, as a union. */
+type OperationIdsOf<Document> = Document extends {
+  paths: infer Paths;
+} ? { [R in keyof Paths]: { [M in keyof Paths[R]]: Paths[R][M] extends {
+  operationId: infer Id;
+} ? Id : never }[keyof Paths[R]] }[keyof Paths] : never;
+/**
+ * Parameter Objects in force for an operation: the Path Item's, then the
+ * operation's own, with `$ref`s into `#/components/parameters` followed.
+ */
+type ParametersOf<Document, Route extends string, Method extends string> = ResolveParameter<Document, PathItemOf<Document, Route> extends {
+  parameters: ReadonlyArray<infer Parameter>;
+} ? Parameter : never> | ResolveParameter<Document, OperationOf<Document, Route, Method> extends {
+  parameters: ReadonlyArray<infer Parameter>;
+} ? Parameter : never>;
+type ResolveParameter<Document, Parameter> = Parameter extends {
+  $ref: infer Ref extends string;
+} ? LocalRef<Document, Ref, 'parameters'> : Parameter;
+type SchemaOfParameter<Document, Parameter> = Parameter extends {
+  schema: infer Schema;
+} ? FromSchema<Schema, Document> : unknown;
+/** Parameters declared `in: Location`, keyed by name, optional unless required. */
+type ParametersIn<Document, Route extends string, Method extends string, Location extends string> = Extract<ParametersOf<Document, Route, Method>, {
+  name: string;
+  in: Location;
+}> extends infer Declared ? Simplify<{ [P in Extract<Declared, {
+  name: string;
+}> as P extends {
+  required: true;
+} ? P['name'] : never]: SchemaOfParameter<Document, P> } & { [P in Extract<Declared, {
+  name: string;
+}> as P extends {
+  required: true;
+} ? never : P['name']]?: SchemaOfParameter<Document, P> }> : never;
+/**
+ * `ctx.openapi.params` for one operation, with each value typed by its schema
+ * instead of `unknown`.
+ */
+type ParamsFor<Document, Route extends string, Method extends string> = {
+  readonly path: ParametersIn<Document, Route, Method, 'path'>;
+  readonly query: ParametersIn<Document, Route, Method, 'query'>;
+  readonly header: ParametersIn<Document, Route, Method, 'header'>;
+  readonly cookie: ParametersIn<Document, Route, Method, 'cookie'>;
+};
+/**
+ * The `matched` branch for one operation, with `route`, `operation` and
+ * `params` specialized to it.
+ *
+ * `security` and `mediaType` keep their general types: they are not what the
+ * narrowing is for, and pinning them would add conditional depth for no gain.
+ */
+type MatchedOperation<Document, Route extends string, Method extends string> = {
+  readonly matched: true;
+  readonly route: Route;
+  readonly operation: OperationOf<Document, Route, Method>;
+  readonly operationId: OperationOf<Document, Route, Method> extends {
+    operationId: infer Id;
+  } ? Id : undefined;
+  readonly security: OpenApiMatched['security'];
+  readonly params: ParamsFor<Document, Route, Method>;
+  readonly mediaType: OpenApiMatched['mediaType'];
+};
+/**
+ * Every operation the document declares, as a union — one branch each, so
+ * narrowing on `operationId` (or `route`) inside a handler reaches that
+ * operation's own parameter types with no cast.
+ */
+type MatchedFor<Document> = { [Route in RoutesOf<Document>]: { [Method in MethodsOf<Document, Route>]: MatchedOperation<Document, Route, Method> }[MethodsOf<Document, Route>] }[RoutesOf<Document>];
+/**
+ * What lands at `ctx.openapi` for a given document.
+ *
+ * Falls back to the unspecialized {@link OpenApiContribution} when the
+ * document arrived without its literal type — annotated `: OpenAPIObject`,
+ * say. `RoutesOf` is `never` there, which would otherwise leave a union with
+ * no `matched: true` branch at all and break every existing consumer.
+ * Degrading to today's shape is what keeps this change additive.
+ */
+type ContributionFor<Document> = [RoutesOf<Document>] extends [never] ? OpenApiContribution : MatchedFor<Document> | OpenApiUnmatched;
+//#endregion
 //#region src/with-openapi.d.ts
+/**
+ * The document-aware call signature, intersected *ahead* of the one
+ * `defineMiddleware` produces so it is tried first.
+ *
+ * Only the config-only form is specialized — the form that goes in a
+ * `pipeline` array, which is how this is mounted. `pipeline` then carries the
+ * document-specific contribution through to the handler on its own. The two
+ * handler-taking forms fall through to the general signatures below it, where
+ * `ctx.openapi` keeps its unspecialized shape.
+ *
+ * The runtime is untouched: this re-describes what `defineMiddleware` already
+ * returns. That makes the description an assertion we own — if `ParamsFor`
+ * ever disagrees with what the middleware actually deserializes, the types
+ * are what lie, and nothing here would catch it.
+ */
+interface TypedByDocument {
+  <const Document extends OpenAPIObject>(config: Omit<WithOpenApiConfig, 'document'> & {
+    document: Document;
+  }): SingleKeyEntry<'openapi', Record<never, never>, ContributionFor<Document>>;
+}
 /**
  * Middleware that holds an API to its own description.
  *
@@ -446,6 +723,30 @@ type OpenApiContribution = OpenApiMatched | OpenApiUnmatched;
  *
  * @category Middleware
  */
-declare const withOpenApi: Middleware<'openapi', WithOpenApiConfig, Record<never, never>, OpenApiContribution>;
+declare const withOpenApi: TypedByDocument & Middleware<'openapi', WithOpenApiConfig, Record<never, never>, OpenApiContribution>;
+//#endregion
+//#region src/define-document.d.ts
+/**
+ * Check a document against `OpenAPIObject` without widening it.
+ *
+ * Returns its argument; the whole function is the type parameter.
+ *
+ * @example
+ * ```ts
+ * // document.ts
+ * export const document = defineDocument({
+ *   openapi: '3.1.0',
+ *   info: { title: 'Acme', version: '1' },
+ *   servers: [{ url: '/api' }],
+ *   paths: { ... },
+ * })
+ *
+ * // server.ts — `ctx.openapi` is typed against these operations
+ * pipeline([withOpenApi({ document })], handler)
+ *
+ * document.servers[0].url //  '/api', not string
+ * ```
+ */
+declare function defineDocument<const Document extends OpenAPIObject>(document: Document): Document;
 //#endregion
-export { type CorsOrigin, type CorsPolicy, type FetchHandler, type HttpMethod, type OpenApiContribution, type OpenApiCorsOptions, type OpenApiMatched, type OpenApiParams, type OpenApiRejection, type OpenApiRejectionKind, type OpenApiUnmatched, type OpenApiValidateOptions, type OpenApiViolation, type ParameterIn, SCALAR_CDN_URL, type ScalarHtmlInput, type ScalarReferenceOptions, type SchemaDraft, type WithOpenApiConfig, withOpenApi };
+export { type ContributionFor, type CorsOrigin, type CorsPolicy, type FetchHandler, type FromSchema, type HttpMethod, type MatchedFor, type MethodsOf, type OpenApiContribution, type OpenApiCorsOptions, type OpenApiMatched, type OpenApiParams, type OpenApiRejection, type OpenApiRejectionKind, type OpenApiUnmatched, type OpenApiValidateOptions, type OpenApiViolation, type OperationIdsOf, type OperationOf, type ParameterIn, type ParamsFor, type RoutesOf, SCALAR_CDN_URL, type ScalarHtmlInput, type ScalarReferenceOptions, type SchemaDraft, type WithOpenApiConfig, defineDocument, withOpenApi };

package/dist/index.js

@@ -868,18 +868,20 @@ function joinPath(base, child) {
 	return `${base.endsWith("/") ? base.slice(0, -1) : base}/${child}`;
 }
 /** Fill in the reference endpoint's defaults, once, at construction. */
-function resolveReference(document, options) {
-	const path = options.path ?? "/reference";
+function resolveReference(document, options, basePath) {
+	const path = options.path ?? joinPath(basePath ?? "", "reference");
 	if (!path.startsWith("/")) throw new Error(`withOpenApi: reference.path must start with "/", got ${JSON.stringify(path)}`);
-	const documentPath = options.documentPath ?? joinPath(path, "openapi.json");
+	const documentPath = options.documentPath ?? joinPath(basePath ?? "", "openapi.json");
+	const documentUrl = options.documentUrl ?? documentPath;
 	const title = options.title ?? document.info?.title ?? "API Reference";
 	const cdnUrl = options.cdnUrl ?? SCALAR_CDN_URL;
 	const configuration = {
-		url: documentPath,
+		url: documentUrl,
 		...options.configuration
 	};
 	const page = (options.html ?? renderScalarHtml)({
 		documentPath,
+		documentUrl,
 		title,
 		cdnUrl,
 		configuration
@@ -887,6 +889,7 @@ function resolveReference(document, options) {
 	return {
 		path,
 		documentPath,
+		documentUrl,
 		cacheControl: options.cacheControl ?? "no-cache",
 		render: () => page
 	};
@@ -1151,7 +1154,7 @@ function defaultRejectionResponse(rejection) {
 	if (rejection.allow !== void 0 && rejection.allow.length > 0) headers.set("allow", rejection.allow.join(", "));
 	return Response.json({
 		error: rejection.kind,
-		message: REJECTION_MESSAGES[rejection.kind],
+		message: rejection.message ?? REJECTION_MESSAGES[rejection.kind],
 		...rejection.accepts === void 0 ? {} : { accepts: rejection.accepts },
 		violations: rejection.violations
 	}, {
@@ -1159,20 +1162,16 @@ function defaultRejectionResponse(rejection) {
 		headers
 	});
 }
-function unmatched(document, reason, method, route) {
+function unmatched(reason, route) {
 	return { openapi: {
 		matched: false,
 		reason,
-		document,
 		route,
-		method,
 		operation: void 0,
 		operationId: void 0,
 		security: void 0,
 		params: EMPTY_PARAMS,
-		body: void 0,
-		mediaType: void 0,
-		validated: false
+		mediaType: void 0
 	} };
 }
 /**
@@ -1246,7 +1245,7 @@ const withOpenApi = defineMiddleware({
 		const onUnknownMethod = config.onUnknownMethod ?? "reject";
 		const resolve = (schema) => resolveSchema(document, schema);
 		const validateSchema = options === void 0 ? void 0 : createSchemaValidator(document, config.schemaDraft ?? draftFor(document));
-		const reference = config.reference === void 0 || config.reference === false ? void 0 : resolveReference(document, config.reference === true ? {} : config.reference);
+		const reference = config.reference === void 0 || config.reference === false ? void 0 : resolveReference(document, config.reference === true ? {} : config.reference, basePath);
 		const documentJson = reference === void 0 ? void 0 : JSON.stringify(document);
 		const cors = config.cors === void 0 ? void 0 : createCorsPolicy(document, routes, config.cors);
 		/**
@@ -1263,7 +1262,7 @@ const withOpenApi = defineMiddleware({
 				route: void 0
 			});
 			if (config.skip?.(req) === true) return {
-				result: unmatched(document, "skipped", req.method, void 0),
+				result: unmatched("skipped", void 0),
 				route: void 0
 			};
 			const url = new URL(req.url);
@@ -1289,7 +1288,7 @@ const withOpenApi = defineMiddleware({
 			const match = pathname === void 0 ? void 0 : router.match(pathname);
 			if (match === void 0) {
 				if (onUnknownRoute === "pass") return {
-					result: unmatched(document, "no_route", req.method, void 0),
+					result: unmatched("no_route", void 0),
 					route: void 0
 				};
 				return respond({
@@ -1297,6 +1296,7 @@ const withOpenApi = defineMiddleware({
 					status: 404,
 					method: req.method,
 					pathname: url.pathname,
+					message: pathname === void 0 ? `the pathname ${JSON.stringify(url.pathname)} is outside basePath ${JSON.stringify(basePath)}` : `no operation in the API description matches ${JSON.stringify(pathname)}`,
 					violations: []
 				});
 			}
@@ -1307,7 +1307,7 @@ const withOpenApi = defineMiddleware({
 			const operation = isHttpMethod(method) ? match.route.operations.get(method) : void 0;
 			if (operation === void 0) {
 				if (onUnknownMethod === "pass") return {
-					result: unmatched(document, "no_operation", req.method, match.route.template),
+					result: unmatched("no_operation", match.route.template),
 					route: match.route
 				};
 				return respond({
@@ -1342,7 +1342,6 @@ const withOpenApi = defineMiddleware({
 					message: `query parameter "${name}" is not declared by this operation`
 				});
 			}
-			let body;
 			let mediaType;
 			const requestBody = operation.requestBody;
 			if (requestBody !== void 0 && options?.body === true) {
@@ -1373,7 +1372,6 @@ const withOpenApi = defineMiddleware({
 					});
 				} else {
 					mediaType = read.content.mediaType;
-					body = read.value;
 					if (read.validatable && read.content.schema !== void 0 && validateSchema) {
 						const schema = read.content.schema;
 						for (const unit of validateSchema(read.value, schema)) violations.push(toViolation("body", void 0, unit, options?.describe === true ? describeFailure(document, schema, unit) : void 0));
@@ -1391,16 +1389,12 @@ const withOpenApi = defineMiddleware({
 			return {
 				result: { openapi: {
 					matched: true,
-					document,
 					route: operation.route,
-					method: operation.method,
 					operation: operation.operation,
 					operationId: operation.operationId,
 					security: operation.security,
 					params,
-					body,
-					mediaType,
-					validated: options !== void 0
+					mediaType
 				} },
 				route: match.route
 			};
@@ -1416,4 +1410,31 @@ const withOpenApi = defineMiddleware({
 });
 
 //#endregion
-export { SCALAR_CDN_URL, withOpenApi };
+//#region src/define-document.ts
+/**
+* Check a document against `OpenAPIObject` without widening it.
+*
+* Returns its argument; the whole function is the type parameter.
+*
+* @example
+* ```ts
+* // document.ts
+* export const document = defineDocument({
+*   openapi: '3.1.0',
+*   info: { title: 'Acme', version: '1' },
+*   servers: [{ url: '/api' }],
+*   paths: { ... },
+* })
+*
+* // server.ts — `ctx.openapi` is typed against these operations
+* pipeline([withOpenApi({ document })], handler)
+*
+* document.servers[0].url //  '/api', not string
+* ```
+*/
+function defineDocument(document) {
+	return document;
+}
+
+//#endregion
+export { SCALAR_CDN_URL, defineDocument, withOpenApi };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@croutonian/with-openapi",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "OpenAPI middleware for @supabase/middleware. Matches each request against an OpenAPI 3.1 document, optionally rejects the ones it does not describe, contributes the matched operation and validated params to ctx, and optionally serves a Scalar API reference.",
   "keywords": [
     "openapi",