@schemavaults/openapi-operations 0.1.4

package/README.md

@@ -0,0 +1,164 @@
+# @schemavaults/openapi-operations
+
+Define HTTP operations once — method, path, [zod](https://zod.dev) v4 request/response
+schemas, and the auth scheme + permissions a caller needs — then:
+
+- generate an **OpenAPI 3.1 document** from them
+  (via [`@asteasolutions/zod-to-openapi`](https://github.com/asteasolutions/zod-to-openapi)), and
+- serve them as a **[Hono](https://hono.dev) app** on Vercel functions or Next.js
+  App Router route handlers, with request validation and auth enforcement built in.
+
+The same definitions power the auth server and third-party resource servers; only the
+credential *resolvers* differ per host. `@schemavaults/openapi-docs-ui` renders the
+generated document (routes, permissions, auth details) as browsable docs.
+
+## Install
+
+```bash
+bun add @schemavaults/openapi-operations
+```
+
+## Defining operations
+
+```ts
+import {
+  z,
+  createOperationDefiner,
+  requireAuth,
+  publicAccess,
+  schemaVaultsAccessTokenBearerScheme,
+} from "@schemavaults/openapi-operations";
+
+// Bind the per-request context and resolved-user types once per app.
+const defineOperation = createOperationDefiner<{ dbh: Kysely<AuthDatabase> }, UserData>();
+
+const AppSchema = z
+  .object({ app_id: z.string().uuid(), name: z.string() })
+  .openapi("App"); // emitted under components.schemas.App
+
+export const getApp = defineOperation({
+  method: "get",
+  path: "/api/apps/{app_id}", // OpenAPI style placeholders
+  summary: "Get an app",
+  tags: ["apps"],
+  auth: requireAuth({
+    schemes: [schemaVaultsAccessTokenBearerScheme],
+    routeGuard: "authenticated", // or "admin"
+    requiredScopes: ["email"],   // token scope claim must include these
+    organization: { parameter: "organization_id", roles: ["owner", "admin"] }, // optional
+  }),
+  request: {
+    params: z.object({ app_id: z.string().uuid() }),
+    query: z.object({ include: z.union([z.string(), z.array(z.string())]).optional() }),
+    headers: z.object({ "x-trace": z.string().optional() }),
+    // body: { contentType: "application/json", schema: ... } (POST/PUT/PATCH/DELETE only)
+  },
+  responses: {
+    200: { description: "The app", schema: AppSchema },
+    404: { description: "Not found", schema: ErrorSchema },
+  },
+  handler: async (ctx) => {
+    // ctx.params / ctx.query / ctx.headers / ctx.body are validated & typed
+    // ctx.auth is the AuthPrincipal (null only on publicAccess() operations)
+    // ctx.context is whatever createOperationsApp({ context }) produced
+    const app = await ctx.context.dbh.selectFrom("APPS")...;
+    if (!app) return ctx.json(404, { success: false, message: "No such app" });
+    return ctx.json(200, app); // status + body are checked against `responses`
+  },
+});
+
+export const health = defineOperation({
+  method: "get",
+  path: "/api/health",
+  summary: "Liveness probe",
+  auth: publicAccess(),
+  responses: { 200: { description: "ok", schema: z.object({ ok: z.literal(true) }) } },
+  handler: (ctx) => ctx.json(200, { ok: true }),
+});
+```
+
+`defineOperationGroup({ pathPrefix, tags, operations })` applies a shared prefix and tags.
+Throw `new OperationError(status, { error, message })` from a handler to short-circuit.
+
+### Auth schemes
+
+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 |
+
+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.
+
+## Generating the OpenAPI document
+
+```ts
+import { buildOpenApiDocument } from "@schemavaults/openapi-operations";
+
+export const openApiDocument = buildOpenApiDocument({
+  info: { title: "SchemaVaults Auth API", version: "1.0.0" },
+  servers: [{ url: "https://auth.schemavaults.com" }],
+  tags: [{ name: "apps", description: "Client applications" }],
+  operations: [getApp, health],
+});
+```
+
+## Serving with Hono on Vercel / Next.js
+
+```ts
+import { createOperationsApp, toNextRouteHandlers } from "@schemavaults/openapi-operations";
+
+const app = createOperationsApp<{ dbh: Kysely<AuthDatabase> }, UserData>({
+  operations: [getApp, health],
+  context: async () => ({ dbh: await getDbh() }),
+  authResolvers: {
+    // keyed by scheme name; return null when no credential for that scheme is present
+    "schemavaults-access-token": async (c) => {
+      const token = c.req.header("authorization")?.replace(/^Bearer /, "");
+      if (!token) return null;
+      const user = await verifyAccessToken(token); // throw OperationError(401, ...) if invalid
+      return {
+        scheme: "schemavaults-access-token",
+        user,
+        isAdmin: user.admin,
+        scope: user.scope ?? null,
+        getOrganizationRole: (orgId) => lookupMembershipRole(user.uid, orgId),
+      };
+    },
+  },
+  // Served at GET /openapi.json. Pass a function to build it per request,
+  // e.g. to set `servers` from the incoming Host / X-Forwarded-* headers.
+  openapi: { document: openApiDocument },
+});
+
+// app/api/[[...route]]/route.ts
+export const runtime = "nodejs";
+export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextRouteHandlers(app);
+
+// or a plain Vercel function: api/[[...route]].ts
+export default toVercelHandler(app);
+```
+
+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.
+
+## Scripts
+
+```bash
+bun run build      # tsc + tsc-alias → dist/
+bun run test       # bun test
+bun run lint
+bun run typecheck
+```

package/dist/adapters/nextjs.d.ts

@@ -0,0 +1,20 @@
+import type { Hono } from "hono";
+import { HTTP_METHODS, type HttpMethod } from "../http-method";
+export type NextRouteHandler = (request: Request) => Response | Promise<Response>;
+export type NextRouteHandlers<TMethods extends HttpMethod = HttpMethod> = {
+    readonly [M in TMethods as Uppercase<M>]: NextRouteHandler;
+};
+/**
+ * Next.js App Router route-handler exports for the operations app. Typical
+ * usage from a catch-all route so one Hono app serves every operation:
+ *
+ * ```ts
+ * // app/api/[[...route]]/route.ts
+ * export const runtime = "nodejs";
+ * export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextRouteHandlers(app);
+ * ```
+ *
+ * Pass `methods` to only export a subset (e.g. when a route file coexists
+ * with hand-written handlers for other methods).
+ */
+export declare function toNextRouteHandlers<const TMethods extends readonly HttpMethod[] = typeof HTTP_METHODS>(app: Hono, methods?: TMethods): NextRouteHandlers<TMethods[number]>;

package/dist/adapters/nextjs.js

@@ -0,0 +1,24 @@
+import { handle } from "hono/vercel";
+import { HTTP_METHODS } from "../http-method";
+/**
+ * Next.js App Router route-handler exports for the operations app. Typical
+ * usage from a catch-all route so one Hono app serves every operation:
+ *
+ * ```ts
+ * // app/api/[[...route]]/route.ts
+ * export const runtime = "nodejs";
+ * export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } = toNextRouteHandlers(app);
+ * ```
+ *
+ * Pass `methods` to only export a subset (e.g. when a route file coexists
+ * with hand-written handlers for other methods).
+ */
+export function toNextRouteHandlers(app, methods = HTTP_METHODS) {
+    const handler = handle(app);
+    const handlers = {};
+    for (const method of methods) {
+        handlers[method.toUpperCase()] = handler;
+    }
+    return handlers;
+}
+//# sourceMappingURL=nextjs.js.map

package/dist/adapters/nextjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nextjs.js","sourceRoot":"","sources":["../../src/adapters/nextjs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,YAAY,EAAmB,MAAM,gBAAgB,CAAC;AAQ/D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAS,EACT,UAAoB,YAAmC;IAEvD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAqC,EAAE,CAAC;IACtD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,QAAQ,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,GAAG,OAAO,CAAC;IAC3C,CAAC;IACD,OAAO,QAA+C,CAAC;AACzD,CAAC"}

package/dist/adapters/vercel.d.ts

@@ -0,0 +1,13 @@
+import type { Hono } from "hono";
+export type VercelFunctionHandler = (request: Request) => Response | Promise<Response>;
+/**
+ * Wraps the operations app as a Vercel (Fluid / Node.js / Edge) function
+ * handler using Hono's Vercel adapter. Export it from a `api/*.ts` function
+ * file or a Next.js route handler:
+ *
+ * ```ts
+ * // api/[[...route]].ts
+ * export default toVercelHandler(app);
+ * ```
+ */
+export declare function toVercelHandler(app: Hono): VercelFunctionHandler;

package/dist/adapters/vercel.js

@@ -0,0 +1,15 @@
+import { handle } from "hono/vercel";
+/**
+ * Wraps the operations app as a Vercel (Fluid / Node.js / Edge) function
+ * handler using Hono's Vercel adapter. Export it from a `api/*.ts` function
+ * file or a Next.js route handler:
+ *
+ * ```ts
+ * // api/[[...route]].ts
+ * export default toVercelHandler(app);
+ * ```
+ */
+export function toVercelHandler(app) {
+    return handle(app);
+}
+//# sourceMappingURL=vercel.js.map

package/dist/adapters/vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel.js","sourceRoot":"","sources":["../../src/adapters/vercel.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,GAAS;IACvC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC"}

package/dist/auth-scheme.d.ts

@@ -0,0 +1,101 @@
+import type { SecuritySchemeObject } from "openapi3-ts/oas31";
+import type { OrganizationMembershipRoleType } from "@schemavaults/auth-common/organizations";
+/**
+ * A named OpenAPI security scheme (`components.securitySchemes[name]`) plus
+ * the metadata the SchemaVaults docs UI uses to explain how to authenticate.
+ *
+ * The scheme only DESCRIBES how credentials are transported. Verifying them
+ * is the job of an {@link AuthResolver} registered with the Hono app under
+ * the same `name`, so the same operation definitions can run on the auth
+ * 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> {
+    /** Key under `components.securitySchemes` and in `security` requirements. */
+    readonly name: TName;
+    /** Human readable label for docs. */
+    readonly title: string;
+    /** Longer explanation for docs (where to get the credential, lifetime, ...). */
+    readonly description?: string;
+    /** The OpenAPI 3.1 security scheme object emitted into the document. */
+    readonly securityScheme: SecuritySchemeObject;
+    /**
+     * Value for the `WWW-Authenticate` header of a 401 produced when no
+     * credential for this scheme was presented (RFC 7235 §4.1). Optional;
+     * schemes without a challenge (cookies, api keys) omit it.
+     */
+    readonly challenge?: string;
+}
+export declare function defineAuthScheme<const TName extends string>(definition: AuthSchemeDefinition<TName>): AuthSchemeDefinition<TName>;
+/**
+ * Route guard levels mirroring `@schemavaults/auth-server-sdk`'s
+ * `withAuthenticatedApiRouteGuard` / `withAdminApiRouteGuard`.
+ */
+export declare const ROUTE_GUARD_TYPES: readonly ["authenticated", "admin"];
+export type RouteGuardType = (typeof ROUTE_GUARD_TYPES)[number];
+/**
+ * Membership requirement within the organization named by a path/query
+ * parameter of the operation. Mirrors `required_organization` +
+ * `custom_is_user_in_organization` on the server SDK route guard: platform
+ * administrators bypass the membership check unless `adminBypass` is false.
+ */
+export interface OrganizationRoleRequirement {
+    /** Name of the request parameter (path, then query) carrying the organization id. */
+    readonly parameter: string;
+    /** Accepted membership roles. Empty means "any member". */
+    readonly roles: readonly OrganizationMembershipRoleType[];
+    /** Whether platform admins satisfy the requirement without membership (default true). */
+    readonly adminBypass?: boolean;
+}
+/**
+ * What a caller must present / be to invoke an operation. Represented in
+ * the OpenAPI document both as the standard `security` requirement list
+ * (one entry per accepted scheme, carrying the scopes) and as the
+ * `x-schemavaults-auth` vendor extension so docs can show the route guard
+ * and organization role in addition to the scopes.
+ */
+export interface AuthRequirements {
+    /** Schemes accepted for this operation (any one of them satisfies it). */
+    readonly schemes: readonly AuthSchemeDefinition[];
+    /** Who may call once authenticated. Defaults to "authenticated". */
+    readonly routeGuard?: RouteGuardType;
+    /**
+     * Scopes the presented token's `scope` claim must include. A token with no
+     * scope claim grants no scopes, so any non-empty list denies it (403).
+     * There is no admin bypass: scopes describe what the TOKEN was granted.
+     */
+    readonly requiredScopes?: readonly string[];
+    /** Organization membership requirement resolved from a request parameter. */
+    readonly organization?: OrganizationRoleRequirement;
+    /** Free-form note for the docs ("only the app owner may ...", ...). */
+    readonly notes?: string;
+}
+export interface PublicOperationAuth {
+    readonly type: "public";
+    readonly notes?: string;
+}
+export interface RequiredOperationAuth extends AuthRequirements {
+    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;
+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">;
+/**
+ * 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">;
+/** 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">;
+/** OAuth 2.0 `client_secret_basic` client authentication (RFC 6749 §2.3.1). */
+export declare const oidcClientSecretBasicScheme: AuthSchemeDefinition<"oidc-client-secret-basic">;
+/** OAuth 2.0 `client_secret_post` client authentication (credentials in the form body). */
+export declare const oidcClientSecretPostScheme: AuthSchemeDefinition<"oidc-client-secret-post">;
+/** 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

@@ -0,0 +1,125 @@
+export function defineAuthScheme(definition) {
+    if (typeof definition.name !== "string" || definition.name.length === 0) {
+        throw new TypeError("An auth scheme needs a non-empty name");
+    }
+    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)`);
+    }
+    return Object.freeze({ ...definition });
+}
+/**
+ * Route guard levels mirroring `@schemavaults/auth-server-sdk`'s
+ * `withAuthenticatedApiRouteGuard` / `withAdminApiRouteGuard`.
+ */
+export const ROUTE_GUARD_TYPES = ["authenticated", "admin"];
+/** Marks an operation as callable without credentials. */
+export function publicAccess(notes) {
+    return notes === undefined ? { type: "public" } : { type: "public", notes };
+}
+/** Marks an operation as requiring one of the given schemes (+ extra checks). */
+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");
+    }
+    const names = new Set();
+    for (const scheme of requirements.schemes) {
+        if (names.has(scheme.name)) {
+            throw new TypeError(`Auth scheme "${scheme.name}" listed twice`);
+        }
+        names.add(scheme.name);
+    }
+    return {
+        type: "required",
+        ...requirements,
+        routeGuard: requirements.routeGuard ?? "authenticated",
+    };
+}
+export function isPublicOperationAuth(auth) {
+    return auth.type === "public";
+}
+// ---------------------------------------------------------------------------
+// Built-in SchemaVaults schemes
+// ---------------------------------------------------------------------------
+/** `Authorization: Bearer <access token>` issued by the SchemaVaults 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>`.",
+    securityScheme: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT",
+        description: "Access token issued by the SchemaVaults auth server for this API server.",
+    },
+    challenge: 'Bearer realm="schemavaults"',
+});
+/**
+ * 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 function schemaVaultsAccessTokenCookieScheme(cookieName) {
+    return defineAuthScheme({
+        name: "schemavaults-access-token-cookie",
+        title: "SchemaVaults 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.",
+        },
+    });
+}
+/** The auth server's own refresh-token cookie (only meaningful ON the auth server). */
+export function schemaVaultsRefreshTokenCookieScheme(cookieName) {
+    return defineAuthScheme({
+        name: "schemavaults-refresh-token-cookie",
+        title: "SchemaVaults 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",
+            in: "cookie",
+            name: cookieName,
+            description: "Auth server session cookie.",
+        },
+    });
+}
+/** OAuth 2.0 `client_secret_basic` client authentication (RFC 6749 §2.3.1). */
+export const oidcClientSecretBasicScheme = defineAuthScheme({
+    name: "oidc-client-secret-basic",
+    title: "OAuth 2.0 client credentials (HTTP Basic)",
+    description: "Confidential client authentication: `Authorization: Basic base64(client_id:client_secret)` (client_secret_basic).",
+    securityScheme: {
+        type: "http",
+        scheme: "basic",
+        description: "client_secret_basic — RFC 6749 §2.3.1",
+    },
+    challenge: 'Basic realm="schemavaults"',
+});
+/** OAuth 2.0 `client_secret_post` client authentication (credentials in the form body). */
+export const oidcClientSecretPostScheme = defineAuthScheme({
+    name: "oidc-client-secret-post",
+    title: "OAuth 2.0 client credentials (form body)",
+    description: "Confidential client authentication with `client_id` and `client_secret` in the `application/x-www-form-urlencoded` body (client_secret_post).",
+    securityScheme: {
+        type: "apiKey",
+        in: "header",
+        name: "X-SchemaVaults-Client-Secret-Post",
+        description: "Documentation placeholder: credentials travel in the form body as client_id/client_secret (client_secret_post, RFC 6749 §2.3.1).",
+    },
+});
+/** A static API key in a header (e.g. cron / internal automation). */
+export function apiKeyHeaderScheme(name, headerName, description) {
+    return defineAuthScheme({
+        name,
+        title: `API key (${headerName})`,
+        description: description ?? `A pre-shared API key sent in the \`${headerName}\` header.`,
+        securityScheme: {
+            type: "apiKey",
+            in: "header",
+            name: headerName,
+        },
+    });
+}
+//# sourceMappingURL=auth-scheme.js.map

package/dist/auth-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-scheme.js","sourceRoot":"","sources":["../src/auth-scheme.ts"],"names":[],"mappings":"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"}

package/dist/http-method.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTTP methods an operation can be declared with. Lower-case to match the
+ * OpenAPI `paths` object keys; adapters upper-case them for routing.
+ */
+export declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete", "head", "options"];
+export type HttpMethod = (typeof HTTP_METHODS)[number];
+export declare function isHttpMethod(value: unknown): value is HttpMethod;
+export declare const HTTP_METHODS_WITH_REQUEST_BODY: ReadonlySet<HttpMethod>;

package/dist/http-method.js

@@ -0,0 +1,24 @@
+/**
+ * HTTP methods an operation can be declared with. Lower-case to match the
+ * OpenAPI `paths` object keys; adapters upper-case them for routing.
+ */
+export const HTTP_METHODS = [
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+];
+export function isHttpMethod(value) {
+    return (typeof value === "string" &&
+        HTTP_METHODS.includes(value));
+}
+export const HTTP_METHODS_WITH_REQUEST_BODY = new Set([
+    "post",
+    "put",
+    "patch",
+    "delete",
+]);
+//# sourceMappingURL=http-method.js.map

package/dist/http-method.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-method.js","sourceRoot":"","sources":["../src/http-method.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK;IACL,MAAM;IACN,KAAK;IACL,OAAO;IACP,QAAQ;IACR,MAAM;IACN,SAAS;CACD,CAAC;AAIX,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACxB,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CACpD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,8BAA8B,GAA4B,IAAI,GAAG,CAAa;IACzF,MAAM;IACN,KAAK;IACL,OAAO;IACP,QAAQ;CACT,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export { z } from "./zod-openapi";
+export type { ZodType, ZodObject } 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 { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, } 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 { buildOpenApiDocument, collectAuthSchemes, toRouteConfig, toSecuritySchemeComponent, } from "./openapi/build-openapi-document";
+export type { BuildOpenApiDocumentOptions } from "./openapi/build-openapi-document";
+export { SCHEMAVAULTS_AUTH_EXTENSION, SCHEMAVAULTS_SCHEME_TITLE_EXTENSION, SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION, toSchemaVaultsAuthExtension, isSchemaVaultsAuthExtension, } from "./openapi/extensions";
+export type { SchemaVaultsAuthExtension } from "./openapi/extensions";
+export { extractPathParameterNames, openApiPathToHonoPath, honoPathToOpenApiPath, isOpenApiPath, } from "./openapi/path-format";
+export * from "./runtime";
+export type { Hono, Context as HonoContext } from "hono";
+export { getCookie, getSignedCookie } from "hono/cookie";
+export { toVercelHandler } from "./adapters/vercel";
+export type { VercelFunctionHandler } from "./adapters/vercel";
+export { toNextRouteHandlers } from "./adapters/nextjs";
+export type { NextRouteHandler, NextRouteHandlers } from "./adapters/nextjs";

package/dist/index.js

@@ -0,0 +1,12 @@
+export { z } 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 { defineOperation, createOperationDefiner, defineOperationGroup, defaultOperationId, assertUniqueOperations, } from "./operation";
+export { buildOpenApiDocument, collectAuthSchemes, toRouteConfig, toSecuritySchemeComponent, } from "./openapi/build-openapi-document";
+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";
+export { getCookie, getSignedCookie } from "hono/cookie";
+export { toVercelHandler } from "./adapters/vercel";
+export { toNextRouteHandlers } from "./adapters/nextjs";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAGlC,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,GACvB,MAAM,aAAa,CAAC;AAsBrB,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,aAAa,EACb,yBAAyB,GAC1B,MAAM,kCAAkC,CAAC;AAE1C,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/openapi/build-openapi-document.d.ts

@@ -0,0 +1,27 @@
+import { type RouteConfig } from "@asteasolutions/zod-to-openapi";
+import type { ExternalDocumentationObject, InfoObject, OpenAPIObject, SecuritySchemeObject, ServerObject, TagObject } from "openapi3-ts/oas31";
+import type { AuthSchemeDefinition } from "../auth-scheme";
+import type { AnyOperationDefinition } from "../operation";
+export interface BuildOpenApiDocumentOptions {
+    readonly info: InfoObject;
+    readonly operations: readonly AnyOperationDefinition[];
+    readonly servers?: readonly ServerObject[];
+    /** Tag descriptions; tags used by operations but not listed here are added bare. */
+    readonly tags?: readonly TagObject[];
+    readonly externalDocs?: ExternalDocumentationObject;
+    /** Schemes to document even when no operation references them. */
+    readonly additionalAuthSchemes?: readonly AuthSchemeDefinition[];
+    /** Document-level vendor extensions. */
+    readonly extensions?: Readonly<Record<`x-${string}`, unknown>>;
+}
+/** Every distinct auth scheme referenced by the operations (first definition wins per name). */
+export declare function collectAuthSchemes(operations: readonly AnyOperationDefinition[], additional?: readonly AuthSchemeDefinition[]): AuthSchemeDefinition[];
+export declare function toSecuritySchemeComponent(scheme: AuthSchemeDefinition): SecuritySchemeObject;
+/** zod-to-openapi route config for one operation (also usable with `@hono/zod-openapi`). */
+export declare function toRouteConfig(operation: AnyOperationDefinition): RouteConfig;
+/**
+ * Builds an OpenAPI 3.1 document from operation definitions using
+ * `@asteasolutions/zod-to-openapi`. Zod schemas registered with
+ * `.openapi("RefId")` are emitted under `components.schemas`.
+ */
+export declare function buildOpenApiDocument(options: BuildOpenApiDocumentOptions): OpenAPIObject;