@lpdjs/firestore-repo-service 2.6.7 → 2.6.9

package/dist/servers/hono/index.d.cts

@@ -206,6 +206,52 @@ type AnyServicesContainer = ServicesContainer<Record<string, any>>;
 type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
 /** Where the validated payload comes from. */
 type PayloadSource = "json" | "query" | "form" | "param";
+/**
+ * Structured logger injected into every handler / interceptor / error-handler
+ * context. Implement it, or extend the package's `BaseLogger` and override its
+ * `write` hook to route to your sink (Firebase logger, pino, …).
+ *
+ * `error()` returns a correlation id so the same value can be both logged and
+ * returned to the client.
+ */
+interface Logger {
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    /** @returns a correlation id (e.g. to include in the HTTP error response). */
+    error(error: unknown, meta?: unknown): string;
+    debug(message: string, meta?: unknown): void;
+}
+/** Context passed to {@link ErrorHandler.handle}. */
+interface ErrorHandlerContext<TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> {
+    /** The thrown value (an `AppError`, a Zod {@link ValidationError}, …). */
+    error: unknown;
+    /** Hono request context — set status, read headers, build the response. */
+    c: Context<TEnv>;
+    /** Route metadata (read-only). */
+    route: AnyRouteDef;
+    /** Global DI services container. */
+    services: TServices;
+    /** Injected {@link Logger} when one was passed to the API, else `undefined`. */
+    logger?: Logger;
+}
+/**
+ * Cross-cutting error strategy — a class (or object) you pass to the API and
+ * that the server injects everywhere **and** applies automatically.
+ *
+ * Implement {@link ErrorHandler.handle} to map any thrown value to an HTTP
+ * `Response` (e.g. your `AppError` → status + localized body, plus structured
+ * logging with a correlation id). Return `null` to decline the error and let
+ * the built-in fallback (`ValidationError` envelope) / `onError` take over.
+ *
+ * Prefer extending the package's {@link BaseErrorHandler} (it already maps the
+ * built-in errors) and overriding its `mapError` / `logError` hooks. Pass it
+ * **per API** via `ApiConfig.errorHandler`, or once via the registry
+ * (`{ services, errorHandler }`); it is then available in every handler /
+ * interceptor context as `errorHandler` and auto-applied on any uncaught error.
+ */
+interface ErrorHandler<TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> {
+    handle(ctx: ErrorHandlerContext<TEnv, TServices>): Response | null | Promise<Response | null>;
+}
 /** Handler signature — receives a single typed context object. */
 type RouteHandler<TIn, TOut, TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> = (ctx: {
     /** Validated (and typed) request payload. `void` when no `input` schema is defined. */
@@ -218,6 +264,13 @@ type RouteHandler<TIn, TOut, TEnv extends Env = Env, TServices extends AnyServic
      * `services` option.
      */
     services: TServices;
+    /**
+     * Injected {@link ErrorHandler} when one was passed to the API, else
+     * `undefined`. Usually you just `throw` and let it apply automatically.
+     */
+    errorHandler?: ErrorHandler<TEnv, TServices>;
+    /** Injected {@link Logger} when one was passed to the API, else `undefined`. */
+    logger?: Logger;
 }) => Promise<TOut | Response> | TOut | Response;
 /**
  * One route declaration. Default-exported by every `routes.ts` file inside the
@@ -264,7 +317,7 @@ interface RouteDef<TIn extends z.ZodTypeAny | undefined = z.ZodTypeAny | undefin
     /** Mark the operation as deprecated in the generated spec. */
     deprecated?: boolean;
     /** Security requirements (operationId-level override). */
-    security?: Array<Record<string, string[]>>;
+    security?: SecurityRequirement[];
     /** The request handler. */
     handler: RouteHandler<TIn extends z.ZodTypeAny ? z.infer<TIn> : void, TOut extends z.ZodTypeAny ? z.infer<TOut> : unknown, TEnv>;
 }
@@ -374,13 +427,137 @@ type RouteInterceptor<TEnv extends Env = Env, TServices extends AnyServicesConta
     c: Context<TEnv>;
     /** Global DI services container. See {@link RouteHandler}. */
     services: TServices;
