@schemavaults/openapi-operations 0.3.0 → 0.4.0

package/README.md

@@ -105,20 +105,69 @@ Request bodies take two extra flags:
 
 An `AuthSchemeDefinition` is a named OpenAPI security scheme plus docs metadata. Built-ins:
 
-| Export | Scheme |
-| --- | --- |
-| `schemaVaultsAccessTokenBearerScheme` | `Authorization: Bearer <access token>` |
-| `schemaVaultsAccessTokenCookieScheme(cookieName)` | first-party access token cookie |
-| `schemaVaultsRefreshTokenCookieScheme(cookieName)` | auth-server session cookie |
-| `oidcClientSecretBasicScheme` / `oidcClientSecretPostScheme` | OAuth 2.0 client authentication |
-| `apiKeyHeaderScheme(name, header)` | static API key |
-| `defineAuthScheme({...})` | anything else |
+| Export | Scheme | Principal |
+| --- | --- | --- |
+| `schemaVaultsAccessTokenBearerScheme` | `Authorization: Bearer <access token>` | user |
+| `schemaVaultsAccessTokenCookieScheme(cookieName)` | first-party access token cookie | user |
+| `schemaVaultsRefreshTokenCookieScheme(cookieName)` | auth-server session cookie | user |
+| `oidcClientSecretBasicScheme` / `oidcClientSecretPostScheme` | OAuth 2.0 client authentication | any |
+| `apiKeyHeaderScheme(name, header)` | static API key | any |
+| `defineAuthScheme({...})` | anything else | as declared |
 
 Schemes describe *how* credentials are transported; verification is a per-host
 `AuthResolver` (below). The OpenAPI document carries the standard `security`
 requirement per operation and an `x-schemavaults-auth` extension with the route guard,
 required scopes and organization role so docs can display them.
 
+#### User-bearing schemes: non-nullable `ctx.auth.user`
+
+`AuthPrincipal.user` is `TUser | null` because a principal may be a non-user credential
+(client credentials, an API key). A scheme whose resolver *always* identifies a user
+declares `principal: "user"` (the three SchemaVaults token schemes do), and when every
+scheme an operation accepts is such a scheme, its handler gets `ctx.auth.user` typed as
+`TUser`:
+
+```ts
+const userSchemes = [schemaVaultsAccessTokenBearerScheme, accessTokenCookieScheme] as const;
+
+export const me = defineOperation({
+  auth: requireAuth({ schemes: userSchemes }), // keep the tuple type: `as const`, no widening
+  handler: (ctx) => ctx.json(200, { uid: ctx.auth.user.uid }), // UserData, not UserData | null
+  // ...
+});
+```
+
+Keep the scheme list's tuple type (a helper returning `RequiredOperationAuth` without
+its type parameter, or a scheme annotated as `AuthSchemeDefinition<"name">` instead of
+`AuthSchemeDefinition<"name", "user">`, widens it back to nullable). The runtime enforces
+the declaration: a `principal: "user"` scheme whose resolver returns a principal without
+a user is refused with 401. For operations that also accept non-user schemes,
+`requireUser(ctx.auth)` narrows and throws a 401 `OperationError` otherwise.
+
+Resource servers verifying SchemaVaults access tokens do not write resolvers for these
+schemes themselves: `createSchemaVaultsAuthResolvers()` from
+`@schemavaults/auth-server-sdk/openapi-operations` returns them, keyed by scheme name,
+built on the server SDK's `RouteGuardFactory` and the auth server's JWKS.
+
+### The error envelope
+
+Every error the runtime produces, and every `OperationError` a handler throws, is
+`{ success: false, error, message, issues?, details? }`. `OperationErrorBodySchema` is
+that envelope as a zod schema (registered as `components.schemas.OperationError`, with
+`OperationValidationIssueSchema` as `OperationValidationIssue`), for the 404 / 409 / ...
+responses a handler declares:
+
+```ts
+responses: {
+  200: { description: "App", schema: AppSchema },
+  404: { description: "No such app", schema: OperationErrorBodySchema },
+},
+handler: (ctx) => {
+  if (!app) throw new OperationError(404, { error: "not_found", message: "No such app" });
+  // ...
+},
+```
+
 ## Generating the OpenAPI document
 
 ```ts
@@ -129,9 +178,21 @@ export const openApiDocument = buildOpenApiDocument({
   servers: [{ url: "https://auth.schemavaults.com" }],
   tags: [{ name: "apps", description: "Client applications" }],
   operations: [getApp, health],
+  // Also document the responses the runtime produces on its own (below).
+  documentRuntimeResponses: true,
 });
 ```
 