+    /**
+     * Injected {@link ErrorHandler} when one was passed to the API. Call
+     * `errorHandler?.handle({ error, c, route, services })` in your `catch` to
+     * reuse the shared mapping, or simply rethrow to let it apply automatically.
+     */
+    errorHandler?: ErrorHandler<TEnv, TServices>;
+    /** Injected {@link Logger} when one was passed to the API, else `undefined`. */
+    logger?: Logger;
 }) => Promise<Response | unknown> | Response | unknown;
+/**
+ * Success-envelope schema declared alongside an interceptor so the generated
+ * OpenAPI spec documents what the **wrapper actually returns** (not the raw
+ * handler output).
+ *
+ * - a **static** Zod schema → same envelope for every route (e.g.
+ *   `z.object({ data: z.any(), intercepted: z.boolean() })`);
+ * - a **factory** `(routeOutput) => schema` → wraps each route's own `output`,
+ *   so `data` is typed per endpoint in the docs.
+ */
+type InterceptorOutput = z.ZodTypeAny | ((routeOutput: z.ZodTypeAny | undefined) => z.ZodTypeAny);
+/** A single declared error response for the OpenAPI spec. */
+type InterceptorErrorResponse = z.ZodTypeAny | {
+    description?: string;
+    schema?: z.ZodTypeAny;
+};
+/**
+ * Structured interceptor — pairs the cross-cutting {@link RouteInterceptor}
+ * `handler` with the OpenAPI metadata describing what it returns, so the docs
+ * reflect the real wrapped responses (success envelope + error shapes).
+ *
+ * @example
+ * ```ts
+ * interceptor: {
+ *   // factory: `data` reflects each route's own output schema
+ *   output: (routeOutput) =>
+ *     z.object({ data: routeOutput ?? z.unknown(), intercepted: z.boolean() }),
+ *   errors: {
+ *     400: ValidationErrorSchema,
+ *     500: { description: "Internal", schema: ErrorSchema },
+ *   },
+ *   handler: async ({ c, next }) => {
+ *     const data = await next();
+ *     return c.json({ data, intercepted: true });
+ *   },
+ * }
+ * ```
+ */
+interface InterceptorConfig<TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> {
+    /** Success-envelope schema (static) or per-route factory. */
+    output?: InterceptorOutput;
+    /**
+     * Error responses applied to **every** operation, keyed by HTTP status. Pass
+     * a bare Zod schema or `{ description, schema }`.
+     */
+    errors?: Record<number, InterceptorErrorResponse>;
+    /** The interceptor function. See {@link RouteInterceptor}. */
+    handler: RouteInterceptor<TEnv, TServices>;
+}
+/**
+ * Interceptor option accepted by the server / registry — either a bare
+ * {@link RouteInterceptor} function (legacy) or a structured
+ * {@link InterceptorConfig} carrying OpenAPI metadata.
+ */
+type InterceptorOption<TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> = RouteInterceptor<TEnv, TServices> | InterceptorConfig<TEnv, TServices>;
 /** OpenAPI document info (subset of the spec used by the helper). */
 interface OpenAPIInfo {
     title: string;
     version: string;
     description?: string;
 }