+`buildOpenApiDocument` emits the responses each operation declares. The runtime also
+answers on its own with 400 (validation of params / query / headers / body, missing
+organization parameter), 401 (protected operations; with `WWW-Authenticate`), 403 (admin
+route guard, required scopes, organization role), 415 (operations with a validated body)
+and 500, all with the `OperationError` envelope. `documentRuntimeResponses: true` merges
+those into every operation that can produce them; a response the operation declares for
+the same status takes precedence. `runtimeErrorResponses(operation)` returns the set for
+one operation (and `withRuntimeErrorResponses(operation)` a copy with them merged) when
+you assemble responses yourself.
+
 ## Serving with Hono on Vercel / Next.js
 
 ```ts
@@ -212,15 +273,42 @@ dynamic segment is parsed by the app itself (Next.js' `params` are never read).
 for the rest to Next.js. The factory validates the whole catalogue up front (unique
 operations, a resolver for every scheme) and `api.app()` throws for an operation that
 is not in it, so a route file cannot serve something the document does not describe.
-The reverse (a documented operation with no route file) is a file-layout question;
-the example resource server in this repository checks it with a small `bun test`.
+The reverse (a documented operation with no route file, or one in the wrong folder) is a
+file-layout question; `checkNextAppRouterRoutes()` from
+`@schemavaults/openapi-operations/nextjs/app-router-routes` answers it for a `bun test`
+or a generation script. Given the catalogue and the `app` directory it verifies that every
+`operation.ts` / `operations.ts` under `app/api/**` exports operations that are in the
+catalogue and declare the path its folder serves (`[id]` ↔ `{id}`, `(group)` segments
+ignored, catch-all segments rejected), that a sibling `route.ts` exists, that every
+catalogue entry comes from such a file, and that every `route.ts` serves a catalogued path:
+
+```ts
+// src/lib/api/routes.test.ts
+import { checkNextAppRouterRoutes } from "@schemavaults/openapi-operations/nextjs/app-router-routes";
+
+test("route files and the catalogue agree", async () => {
+  const report = await checkNextAppRouterRoutes({
+    operations,                                   // the catalogue
+    appDirectory: path.resolve(import.meta.dir, "../../app"),
+    ignoredRoutePaths: ["/api/openapi.json"],     // route files that are not operations
+  });
+  expect(report.problems).toEqual([]);
+});
+```
+
+`assertNextAppRouterRoutes()` throws an `Error` listing every problem instead, for
+scripts. Options: `apiDirectory` (default `api`), `operationFileNames` (default
+`["operation.ts", "operations.ts"]`), `routeFileName`, `ignoredRouteDirectories` (e.g.
+`api/auth/[...nextauth]`), `importModule` (default dynamic `import()`), `catalogueLabel`.
 
 Per request the app: resolves the context, tries each accepted scheme's resolver in
 order (401 + `WWW-Authenticate` if none yields a principal), enforces the route guard
 (403), required scopes (403 `insufficient_scope`), organization membership (403), then
 validates params/query/headers/body (400 with zod issues, 415 on media type mismatch)
 and finally calls the handler. Errors use the `{ success: false, error, message }`
-envelope.
+envelope (`OperationErrorBodySchema`). An `OperationError` thrown from a different copy of
+this package (isolated installs can load it twice) is recognised structurally
+(`isOperationError()`), so it still short-circuits with its status and body.
 
 ## Scripts
 

package/dist/auth-scheme.d.ts

@@ -1,5 +1,19 @@
 import type { SecuritySchemeObject } from "openapi3-ts/oas31";
 import type { OrganizationMembershipRoleType } from "@schemavaults/auth-common/organizations";
+/**
+ * What kind of principal a scheme's resolver produces:
+ *
+ * - `"user"`: the credential always identifies a user, so a principal
+ *   resolved from it carries a non-null `user`. When every scheme an
+ *   operation accepts is a user scheme, its handler sees `ctx.auth.user`
+ *   typed as `TUser` (not `TUser | null`), and the runtime fails closed
+ *   (401) should a resolver ever return a principal without a user.
+ * - `"any"` (the default): the principal may or may not be a user (client
+ *   credentials, API keys, ...); handlers narrow `ctx.auth.user` themselves.
+ */
+export type AuthPrincipalKind = "user" | "any";
+export declare const AUTH_PRINCIPAL_KINDS: readonly ["user", "any"];
+export declare function isValidAuthPrincipalKind(value: unknown): value is AuthPrincipalKind;
 /**
  * A named OpenAPI security scheme (`components.securitySchemes[name]`) plus
  * the metadata the SchemaVaults docs UI uses to explain how to authenticate.
@@ -10,9 +24,11 @@ import type { OrganizationMembershipRoleType } from "@schemavaults/auth-common/o
  * server (which can decrypt its own tokens) and on a third-party resource
  * server (which verifies them against the auth server's JWKS).
  */
-export interface AuthSchemeDefinition<TName extends string = string> {
+export interface AuthSchemeDefinition<TName extends string = string, TPrincipal extends AuthPrincipalKind = AuthPrincipalKind> {
     /** Key under `components.securitySchemes` and in `security` requirements. */
     readonly name: TName;
+    /** What the resolver of this scheme produces; see {@link AuthPrincipalKind}. Default `"any"`. */
+    readonly principal?: TPrincipal;
     /** Human readable label for docs. */
     readonly title: string;
     /** Longer explanation for docs (where to get the credential, lifetime, ...). */
@@ -26,7 +42,16 @@ export interface AuthSchemeDefinition<TName extends string = string> {
      */
     readonly challenge?: string;
 }
-export declare function defineAuthScheme<const TName extends string>(definition: AuthSchemeDefinition<TName>): AuthSchemeDefinition<TName>;
+export declare function defineAuthScheme<const TName extends string, const TPrincipal extends AuthPrincipalKind = "any">(definition: AuthSchemeDefinition<TName, TPrincipal>): AuthSchemeDefinition<TName, TPrincipal>;
+/** Whether a principal resolved from the scheme is guaranteed to carry a user. */
+export declare function schemeResolvesUser(scheme: AuthSchemeDefinition): boolean;
+/** A scheme whose resolver always produces a user principal. */
+export type UserAuthSchemeDefinition<TName extends string = string> = AuthSchemeDefinition<TName, "user">;
+/**
+ * `true` when every scheme in the (non-empty) list is a user scheme, so a
+ * principal resolved through any of them carries a non-null user.
+ */
+export type AllSchemesResolveUser<TSchemes extends readonly AuthSchemeDefinition[]> = TSchemes extends readonly [] ? false : TSchemes[number] extends UserAuthSchemeDefinition ? true : false;
 /**
  * Route guard levels mirroring `@schemavaults/auth-server-sdk`'s
  * `withAuthenticatedApiRouteGuard` / `withAdminApiRouteGuard`.
@@ -54,9 +79,9 @@ export interface OrganizationRoleRequirement {
  * `x-schemavaults-auth` vendor extension so docs can show the route guard
  * and organization role in addition to the scopes.
  */
-export interface AuthRequirements {
+export interface AuthRequirements<TSchemes extends readonly AuthSchemeDefinition[] = readonly AuthSchemeDefinition[]> {
     /** Schemes accepted for this operation (any one of them satisfies it). */
-    readonly schemes: readonly AuthSchemeDefinition[];
+    readonly schemes: TSchemes;
     /** Who may call once authenticated. Defaults to "authenticated". */
     readonly routeGuard?: RouteGuardType;
     /**
@@ -74,28 +99,32 @@ export interface PublicOperationAuth {
     readonly type: "public";
     readonly notes?: string;
 }
-export interface RequiredOperationAuth extends AuthRequirements {
+export interface RequiredOperationAuth<TSchemes extends readonly AuthSchemeDefinition[] = readonly AuthSchemeDefinition[]> extends AuthRequirements<TSchemes> {
     readonly type: "required";
 }
 export type OperationAuth = PublicOperationAuth | RequiredOperationAuth;
 /** Marks an operation as callable without credentials. */
 export declare function publicAccess(notes?: string): PublicOperationAuth;
-/** Marks an operation as requiring one of the given schemes (+ extra checks). */
-export declare function requireAuth(requirements: AuthRequirements): RequiredOperationAuth;
+/**
+ * Marks an operation as requiring one of the given schemes (+ extra checks).
+ * The scheme list type is preserved so that operations accepting only
+ * `principal: "user"` schemes get a non-nullable `ctx.auth.user`.
+ */
+export declare function requireAuth<const TSchemes extends readonly AuthSchemeDefinition[]>(requirements: AuthRequirements<TSchemes>): RequiredOperationAuth<TSchemes>;
 export declare function isPublicOperationAuth(auth: OperationAuth): auth is PublicOperationAuth;
-/** `Authorization: Bearer <access token>` issued by the SchemaVaults auth server. */
-export declare const schemaVaultsAccessTokenBearerScheme: AuthSchemeDefinition<"schemavaults-access-token">;
+/** `Authorization: Bearer <access token>` issued by the auth server. */
+export declare const schemaVaultsAccessTokenBearerScheme: AuthSchemeDefinition<"schemavaults-access-token", "user">;
 /**
  * The first-party access-token cookie set by the auth server / resource
  * server SDK (`AccessTokenCookieName(api_server_id)`). The cookie name is
  * per API server, so the concrete name is filled in by the caller.
  */
-export declare function schemaVaultsAccessTokenCookieScheme(cookieName: string): AuthSchemeDefinition<"schemavaults-access-token-cookie">;
+export declare function schemaVaultsAccessTokenCookieScheme(cookieName: string): AuthSchemeDefinition<"schemavaults-access-token-cookie", "user">;
 /** The auth server's own refresh-token cookie (only meaningful ON the auth server). */
-export declare function schemaVaultsRefreshTokenCookieScheme(cookieName: string): AuthSchemeDefinition<"schemavaults-refresh-token-cookie">;
+export declare function schemaVaultsRefreshTokenCookieScheme(cookieName: string): AuthSchemeDefinition<"schemavaults-refresh-token-cookie", "user">;
 /** OAuth 2.0 `client_secret_basic` client authentication (RFC 6749 §2.3.1). */
-export declare const oidcClientSecretBasicScheme: AuthSchemeDefinition<"oidc-client-secret-basic">;
+export declare const oidcClientSecretBasicScheme: AuthSchemeDefinition<"oidc-client-secret-basic", "any">;
 /** OAuth 2.0 `client_secret_post` client authentication (credentials in the form body). */
-export declare const oidcClientSecretPostScheme: AuthSchemeDefinition<"oidc-client-secret-post">;
+export declare const oidcClientSecretPostScheme: AuthSchemeDefinition<"oidc-client-secret-post", "any">;
 /** A static API key in a header (e.g. cron / internal automation). */
 export declare function apiKeyHeaderScheme<const TName extends string>(name: TName, headerName: string, description?: string): AuthSchemeDefinition<TName>;

package/dist/auth-scheme.js

@@ -1,3 +1,7 @@
+export const AUTH_PRINCIPAL_KINDS = ["user", "any"];
+export function isValidAuthPrincipalKind(value) {
+    return typeof value === "string" && AUTH_PRINCIPAL_KINDS.includes(value);
+}
 export function defineAuthScheme(definition) {
     if (typeof definition.name !== "string" || definition.name.length === 0) {
         throw new TypeError("An auth scheme needs a non-empty name");
@@ -5,8 +9,15 @@ export function defineAuthScheme(definition) {
     if (!/^[A-Za-z0-9._-]+$/.test(definition.name)) {
         throw new TypeError(`Auth scheme name "${definition.name}" must match /^[A-Za-z0-9._-]+$/ (it becomes an OpenAPI component key)`);
     }
+    if (definition.principal !== undefined && !isValidAuthPrincipalKind(definition.principal)) {
+        throw new TypeError(`Auth scheme "${definition.name}" has an unknown principal kind "${String(definition.principal)}" (expected one of: ${AUTH_PRINCIPAL_KINDS.join(", ")})`);
+    }
     return Object.freeze({ ...definition });
 }
+/** Whether a principal resolved from the scheme is guaranteed to carry a user. */
+export function schemeResolvesUser(scheme) {
+    return scheme.principal === "user";
+}
 /**
  * Route guard levels mirroring `@schemavaults/auth-server-sdk`'s
  * `withAuthenticatedApiRouteGuard` / `withAdminApiRouteGuard`.
@@ -16,7 +27,11 @@ export const ROUTE_GUARD_TYPES = ["authenticated", "admin"];
 export function publicAccess(notes) {
     return notes === undefined ? { type: "public" } : { type: "public", notes };
 }
-/** Marks an operation as requiring one of the given schemes (+ extra checks). */
+/**
+ * Marks an operation as requiring one of the given schemes (+ extra checks).
+ * The scheme list type is preserved so that operations accepting only
+ * `principal: "user"` schemes get a non-nullable `ctx.auth.user`.
+ */
 export function requireAuth(requirements) {
     if (!Array.isArray(requirements.schemes) || requirements.schemes.length === 0) {
         throw new TypeError("requireAuth() needs at least one auth scheme; use publicAccess() for open operations");
@@ -40,16 +55,21 @@ export function isPublicOperationAuth(auth) {
 // ---------------------------------------------------------------------------
 // Built-in SchemaVaults schemes
 // ---------------------------------------------------------------------------
-/** `Authorization: Bearer <access token>` issued by the SchemaVaults auth server. */
+// The auth server may be any deployment of @schemavaults/auth-server,
+// including white-label ones, so the docs copy never names SchemaVaults as
+// the issuer. The scheme names (and challenge realms) are protocol
+// identifiers and stay as they are.
+/** `Authorization: Bearer <access token>` issued by the auth server. */
 export const schemaVaultsAccessTokenBearerScheme = defineAuthScheme({
     name: "schemavaults-access-token",
-    title: "SchemaVaults access token (Bearer)",
-    description: "An access token issued by the SchemaVaults auth server for this API server, sent as `Authorization: Bearer <token>`.",
+    principal: "user",
+    title: "Access token (Bearer)",
+    description: "An access token issued by the auth server for this API server, sent as `Authorization: Bearer <token>`.",
     securityScheme: {
         type: "http",
         scheme: "bearer",
         bearerFormat: "JWT",
-        description: "Access token issued by the SchemaVaults auth server for this API server.",
+        description: "Access token issued by the auth server for this API server.",
     },
     challenge: 'Bearer realm="schemavaults"',
 });
@@ -61,13 +81,14 @@ export const schemaVaultsAccessTokenBearerScheme = defineAuthScheme({
 export function schemaVaultsAccessTokenCookieScheme(cookieName) {
     return defineAuthScheme({
         name: "schemavaults-access-token-cookie",
-        title: "SchemaVaults access token (cookie)",
+        principal: "user",
+        title: "Access token (cookie)",
         description: `The first-party HTTP-only access token cookie \`${cookieName}\` set after login.`,
         securityScheme: {
             type: "apiKey",
             in: "cookie",
             name: cookieName,
-            description: "First-party access token cookie set by the SchemaVaults auth flow.",
+            description: "First-party access token cookie set after login.",
         },
     });
 }
@@ -75,7 +96,8 @@ export function schemaVaultsAccessTokenCookieScheme(cookieName) {
 export function schemaVaultsRefreshTokenCookieScheme(cookieName) {
     return defineAuthScheme({
         name: "schemavaults-refresh-token-cookie",
-        title: "SchemaVaults session (refresh token cookie)",
+        principal: "user",
+        title: "Auth server session (refresh token cookie)",
         description: `The auth server's HTTP-only refresh token cookie \`${cookieName}\`; only the auth server itself can resolve it.`,
         securityScheme: {
             type: "apiKey",

package/dist/auth-scheme.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-scheme.js","sourceRoot":"","sources":["../src/auth-scheme.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-scheme.js","sourceRoot":"","sources":["../src/auth-scheme.ts"],"names":[],"mappings":"AAgBA,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAiD,CAAC;AAEpG,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAClG,CAAC;AAkCD,MAAM,UAAU,gBAAgB,CAG9B,UAAmD;IACnD,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,SAAS,CACjB,qBAAqB,UAAU,CAAC,IAAI,wEAAwE,CAC7G,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,wBAAwB,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1F,MAAM,IAAI,SAAS,CACjB,gBAAgB,UAAU,CAAC,IAAI,oCAAoC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,uBAAuB,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACzJ,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,EAAE,CAAC,CAAC;AAC1C,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,MAA4B;IAC7D,OAAO,MAAM,CAAC,SAAS,KAAK,MAAM,CAAC;AACrC,CAAC;AAeD;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,eAAe,EAAE,OAAO,CAAU,CAAC;AAyDrE,0DAA0D;AAC1D,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,YAAwC;IAExC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,SAAS,CACjB,sFAAsF,CACvF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,YAAY,CAAC,OAAO,EAAE,CAAC;QAC1C,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,SAAS,CAAC,gBAAgB,MAAM,CAAC,IAAI,gBAAgB,CAAC,CAAC;QACnE,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IACD,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,GAAG,YAAY;QACf,UAAU,EAAE,YAAY,CAAC,UAAU,IAAI,eAAe;KACvD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAmB;IACvD,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,gCAAgC;AAChC,8EAA8E;AAC9E,sEAAsE;AACtE,2EAA2E;AAC3E,mEAAmE;AACnE,oCAAoC;AAEpC,wEAAwE;AACxE,MAAM,CAAC,MAAM,mCAAmC,GAAG,gBAAgB,CAAC;IAClE,IAAI,EAAE,2BAA2B;IACjC,SAAS,EAAE,MAAM;IACjB,KAAK,EAAE,uBAAuB;IAC9B,WAAW,EACT,yGAAyG;IAC3G,cAAc,EAAE;QACd,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,QAAQ;QAChB,YAAY,EAAE,KAAK;QACnB,WAAW,EAAE,6DAA6D;KAC3E;IACD,SAAS,EAAE,6BAA6B;CACzC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,UAAU,mCAAmC,CACjD,UAAkB;IAElB,OAAO,gBAAgB,CAAC;QACtB,IAAI,EAAE,kCAAkC;QACxC,SAAS,EAAE,MAAM;QACjB,KAAK,EAAE,uBAAuB;QAC9B,WAAW,EAAE,mDAAmD,UAAU,qBAAqB;QAC/F,cAAc,EAAE;YACd,IAAI,EAAE,QAAQ;YACd,EAAE,EAAE,QAAQ;YACZ,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,kDAAkD;SAChE;KACF,CAAC,CAAC;AACL,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,oCAAoC,CAClD,UAAkB;IAElB,OAAO,gBAAgB,CAAC;QACtB,IAAI,EAAE,mCAAmC;QACzC,SAAS,EAAE,MAAM;QACjB,KAAK,EAAE,4CAA4C;QACnD,WAAW,EAAE,sDAAsD,UAAU,iDAAiD;QAC9H,cAAc,EAAE;YACd,IAAI,EAAE,QAAQ;YACd,EAAE,EAAE,QAAQ;YACZ,IAAI,EAAE,UAAU;YAChB,WAAW,EAAE,6BAA6B;SAC3C;KACF,CAAC,CAAC;AACL,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,2BAA2B,GAAG,gBAAgB,CAAC;IAC1D,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,2CAA2C;IAClD,WAAW,EACT,mHAAmH;IACrH,cAAc,EAAE;QACd,IAAI,EAAE,MAAM;QACZ,MAAM,EAAE,OAAO;QACf,WAAW,EAAE,uCAAuC;KACrD;IACD,SAAS,EAAE,4BAA4B;CACxC,CAAC,CAAC;AAEH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,0BAA0B,GAAG,gBAAgB,CAAC;IACzD,IAAI,EAAE,yBAAyB;IAC/B,KAAK,EAAE,0CAA0C;IACjD,WAAW,EACT,+IAA+I;IACjJ,cAAc,EAAE;QACd,IAAI,EAAE,QAAQ;QACd,EAAE,EAAE,QAAQ;QACZ,IAAI,EAAE,mCAAmC;QACzC,WAAW,EACT,kIAAkI;KACrI;CACF,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,UAAU,kBAAkB,CAChC,IAAW,EACX,UAAkB,EAClB,WAAoB;IAEpB,OAAO,gBAAgB,CAAC;QACtB,IAAI;QACJ,KAAK,EAAE,YAAY,UAAU,GAAG;QAChC,WAAW,EACT,WAAW,IAAI,sCAAsC,UAAU,YAAY;QAC7E,cAAc,EAAE;YACd,IAAI,EAAE,QAAQ;YACd,EAAE,EAAE,QAAQ;YACZ,IAAI,EAAE,UAAU;SACjB;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -2,12 +2,13 @@ export { z, withOpenApi } from "./zod-openapi";
 export type { ZodType, ZodObject, OpenApiSchemaMetadata } from "./zod-openapi";
 export { HTTP_METHODS, HTTP_METHODS_WITH_REQUEST_BODY, isHttpMethod } from "./http-method";
 export type { HttpMethod } from "./http-method";
-export { defineAuthScheme, publicAccess, requireAuth, isPublicOperationAuth, ROUTE_GUARD_TYPES, schemaVaultsAccessTokenBearerScheme, schemaVaultsAccessTokenCookieScheme, schemaVaultsRefreshTokenCookieScheme, oidcClientSecretBasicScheme, oidcClientSecretPostScheme, apiKeyHeaderScheme, } from "./auth-scheme";
-export type { AuthSchemeDefinition, AuthRequirements, OperationAuth, PublicOperationAuth, RequiredOperationAuth, OrganizationRoleRequirement, RouteGuardType, } from "./auth-scheme";
+export { defineAuthScheme, AUTH_PRINCIPAL_KINDS, isValidAuthPrincipalKind, schemeResolvesUser, publicAccess, requireAuth, isPublicOperationAuth, ROUTE_GUARD_TYPES, schemaVaultsAccessTokenBearerScheme, schemaVaultsAccessTokenCookieScheme, schemaVaultsRefreshTokenCookieScheme, oidcClientSecretBasicScheme, oidcClientSecretPostScheme, apiKeyHeaderScheme, } from "./auth-scheme";
+export type { AllSchemesResolveUser, AuthPrincipalKind, AuthSchemeDefinition, AuthRequirements, UserAuthSchemeDefinition, OperationAuth, PublicOperationAuth, RequiredOperationAuth, OrganizationRoleRequirement, RouteGuardType, } from "./auth-scheme";
 export { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, operationHttpMethods, } from "./operation";
-export type { AnyOperationDefinition, AuthPrincipal, EmptyResponseStatusOf, InferBody, InferParsed, OperationDefiner, OperationDefinition, OperationGroup, OperationHandlerContext, OperationHandlerResult, OperationInput, OperationRequestDefinition, RequestBodyContentType, RequestBodyDefinition, ResponseBodyOf, ResponseDefinition, ResponseStatusOf, ResponsesDefinition, } from "./operation";
+export type { AnyOperationDefinition, AuthPrincipal, EmptyResponseStatusOf, InferBody, InferParsed, OperationDefiner, OperationDefinition, OperationGroup, OperationHandlerContext, OperationHandlerResult, OperationInput, OperationRequestDefinition, RequestBodyContentType, RequestBodyDefinition, ResolvedAuthPrincipal, ResponseBodyOf, ResponseDefinition, ResponseStatusOf, ResponsesDefinition, UserAuthPrincipal, } from "./operation";
 export { buildOpenApiDocument, collectAuthSchemes, toRouteConfig, toSecuritySchemeComponent, } from "./openapi/build-openapi-document";
 export type { BuildOpenApiDocumentOptions } from "./openapi/build-openapi-document";
+export { runtimeErrorResponses, withRuntimeErrorResponses } from "./openapi/runtime-responses";
 export type { OpenAPIObject } from "openapi3-ts/oas31";
 export { SCHEMAVAULTS_AUTH_EXTENSION, SCHEMAVAULTS_SCHEME_TITLE_EXTENSION, SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION, toSchemaVaultsAuthExtension, isSchemaVaultsAuthExtension, } from "./openapi/extensions";
 export type { SchemaVaultsAuthExtension } from "./openapi/extensions";

package/dist/index.js

@@ -1,8 +1,9 @@
 export { z, withOpenApi } from "./zod-openapi";
 export { HTTP_METHODS, HTTP_METHODS_WITH_REQUEST_BODY, isHttpMethod } from "./http-method";
-export { defineAuthScheme, publicAccess, requireAuth, isPublicOperationAuth, ROUTE_GUARD_TYPES, schemaVaultsAccessTokenBearerScheme, schemaVaultsAccessTokenCookieScheme, schemaVaultsRefreshTokenCookieScheme, oidcClientSecretBasicScheme, oidcClientSecretPostScheme, apiKeyHeaderScheme, } from "./auth-scheme";
+export { defineAuthScheme, AUTH_PRINCIPAL_KINDS, isValidAuthPrincipalKind, schemeResolvesUser, publicAccess, requireAuth, isPublicOperationAuth, ROUTE_GUARD_TYPES, schemaVaultsAccessTokenBearerScheme, schemaVaultsAccessTokenCookieScheme, schemaVaultsRefreshTokenCookieScheme, oidcClientSecretBasicScheme, oidcClientSecretPostScheme, apiKeyHeaderScheme, } from "./auth-scheme";
 export { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, operationHttpMethods, } from "./operation";
 export { buildOpenApiDocument, collectAuthSchemes, toRouteConfig, toSecuritySchemeComponent, } from "./openapi/build-openapi-document";
+export { runtimeErrorResponses, withRuntimeErrorResponses } from "./openapi/runtime-responses";
 export { SCHEMAVAULTS_AUTH_EXTENSION, SCHEMAVAULTS_SCHEME_TITLE_EXTENSION, SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION, toSchemaVaultsAuthExtension, isSchemaVaultsAuthExtension, } from "./openapi/extensions";
 export { extractPathParameterNames, openApiPathToHonoPath, honoPathToOpenApiPath, isOpenApiPath, } from "./openapi/path-format";
 export * from "./runtime";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,8BAA8B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mCAAmC,EACnC,mCAAmC,EACnC,oCAAoC,EACpC,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAWvB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAsBrB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAI1C,OAAO,EACL,2BAA2B,EAC3B,mCAAmC,EACnC,uCAAuC,EACvC,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,cAAc,WAAW,CAAC;AAI1B,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG/C,OAAO,EAAE,YAAY,EAAE,8BAA8B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG3F,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,qBAAqB,EACrB,iBAAiB,EACjB,mCAAmC,EACnC,mCAAmC,EACnC,oCAAoC,EACpC,2BAA2B,EAC3B,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAcvB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAwBrB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAG/F,OAAO,EACL,2BAA2B,EAC3B,mCAAmC,EACnC,uCAAuC,EACvC,2BAA2B,EAC3B,2BAA2B,GAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,qBAAqB,EACrB,aAAa,GACd,MAAM,uBAAuB,CAAC;AAE/B,cAAc,WAAW,CAAC;AAI1B,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/nextjs/app-router-routes.d.ts

@@ -0,0 +1,56 @@
+import type { AnyOperationDefinition } from "../operation";
+export interface CheckNextAppRouterRoutesOptions {
+    /** The catalogue `buildOpenApiDocument()` / the app factory are given. */
+    readonly operations: readonly AnyOperationDefinition[];
+    /** The Next.js `app` directory (absolute, or relative to the working directory), e.g. `src/app`. */
+    readonly appDirectory: string;
+    /** Sub-directory of `appDirectory` holding the API route files. Default `api`. */
+    readonly apiDirectory?: string;
+    /**
+     * File names (beside a `route.ts`) that declare the operations the route
+     * serves. Default `["operation.ts", "operations.ts"]`.
+     */
+    readonly operationFileNames?: readonly string[];
+    /** Default `route.ts`. */
+    readonly routeFileName?: string;
+    /**
+     * OpenAPI paths served by route files that are not operations (the route
+     * serving the OpenAPI document itself, a webhook with its own handler,
+     * ...). Such a route file needs no operation file.
+     */
+    readonly ignoredRoutePaths?: readonly string[];
+    /**
+     * Directories (relative to `appDirectory`, `/`-separated, e.g.
+     * `api/auth/[...nextauth]`) whose route files are not checked at all.
+     */
+    readonly ignoredRouteDirectories?: readonly string[];
+    /** Loads an operation module; default `import(fileUrl)`. */
+    readonly importModule?: (file: string) => Promise<Record<string, unknown>>;
+    /** How the catalogue is named in messages. Default `the operations catalogue`. */
+    readonly catalogueLabel?: string;
+}
+export interface NextAppRouterRoutesReport {
+    readonly ok: boolean;
+    /** Human readable problems; empty when `ok`. */
+    readonly problems: readonly string[];
+    /** Operation files that were checked (absolute paths). */
+    readonly operationFiles: readonly string[];
+    /** Route files that were checked (absolute paths). */
+    readonly routeFiles: readonly string[];
+}
+/**
+ * Route directory (relative to the app directory) → OpenAPI path:
+ * `(group)` segments dropped, `[param]` → `{param}`. Returns null for
+ * catch-all segments (`[...slug]`, `[[...slug]]`), which OpenAPI cannot
+ * describe.
+ */
+export declare function nextRouteDirectoryToOpenApiPath(routeDirectory: string): string | null;
+/** OpenAPI path → route directory relative to the app directory: `/api/items/{id}` → `api/items/[id]`. */
+export declare function openApiPathToNextRouteDirectory(openApiPath: string): string;
+/**
+ * Checks the route files against the catalogue and reports every problem
+ * found (never throws for layout problems; see {@link assertNextAppRouterRoutes}).
+ */
+export declare function checkNextAppRouterRoutes(options: CheckNextAppRouterRoutesOptions): Promise<NextAppRouterRoutesReport>;
+/** {@link checkNextAppRouterRoutes} that throws an Error listing every problem. */
+export declare function assertNextAppRouterRoutes(options: CheckNextAppRouterRoutesOptions): Promise<NextAppRouterRoutesReport>;

package/dist/nextjs/app-router-routes.js

@@ -0,0 +1,182 @@
+/**
+ * Consistency check between an operations catalogue and the Next.js App
+ * Router files serving it, for the "one `route.ts` per operation" layout
+ * (see `createOperationsAppFactory()`):
+ *
+ * - every `operation.ts` / `operations.ts` under the API directory exports
+ *   at least one operation, has a sibling `route.ts`, and each exported
+ *   operation is in the catalogue and declares the path its directory
+ *   serves (`app/api/items/[id]` ↔ `/api/items/{id}`, route groups
+ *   `(group)` ignored, catch-all segments rejected);
+ * - every catalogue entry comes from such a file;
+ * - every `route.ts` under the API directory serves a catalogued path (or
+ *   one listed in `ignoredRoutePaths`, e.g. the `openapi.json` route).
+ *
+ * Runs under `bun test` / a `bun` script (it reads the file system and
+ * imports the operation modules), not inside a request handler.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { assertUniqueOperations } from "../operation";
+const DEFAULT_OPERATION_FILE_NAMES = ["operation.ts", "operations.ts"];
+const DEFAULT_ROUTE_FILE_NAME = "route.ts";
+/**
+ * Route directory (relative to the app directory) → OpenAPI path:
+ * `(group)` segments dropped, `[param]` → `{param}`. Returns null for
+ * catch-all segments (`[...slug]`, `[[...slug]]`), which OpenAPI cannot
+ * describe.
+ */
+export function nextRouteDirectoryToOpenApiPath(routeDirectory) {
+    const out = [];
+    for (const segment of routeDirectory.split(/[\\/]/).filter((part) => part.length > 0)) {
+        if (segment.startsWith("(") && segment.endsWith(")"))
+            continue;
+        if (segment.startsWith("[...") || segment.startsWith("[[..."))
+            return null;
+        const param = /^\[([^\]]+)\]$/.exec(segment);
+        out.push(param ? `{${param[1]}}` : segment);
+    }
+    return `/${out.join("/")}`;
+}
+/** OpenAPI path → route directory relative to the app directory: `/api/items/{id}` → `api/items/[id]`. */
+export function openApiPathToNextRouteDirectory(openApiPath) {
+    return openApiPath
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => segment.replace(/^\{([^}]+)\}$/, "[$1]"))
+        .join("/");
+}
+function isOperationDefinition(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.method === "string" &&
+        typeof candidate.path === "string" &&
+        typeof candidate.operationId === "string" &&
+        typeof candidate.handler === "function");
+}
+function findFiles(directory, names) {
+    if (!existsSync(directory))
+        return [];
+    const found = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        // `_private` folders and node_modules are never routes.
+        if (entry.name.startsWith("_") || entry.name === "node_modules")
+            continue;
+        const full = join(directory, entry.name);
+        if (entry.isDirectory())
+            found.push(...findFiles(full, names));
+        else if (names.has(entry.name))
+            found.push(full);
+    }
+    return found.sort();
+}
+function toPosix(path) {
+    return path.split(sep).join("/");
+}
+async function defaultImportModule(file) {
+    return (await import(pathToFileURL(file).href));
+}
+/**
+ * Checks the route files against the catalogue and reports every problem
+ * found (never throws for layout problems; see {@link assertNextAppRouterRoutes}).
+ */
+export async function checkNextAppRouterRoutes(options) {
+    const appDirectory = resolve(options.appDirectory);
+    const apiDirectory = join(appDirectory, options.apiDirectory ?? "api");
+    const operationFileNames = new Set(options.operationFileNames ?? DEFAULT_OPERATION_FILE_NAMES);
+    const routeFileName = options.routeFileName ?? DEFAULT_ROUTE_FILE_NAME;
+    const ignoredRoutePaths = new Set(options.ignoredRoutePaths ?? []);
+    const ignoredRouteDirectories = new Set((options.ignoredRouteDirectories ?? []).map((directory) => toPosix(directory).replace(/^\/+|\/+$/g, "")));
+    const importModule = options.importModule ?? defaultImportModule;
+    const catalogueLabel = options.catalogueLabel ?? "the operations catalogue";
+    const cwd = process.cwd();
+    const label = (file) => toPosix(relative(cwd, file));
+    const routeDirectoryOf = (file) => toPosix(relative(appDirectory, dirname(file)));
+    const isIgnoredDirectory = (file) => ignoredRouteDirectories.has(routeDirectoryOf(file));
+    const problems = [];
+    try {
+        assertUniqueOperations(options.operations);
+    }
+    catch (error) {
+        problems.push(`${catalogueLabel}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const catalogued = new Set(options.operations);
+    const cataloguedById = new Map(options.operations.map((operation) => [operation.operationId, operation]));
+    const cataloguedPaths = new Set(options.operations.map((operation) => operation.path));
+    if (!existsSync(apiDirectory)) {
+        problems.push(`API directory ${label(apiDirectory)} does not exist`);
+    }
+    const operationFiles = findFiles(apiDirectory, operationFileNames).filter((file) => !isIgnoredDirectory(file));
+    const routeFiles = findFiles(apiDirectory, new Set([routeFileName])).filter((file) => !isIgnoredDirectory(file));
+    const discovered = new Set();
+    for (const file of operationFiles) {
+        const directory = dirname(file);
+        const fileLabel = label(file);
+        if (!existsSync(join(directory, routeFileName))) {
+            problems.push(`${fileLabel}: no sibling ${routeFileName} serves these operations`);
+        }
+        const expectedPath = nextRouteDirectoryToOpenApiPath(routeDirectoryOf(file));
+        if (expectedPath === null) {
+            problems.push(`${fileLabel}: catch-all segments cannot be described in OpenAPI; use explicit [param] segments`);
+            continue;
+        }
+        let mod;
+        try {
+            mod = await importModule(file);
+        }
+        catch (error) {
+            problems.push(`${fileLabel}: failed to import (${error instanceof Error ? error.message : String(error)})`);
+            continue;
+        }
+        const exported = Object.entries(mod).filter((entry) => isOperationDefinition(entry[1]));
+        if (exported.length === 0) {
+            problems.push(`${fileLabel}: exports no operations (export the result of defineOperation())`);
+            continue;
+        }
+        for (const [exportName, operation] of exported) {
+            const id = operation.operationId;
+            if (operation.path !== expectedPath) {
+                problems.push(`${fileLabel}: export '${exportName}' (${id}) declares path '${operation.path}' but its directory maps to '${expectedPath}'`);
+            }
+            if (catalogued.has(operation)) {
+                discovered.add(operation);
+            }
+            else if (cataloguedById.has(id)) {
+                problems.push(`${fileLabel}: export '${exportName}' (${id}) is a different object from the '${id}' listed in ${catalogueLabel} (defined twice?)`);
+            }
+            else {
+                problems.push(`${fileLabel}: export '${exportName}' (${id}) is not listed in ${catalogueLabel}`);
+            }
+        }
+    }
+    for (const operation of catalogued) {
+        if (!discovered.has(operation)) {
+            const fileNames = [...operationFileNames].join(" / ");
+            problems.push(`${catalogueLabel}: '${operation.operationId}' (${operation.method.toUpperCase()} ${operation.path}) is not exported by any ${fileNames} under ${label(apiDirectory)}; define operations next to the ${routeFileName} that serves them`);
+        }
+    }
+    for (const file of routeFiles) {
+        const routePath = nextRouteDirectoryToOpenApiPath(routeDirectoryOf(file));
+        if (routePath === null) {
+            problems.push(`${label(file)}: catch-all route files cannot serve documented operations; list its directory in ignoredRouteDirectories if it is not one`);
+            continue;
+        }
+        if (cataloguedPaths.has(routePath) || ignoredRoutePaths.has(routePath))
+            continue;
+        problems.push(`${label(file)}: serves '${routePath}', which is not in ${catalogueLabel} (add it to ignoredRoutePaths if it is not an operation)`);
+    }
+    return { ok: problems.length === 0, problems, operationFiles, routeFiles };
+}
+/** {@link checkNextAppRouterRoutes} that throws an Error listing every problem. */
+export async function assertNextAppRouterRoutes(options) {
+    const report = await checkNextAppRouterRoutes(options);
+    if (!report.ok) {
+        throw new Error(`Next.js App Router route files and the operations catalogue disagree:\n${report.problems
+            .map((problem) => `  - ${problem}`)
+            .join("\n")}`);
+    }
+    return report;
+}
+//# sourceMappingURL=app-router-routes.js.map