+/** Fields shared by every security scheme. */
+interface SecuritySchemeBase {
+    /** Human-readable description (CommonMark). */
+    description?: string;
+}
+/** API key carried in a header, query param or cookie. */
+interface ApiKeySecurityScheme extends SecuritySchemeBase {
+    type: "apiKey";
+    /** Name of the header, query parameter or cookie. */
+    name: string;
+    /** Location of the API key. */
+    in: "query" | "header" | "cookie";
+}
+/**
+ * HTTP authentication (RFC 7235), e.g. `bearer` (Firebase ID tokens) or
+ * `basic`.
+ */
+interface HttpSecurityScheme extends SecuritySchemeBase {
+    type: "http";
+    /** Auth scheme name — `"bearer"`, `"basic"`, `"digest"`, … */
+    scheme: "bearer" | "basic" | "digest" | (string & {});
+    /** Hint for the bearer token format, e.g. `"JWT"` / `"Firebase JWT"`. */
+    bearerFormat?: string;
+}
+/** Mutual TLS authentication. */
+interface MutualTlsSecurityScheme extends SecuritySchemeBase {
+    type: "mutualTLS";
+}
+/** A single OAuth2 flow. */
+interface OAuthFlowObject {
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    refreshUrl?: string;
+    /** Available scopes → description. */
+    scopes: Record<string, string>;
+}
+/** The OAuth2 flows supported by an {@link OAuth2SecurityScheme}. */
+interface OAuthFlowsObject {
+    implicit?: OAuthFlowObject;
+    password?: OAuthFlowObject;
+    clientCredentials?: OAuthFlowObject;
+    authorizationCode?: OAuthFlowObject;
+}
+/** OAuth2 authentication. */
+interface OAuth2SecurityScheme extends SecuritySchemeBase {
+    type: "oauth2";
+    flows: OAuthFlowsObject;
+}
+/** OpenID Connect Discovery. */
+interface OpenIdConnectSecurityScheme extends SecuritySchemeBase {
+    type: "openIdConnect";
+    openIdConnectUrl: string;
+}
+/** OpenAPI 3.1 Security Scheme Object (discriminated on `type`). */
+type SecurityScheme = ApiKeySecurityScheme | HttpSecurityScheme | MutualTlsSecurityScheme | OAuth2SecurityScheme | OpenIdConnectSecurityScheme;
+/**
+ * A single Security Requirement Object: maps a scheme name (a key of
+ * {@link OpenAPIConfig.securitySchemes}) to the list of required scopes
+ * (empty `[]` for `http` / `apiKey`).
+ */
+type SecurityRequirement = Record<string, string[]>;
 /** OpenAPI configuration on the server. */
 interface OpenAPIConfig {
     /** Path served by the JSON spec (e.g. `/openapi.json`). Default: `/openapi.json`. */
@@ -394,10 +571,37 @@ interface OpenAPIConfig {
         url: string;
         description?: string;
     }[];
-    /** Optional security schemes (e.g. bearer auth). */
-    securitySchemes?: Record<string, unknown>;
-    /** Default security requirement applied to every operation. */
-    security?: Array<Record<string, string[]>>;
+    /**
+     * Reusable security schemes, keyed by name. The keys are referenced from
+     * {@link OpenAPIConfig.security} / per-route `security`.
+     *
+     * @example
+     * ```ts
+     * securitySchemes: {
+     *   bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "Firebase JWT" },
+     * }
+     * ```
+     */
+    securitySchemes?: Record<string, SecurityScheme>;
+    /**
+     * Default security requirement applied to every operation. Each entry maps a
+     * scheme name (a key of {@link OpenAPIConfig.securitySchemes}) to its scopes.
+     *
+     * @example `security: [{ bearerAuth: [] }]`
+     */
+    security?: SecurityRequirement[];
+    /**
+     * Hono middleware(s) guarding **only** the docs UI and JSON spec endpoints
+     * (not the API routes). Use a raw middleware for a custom flow, or the
+     * built-in {@link firebaseBearerAuth} / {@link basicAuth} helpers.
+     *
+     * @example
+     * ```ts
+     * import { firebaseBearerAuth } from "@lpdjs/firestore-repo-service/servers/hono";
+     * openapi: { info, docsAuth: firebaseBearerAuth({ getAuth }) }
+     * ```
+     */
+    docsAuth?: MiddlewareHandler | MiddlewareHandler[];
 }
 /** Options consumed by the {@link HonoServer} constructor. */
 interface HonoServerOptions<TEnv extends Env = Env> {
@@ -434,9 +638,27 @@ interface HonoServerOptions<TEnv extends Env = Env> {
     /**
      * Cross-cutting interceptor wrapping every handler call.
      * Ideal for response envelopes, business-error mapping, tracing.
-     * See {@link RouteInterceptor}.
+     *
+     * Pass a bare {@link RouteInterceptor} function, or an
+     * {@link InterceptorConfig} (`{ output?, errors?, handler }`) so the
+     * generated OpenAPI spec documents the wrapped responses.
+     */
+    interceptor?: InterceptorOption<TEnv>;
+    /**
+     * Cross-cutting error strategy applied to every uncaught error and injected
+     * into every handler / interceptor context. See {@link ErrorHandler}.
+     *
+     * Typically shared across APIs — pass it once to `createApiRegistry` via
+     * `{ services, errorHandler }`; this per-API field overrides it.
+     */
+    errorHandler?: ErrorHandler<TEnv>;
+    /**
+     * Structured {@link Logger} injected into every handler / interceptor /
+     * error-handler context. Extend the package's `BaseLogger` to route to your
+     * sink. Typically shared via `createApiRegistry({ services, logger })`; this
+     * per-API field overrides it.
      */
-    interceptor?: RouteInterceptor<TEnv>;
+    logger?: Logger;
     /**
      * Global DI services container (see {@link createServices}).
      *
@@ -645,6 +867,25 @@ type OnRequestFn = (...args: any[]) => any;
 type ApiConfig<TEnv extends Env = Env> = Omit<HonoServerOptions<TEnv>, "routes" | "api" | "services">;
 /** Map of API tag → its config. */
 type ApiConfigMap = Record<string, ApiConfig>;
+/**
+ * Per-key excess-property guard.
+ *
+ * `createApiRegistry` infers its config map generically (`<const TMap …>`),
+ * which normally **defeats** TypeScript's excess-property checking — a typo
+ * like `openApi` or `middleware` (instead of `openapi` / `middlewares`) would
+ * pass silently and the option would be ignored at runtime.
+ *
+ * This intersects the concrete {@link ApiConfig} shape (so every known key
+ * keeps its real type **and JSDoc**, including nested objects such as
+ * `openapi`) with a `never` mapping for any key absent from `ApiConfig` — which
+ * makes typos a compile error, matching the strictness already enforced on the
+ * CRUD server's `openapi`.
+ *
+ * @internal
+ */
+type StrictApiConfig<T, TEnv extends Env = Env> = ApiConfig<TEnv> & {
+    [K in keyof T as K extends keyof ApiConfig<TEnv> ? never : K]: never;
+};
 /**
  * Options accepted by {@link createApiRegistry} alongside the per-API
  * configs.
@@ -657,6 +898,18 @@ interface ApiRegistryOptions<TServices extends AnyServicesContainer = AnyService
      * `services` to every handler / interceptor.
      */
     services?: TServices;
+    /**
+     * Cross-cutting {@link ErrorHandler} shared across every API — injected into
+     * every handler / interceptor context and applied automatically on any
+     * uncaught error. A per-API `errorHandler` (on the config) overrides it.
+     */
+    errorHandler?: ErrorHandler;
+    /**
+     * Structured {@link Logger} shared across every API — injected into every
+     * handler / interceptor / error-handler context. A per-API `logger` (on the
+     * config) overrides it.
+     */
+    logger?: Logger;
 }
 interface ApiRegistry<TMap extends ApiConfigMap, TServices extends AnyServicesContainer = AnyServicesContainer> {
     /** The registered configs (read-only). */
@@ -710,10 +963,16 @@ interface ApiRegistry<TMap extends ApiConfigMap, TServices extends AnyServicesCo
  * Factory — declare every API tag once and get back a typed `defineRoute`
  * + `toFunctions`. See the file-level example.
  *
- * @param configs  API-tag → per-API config.
+ * Each per-API config is strictly checked against {@link ApiConfig}: unknown
+ * keys (typos like `openApi` / `middleware`) are rejected at compile time,
+ * including nested objects such as `openapi` — mirroring the CRUD server.
+ *
+ * @param configs  API-tag → per-API config (see {@link ApiConfig}).
  * @param options  Cross-API options (shared services container, etc).
  */
-declare function createApiRegistry<const TMap extends ApiConfigMap, TServices extends AnyServicesContainer = AnyServicesContainer>(configs: TMap, options?: ApiRegistryOptions<TServices>): ApiRegistry<TMap, TServices>;
+declare function createApiRegistry<const TMap extends ApiConfigMap, TServices extends AnyServicesContainer = AnyServicesContainer>(configs: {
+    [K in keyof TMap]: StrictApiConfig<TMap[K]>;
+}, options?: ApiRegistryOptions<TServices>): ApiRegistry<TMap, TServices>;
 
 /**
  * OpenAPI 3.1 spec generator from {@link RouteDef} entries.
@@ -723,13 +982,213 @@ declare function createApiRegistry<const TMap extends ApiConfigMap, TServices ex
  */
 
 /** Build the OpenAPI document from the mounted route registry. */
-declare function buildOpenApiDocument(routes: AnyRouteDef[], basePath: string, config: OpenAPIConfig): Record<string, unknown>;
+declare function buildOpenApiDocument(routes: AnyRouteDef[], basePath: string, config: OpenAPIConfig, interceptor?: InterceptorConfig): Record<string, unknown>;
 /**
  * Render a self-contained Scalar API Reference HTML page that points to the
  * generated spec. Loaded from CDN — no build step required.
  */
 declare function renderDocsHtml(specUrl: string, title: string): string;
 
+/**
+ * `BaseErrorHandler` — the package's ready-to-use {@link ErrorHandler}.
+ *
+ * Use it as-is for an API that only needs the built-in error mapping
+ * (`ValidationError` / `BadRequestError` / `OutputValidationError`), or extend
+ * it and override the two hooks to plug your own domain errors + logger:
+ *
+ * - {@link BaseErrorHandler.mapError} — map your `AppError` → `Response`
+ *   (return `null` to defer to the built-in mapping);
+ * - {@link BaseErrorHandler.logError} — log via your `AppLogger`.
+ *
+ * Pass an instance **per API** (`ApiConfig.errorHandler`) so different APIs can
+ * use different strategies (e.g. one with user-facing localized errors, one
+ * with just the defaults).
+ *
+ * @example
+ * ```ts
+ * class AppErrorHandler extends BaseErrorHandler {
+ *   protected mapError({ error, c }) {
+ *     if (error instanceof AppError) {
+ *       return c.json({ error: error.message, errorId: error.errorId }, error.statusCode);
+ *     }
+ *     return null; // → built-in mapping
+ *   }
+ *   protected logError({ error }) {
+ *     AppLogger.err(error);
+ *   }
+ * }
+ *
+ * // apis.ts
+ * v1: { ..., errorHandler: new AppErrorHandler() },  // user-facing API
+ * v2: { ..., errorHandler: new BaseErrorHandler() }, // defaults only
+ * ```
+ */
+
+declare class BaseErrorHandler<TEnv extends Env = Env, TServices extends AnyServicesContainer = AnyServicesContainer> implements ErrorHandler<TEnv, TServices> {
+    /**
+     * Orchestration — not meant to be overridden. Tries the user mapping first,
+     * logs it when matched, then falls back to the built-in mapping.
+     */
+    handle(ctx: ErrorHandlerContext<TEnv, TServices>): Promise<Response | null>;
+    /**
+     * Map a domain error (your `AppError`) to a `Response`. Return `null` to let
+     * {@link BaseErrorHandler.handleBuiltin} handle it. Default: `null`.
+     */
+    protected mapError(_ctx: ErrorHandlerContext<TEnv, TServices>): Response | null | Promise<Response | null>;
+    /**
+     * Log a mapped error (e.g. via your `AppLogger`). Called only when
+     * {@link BaseErrorHandler.mapError} produced a response. Default: no-op.
+     */
+    protected logError(_ctx: ErrorHandlerContext<TEnv, TServices>, _response: Response): void;
+    /**
+     * Built-in mapping of the package's own errors (`ValidationError`,
+     * `BadRequestError`, `OutputValidationError`). Returns `null` for unknown
+     * errors so they bubble to `onError` / Hono.
+     */
+    protected handleBuiltin(ctx: ErrorHandlerContext<TEnv, TServices>): Response | null;
+}
+
+/**
+ * `BaseLogger` — the package's ready-to-use {@link Logger}.
+ *
+ * Use it as-is (writes structured JSON to `console`), or extend it and override
+ * the single {@link BaseLogger.write} hook to route to your sink (Firebase
+ * `logger`, pino, Datadog, …). Each level funnels through `write`, so one
+ * override covers them all.
+ *
+ * Pass an instance **per API** (`ApiConfig.logger`) or once via the registry
+ * (`createApiRegistry({ services, logger })`); it is then injected into every
+ * handler / interceptor / error-handler context as `logger`.
+ *
+ * @example
+ * ```ts
+ * import { logger as fnLogger } from "firebase-functions/v2";
+ * class AppLogger extends BaseLogger {
+ *   protected write(severity, payload) {
+ *     fnLogger.write({ severity, ...payload });
+ *   }
+ * }
+ * ```
+ */
+
+type LogSeverity = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+declare class BaseLogger implements Logger {
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    debug(message: string, meta?: unknown): void;
+    /**
+     * Log an error and return a correlation id. If the error already carries an
+     * `errorId` it is reused, otherwise a fresh one is generated.
+     */
+    error(error: unknown, meta?: unknown): string;
+    /** Build a structured payload from a message + optional metadata. */
+    protected payload(message: string, meta?: unknown): Record<string, unknown>;
+    /**
+     * Sink hook — override to route logs elsewhere. Default: structured
+     * `console` write keyed by severity.
+     */
+    protected write(severity: LogSeverity, payload: Record<string, unknown>): void;
+    /** Reuse an error's `errorId` when present, else generate one. */
+    protected static errorId(error: unknown): string;
+}
+
+/**
+ * Built-in error types thrown by the server pipeline and their default
+ * HTTP mapping — shared by the request handler and {@link BaseErrorHandler}.
+ */
+
+/** Thrown when the request body cannot be read / parsed → HTTP 400. */
+declare class BadRequestError extends Error {
+    readonly statusCode: 400;
+    constructor(message: string);
+}
+/** Thrown when a handler's return value fails the `output` schema → HTTP 500. */
+declare class OutputValidationError extends Error {
+    readonly zodError: ZodError;
+    readonly statusCode: 500;
+    constructor(zodError: ZodError);
+}
+/**
+ * Default JSON mapping for the package's own errors (`ValidationError`,
+ * `BadRequestError`, `OutputValidationError`). Returns `null` for anything
+ * else so the caller can decide (rethrow / custom handler).
+ */
+declare function defaultErrorResponse(c: any, err: unknown): Response | null;
+
+/**
+ * Hono-native auth guards for the OpenAPI docs / spec endpoints.
+ *
+ * These return plain Hono `MiddlewareHandler`s, so they slot into
+ * `OpenAPIConfig.docsAuth` (which protects only `/docs` + `/openapi.json`,
+ * never the API routes). For a fully custom flow, pass your own middleware
+ * instead of these helpers.
+ */
+
+/** Decoded token shape — kept minimal to avoid a hard firebase-admin import. */
+interface DecodedBearerToken {
+    uid: string;
+    email?: string;
+    [claim: string]: any;
+}
+/** Minimal Firebase Admin Auth surface used by {@link firebaseBearerAuth}. */
+interface FirebaseBearerAuthLike {
+    verifyIdToken(idToken: string, checkRevoked?: boolean): Promise<DecodedBearerToken>;
+}
+/** Options for {@link firebaseBearerAuth}. */
+interface FirebaseBearerAuthOptions {
+    /**
+     * Returns the Firebase Admin Auth instance, e.g. `() => getAuth()`. Called
+     * lazily on each request so `initializeApp()` runs first.
+     */
+    getAuth: () => FirebaseBearerAuthLike;
+    /**
+     * Authorization policy. Return `false` (or throw) to reject the request,
+     * any truthy value to allow. Defaults to allowing any verified token.
+     */
+    allow?: (token: DecodedBearerToken) => boolean | Promise<boolean>;
+    /** Revoke check passed to `verifyIdToken`. Default: `false`. */
+    checkRevoked?: boolean;
+    /**
+     * Context key under which the decoded token is stored (`c.set(key, token)`)
+     * for downstream handlers. Default: `"docsUser"`.
+     */
+    contextKey?: string;
+}
+/**
+ * Guard the docs / spec endpoints with a Firebase ID token (Bearer scheme).
+ *
+ * @example
+ * ```ts
+ * import { getAuth } from "firebase-admin/auth";
+ * import { firebaseBearerAuth } from "@lpdjs/firestore-repo-service/servers/hono";
+ *
+ * openapi: {
+ *   info,
+ *   docsAuth: firebaseBearerAuth({
+ *     getAuth: () => getAuth(),
+ *     allow: (t) => t.admin === true,
+ *   }),
+ * }
+ * ```
+ */
+declare function firebaseBearerAuth(options: FirebaseBearerAuthOptions): MiddlewareHandler;
+/** Options for {@link basicAuth}. */
+interface BasicAuthOptions {
+    username: string;
+    password: string;
+    /** Realm advertised in the `WWW-Authenticate` header. Default: `"Docs"`. */
+    realm?: string;
+}
+/**
+ * Guard the docs / spec endpoints with HTTP Basic Auth.
+ *
+ * @example
+ * ```ts
+ * openapi: { info, docsAuth: basicAuth({ username: "admin", password: "secret" }) }
+ * ```
+ */
+declare function basicAuth(options: BasicAuthOptions): MiddlewareHandler;
+
 /**
  * URL path inference from filesystem layout.
  *
@@ -828,4 +1287,4 @@ declare function generateRoutesManifest(routes: ScannedRoute[], opts: GeneratorO
 /** Convenience helper used by the CLI — combines scan + generate in one call. */
 declare function generateFromRoot(rootAbs: string, outFileRel: string, derive: PathDeriveOptions, importExtension: string, scan: (root: string) => ScannedRoute[]): GenerationResult;
 
-export { type AnyRouteDef, type AnyServicesContainer, type ApiConfig, type ApiConfigMap, type ApiRegistry, type ApiRegistryOptions, DEFAULT_DERIVE, DEFAULT_GENERATOR_BANNER, DEFAULT_SCANNER, type GenerationResult, type GeneratorOptions, HonoServer, type HonoServerOptions, type HttpMethod, type OpenAPIConfig, type OpenAPIInfo, type PathDeriveOptions, type PayloadSource, type RequestContext, type RouteDef, type RouteHandler, type RouteInput, type RouteInterceptor, type RouteModuleDefault, type RouteOutput, type RoutesUnion, type ScannedRoute, type ScannerOptions, type ServiceProvider, type ServiceProviderMap, type ServicesContainer, type ServicesOf, UseCase, type UseCaseClass, type UseCaseRouteMeta, ValidationError, buildOpenApiDocument, createApiRegistry, createRequestContextMiddleware, createServices, defineRoutes, derivePath, generateFromRoot, generateRoutesManifest, renderDocsHtml, scanRoutes, toImportSpecifier, useCaseRoute, withRequestContext };
+export { type AnyRouteDef, type AnyServicesContainer, type ApiConfig, type ApiConfigMap, type ApiKeySecurityScheme, type ApiRegistry, type ApiRegistryOptions, BadRequestError, BaseErrorHandler, BaseLogger, type BasicAuthOptions, DEFAULT_DERIVE, DEFAULT_GENERATOR_BANNER, DEFAULT_SCANNER, type DecodedBearerToken, type ErrorHandler, type ErrorHandlerContext, type FirebaseBearerAuthLike, type FirebaseBearerAuthOptions, type GenerationResult, type GeneratorOptions, HonoServer, type HonoServerOptions, type HttpMethod, type HttpSecurityScheme, type InterceptorConfig, type InterceptorErrorResponse, type InterceptorOption, type InterceptorOutput, type LogSeverity, type Logger, type MutualTlsSecurityScheme, type OAuth2SecurityScheme, type OAuthFlowObject, type OAuthFlowsObject, type OpenAPIConfig, type OpenAPIInfo, type OpenIdConnectSecurityScheme, OutputValidationError, type PathDeriveOptions, type PayloadSource, type RequestContext, type RouteDef, type RouteHandler, type RouteInput, type RouteInterceptor, type RouteModuleDefault, type RouteOutput, type RoutesUnion, type ScannedRoute, type ScannerOptions, type SecurityRequirement, type SecurityScheme, type SecuritySchemeBase, type ServiceProvider, type ServiceProviderMap, type ServicesContainer, type ServicesOf, UseCase, type UseCaseClass, type UseCaseRouteMeta, ValidationError, basicAuth, buildOpenApiDocument, createApiRegistry, createRequestContextMiddleware, createServices, defaultErrorResponse, defineRoutes, derivePath, firebaseBearerAuth, generateFromRoot, generateRoutesManifest, renderDocsHtml, scanRoutes, toImportSpecifier, useCaseRoute, withRequestContext };