@darthcav/ts-http-server 0.5.0 → 0.6.0

package/dist/types.d.ts

@@ -10,17 +10,50 @@ export type FSTPlugin = {
     /** Optional options forwarded to the plugin on registration. */
     opts?: FastifyPluginOptions;
 };
+/**
+ * Configuration for Keycloak-backed JWT authentication.
+ */
+export type KeycloakAuthConfig = {
+    /** Keycloak server base URL, e.g. `https://auth.example.com`. */
+    url: string;
+    /** Keycloak realm name. */
+    realm: string;
+    /** Client ID registered in the realm; used as the expected audience. */
+    clientId: string;
+    /** Client secret for the registered client. */
+    clientSecret: string;
+};
+/**
+ * Async function that verifies a bearer token from the `Authorization` header.
+ *
+ * Return `true` to allow the request, `false` to reject it with the default
+ * 401 response, or throw to surface a custom error.
+ */
+export type TokenVerifier = (authorizationHeader: string | undefined) => Promise<boolean>;
 /**
  * Application locals decorated onto the Fastify instance and available
  * throughout the request lifecycle.
  */
 export type LauncherLocals = {
     /** Package metadata (e.g. contents of `package.json`). */
-    pkg?: object;
+    pkg?: Record<string, unknown>;
     /** Hostname the server will bind to. */
     host?: string;
     /** Port the server will listen on. */
     port?: number;
+    /**
+     * Glob patterns (picomatch) for routes that require bearer-token
+     * authentication via the `verifyToken` Fastify decorator.
+     * When `undefined` or empty, authentication is disabled.
+     *
+     * Example: `["/api/**"]`
+     */
+    authPaths?: string[];
+    /**
+     * Protection-space label used in the `WWW-Authenticate` challenge (RFC 6750).
+     * Typically the Keycloak realm name. Defaults to `"api"` when omitted.
+     */
+    authRealm?: string;
     /** Any additional application-specific locals. */
     [key: string]: unknown;
 };
@@ -38,9 +71,39 @@ export type LauncherOptions = {
     routes: Map<string, RouteOptions>;
     /** Map of named decorators to add to the Fastify instance. */
     decorators?: Map<string, unknown>;
+    /**
+     * Token verifier registered as the `verifyToken` Fastify decorator.
+     *
+     * When omitted and `locals.authPaths` is set, all protected routes will
+     * respond with `401 Unauthorized`.
+     */
+    verifyToken?: TokenVerifier;
     /** Optional Fastify server options (merged over {@link defaultFastifyOptions}). */
     opts?: FastifyServerOptions;
     /** Optional callback invoked once the server is listening. */
     done?: () => void;
 };
+/**
+ * Options accepted by the {@link defaultPlugins} function.
+ */
+export type DefaultPluginsOptions = {
+    /** Application locals; `locals.pkg` is exposed as the default EJS context. */
+    locals: LauncherLocals;
+    /** Optional base directory for resolving the `src/` folder; defaults to the parent of `import.meta.dirname`. */
+    baseDir?: string | null;
+    /** Optional Keycloak configuration used to mark the generated `/api/` OpenAPI operations as OpenID Connect–protected. */
+    keycloakAuth?: KeycloakAuthConfig;
+};
+/**
+ * Fastify module augmentation that exposes {@link LauncherLocals} and the
+ * {@link TokenVerifier} as first-class decorators on every `FastifyInstance`.
+ *
+ * Both are registered in {@link launcher} via `fastify.decorate(...)`.
+ */
+declare module "fastify" {
+    interface FastifyInstance {
+        locals: LauncherLocals;
+        verifyToken: TokenVerifier;
+    }
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EACR,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACf,MAAM,SAAS,CAAA;AAEhB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB,+CAA+C;IAE/C,MAAM,EAAE,qBAAqB,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC5D,gEAAgE;IAChE,IAAI,CAAC,EAAE,oBAAoB,CAAA;CAC9B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IACzB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC1B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,MAAM,EAAE,cAAc,CAAA;IACtB,wCAAwC;IACxC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC/B,uCAAuC;IACvC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACjC,8DAA8D;IAC9D,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,mFAAmF;IACnF,IAAI,CAAC,EAAE,oBAAoB,CAAA;IAC3B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EACR,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,YAAY,EACf,MAAM,SAAS,CAAA;AAEhB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACpB,+CAA+C;IAE/C,MAAM,EAAE,qBAAqB,CAAC,GAAG,CAAC,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC5D,gEAAgE;IAChE,IAAI,CAAC,EAAE,oBAAoB,CAAA;CAC9B,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAA;IACX,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CACxB,mBAAmB,EAAE,MAAM,GAAG,SAAS,KACtC,OAAO,CAAC,OAAO,CAAC,CAAA;AAErB;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IACzB,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kDAAkD;IAClD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACzB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC1B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,MAAM,EAAE,cAAc,CAAA;IACtB,wCAAwC;IACxC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC/B,uCAAuC;IACvC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACjC,8DAA8D;IAC9D,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,aAAa,CAAA;IAC3B,mFAAmF;IACnF,IAAI,CAAC,EAAE,oBAAoB,CAAA;IAC3B,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,IAAI,CAAA;CACpB,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAChC,8EAA8E;IAC9E,MAAM,EAAE,cAAc,CAAA;IACtB,gHAAgH;IAChH,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,yHAAyH;IACzH,YAAY,CAAC,EAAE,kBAAkB,CAAA;CACpC,CAAA;AAED;;;;;GAKG;AACH,OAAO,QAAQ,SAAS,CAAC;IACrB,UAAU,eAAe;QACrB,MAAM,EAAE,cAAc,CAAA;QACtB,WAAW,EAAE,aAAa,CAAA;KAC7B;CACJ"}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@darthcav/ts-http-server",
     "description": "A TypeScript HTTP server for Node.js >= 25",
-    "version": "0.5.0",
+    "version": "0.6.0",
     "author": {
         "name": "darthcav",
         "url": "https://github.com/darthcav"
@@ -30,18 +30,25 @@
         "@fastify/etag": "6.1.0",
         "@fastify/helmet": "13.0.2",
         "@fastify/static": "9.0.0",
+        "@fastify/swagger": "9.7.0",
+        "@fastify/swagger-ui": "5.2.5",
         "@fastify/view": "11.1.1",
         "@hapi/boom": "10.0.1",
         "@logtape/fastify": "2.0.5",
         "@logtape/logtape": "2.0.5",
         "ejs": "5.0.1",
-        "fastify": "5.8.4"
+        "fastify": "5.8.4",
+        "jose": "6.2.2",
+        "picomatch": "4.0.4",
+        "yaml": "2.8.3"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.4.9",
+        "@biomejs/biome": "2.4.10",
         "@types/ejs": "3.1.5",
         "@types/node": "25.5.0",
+        "@types/picomatch": "4.0.2",
         "asserttt": "1.0.1",
+        "openapi-types": "12.1.3",
         "prettier": "3.8.1",
         "shx": "0.4.0",
         "typedoc": "0.28.18"

package/src/auth/keycloak.ts

@@ -0,0 +1,43 @@
+import { createRemoteJWKSet, jwtVerify } from "jose"
+import type { KeycloakAuthConfig, TokenVerifier } from "../types.ts"
+
+/**
+ * Creates a JWT token verifier backed by a Keycloak realm's JWKS endpoint.
+ *
+ * The JWKS keys are fetched lazily on the first verification request and
+ * cached; key rotation is handled automatically by `jose`.
+ *
+ * The verifier extracts the bearer token from the `Authorization` header,
+ * verifies the JWT signature against the realm's public keys, and validates
+ * the issuer claim. Any verification failure returns `false` without throwing.
+ *
+ * @param config - Keycloak realm and client configuration.
+ * @returns An async {@link TokenVerifier} that returns `true` if the bearer
+ * JWT is valid, `false` otherwise.
+ */
+export function createKeycloakVerifier(
+    config: KeycloakAuthConfig,
+): TokenVerifier {
+    const baseUrl = config.url.replace(/\/$/, "")
+    const jwksUri = new URL(
+        `/realms/${config.realm}/protocol/openid-connect/certs`,
+        baseUrl,
+    )
+    const JWKS = createRemoteJWKSet(jwksUri)
+    const issuer = `${baseUrl}/realms/${config.realm}`
+
+    return async function verifyToken(
+        authorizationHeader: string | undefined,
+    ): Promise<boolean> {
+        if (!authorizationHeader?.startsWith("Bearer ")) {
+            return false
+        }
+        const token = authorizationHeader.slice(7)
+        try {
+            await jwtVerify(token, JWKS, { issuer })
+            return true
+        } catch {
+            return false
+        }
+    }
+}

package/src/defaults/defaultPlugins.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs"
 import { join } from "node:path"
 import FastifyAccepts from "@fastify/accepts"
 import FastifyCompress from "@fastify/compress"
@@ -5,32 +6,137 @@ import FastifyCors from "@fastify/cors"
 import FastifyEtag from "@fastify/etag"
 import FastifyHelmet from "@fastify/helmet"
 import FastifyStatic from "@fastify/static"
+import FastifySwagger from "@fastify/swagger"
+import FastifySwaggerUi from "@fastify/swagger-ui"
 import FastifyView from "@fastify/view"
 import Ejs from "ejs"
-import type { FSTPlugin, LauncherLocals } from "../types.ts"
+import type { OpenAPIV3_1 } from "openapi-types"
+import { parse } from "yaml"
+import type {
+    DefaultPluginsOptions,
+    FSTPlugin,
+    KeycloakAuthConfig,
+} from "../types.ts"
+
+function configureApiDocumentAuth(
+    apiDoc: OpenAPIV3_1.Document,
+    keycloakAuth?: KeycloakAuthConfig,
+): void {
+    if (!apiDoc.paths) {
+        return
+    }
+
+    const apiPath = apiDoc.paths["/api/"]
+    if (!apiPath) {
+        return
+    }
+
+    if (keycloakAuth) {
+        const baseUrl = keycloakAuth.url.replace(/\/$/, "")
+        const openIdConnectUrl = `${baseUrl}/realms/${keycloakAuth.realm}/.well-known/openid-configuration`
+
+        apiDoc.components ??= {}
+        apiDoc.components.securitySchemes = {
+            openIdConnect: {
+                type: "openIdConnect",
+                openIdConnectUrl,
+            },
+        }
+        apiDoc.security = [{ openIdConnect: [] }]
+
+        for (const operation of Object.values(apiPath)) {
+            if (
+                !operation ||
+                typeof operation !== "object" ||
+                !("responses" in operation)
+            ) {
+                continue
+            }
+
+            operation.security = [{ openIdConnect: [] }]
+            operation.responses ??= {}
+            operation.responses["401"] = {
+                description: "Unauthorized",
+                content: {
+                    "application/json": {
+                        schema: { $ref: "#/components/schemas/Error" },
+                        examples: {
+                            "401": { $ref: "#/components/examples/http_401" },
+                        },
+                    },
+                },
+            }
+        }
+        return
+    }
+
+    delete apiDoc.security
+    if (apiDoc.components?.securitySchemes) {
+        delete apiDoc.components.securitySchemes["openIdConnect"]
+    }
+    for (const operation of Object.values(apiPath)) {
+        if (
+            !operation ||
+            typeof operation !== "object" ||
+            !("responses" in operation)
+        ) {
+            continue
+        }
+
+        delete operation.security
+        delete operation.responses?.["401"]
+    }
+}
 
 /**
  * Builds the default plugin map for use with `launcher`.
  *
  * Registers: `@fastify/accepts`, `@fastify/compress`,
  * `@fastify/cors`, `@fastify/etag`, `@fastify/helmet`,
- * `@fastify/view` (EJS), and `@fastify/static`.
+ * `@fastify/view` (EJS), `@fastify/static`, `@fastify/swagger`,
+ * and `@fastify/swagger-ui`.
+ *
+ * Synchronously reads and resolves all `$ref` schema files from
+ * `src/openapi/schemas/` before building the plugin map, so `@fastify/swagger`
+ * receives a fully inlined document.
  *
  * @param opts.locals - Application locals; `locals.pkg` is exposed as the
  *   default context for every EJS view.
- * @param opts.baseDir - Optional base directory for resolving the `src/` folder; defaults to the parent of `import.meta.dirname`.
+ * @param opts.baseDir - Optional base directory for resolving the `src/`
+ *   folder; defaults to the parent of `import.meta.dirname`.
+ * @param opts.keycloakAuth - Optional Keycloak configuration used to mark the
+ *   generated `/api/` OpenAPI operations as OpenID Connect–protected.
  * @returns A `Map` of plugin names to plugin entries, suitable for passing as
  *   the `plugins` field of `LauncherOptions`.
  */
-export default function defaultPlugins(opts: {
-    locals: LauncherLocals
-    baseDir?: string | null
-}): Map<string, FSTPlugin> {
+export default function defaultPlugins(
+    opts: DefaultPluginsOptions,
+): Map<string, FSTPlugin> {
     const { locals, baseDir = null } = opts
     const plugins = new Map<string, FSTPlugin>()
     const srcDir = baseDir
         ? join(baseDir, "src")
         : join(import.meta.dirname, "..")
+    const apiDoc = parse(
+        readFileSync(join(srcDir, "openapi", "api.yaml"), "utf8"),
+    ) as OpenAPIV3_1.Document
+    const schemas = apiDoc.components?.schemas
+    if (schemas) {
+        for (const key of Object.keys(schemas)) {
+            const schema = schemas[key]
+            if (schema && "$ref" in schema) {
+                const refPath = join(
+                    srcDir,
+                    "openapi",
+                    (schema as { $ref: string }).$ref,
+                )
+                schemas[key] = parse(
+                    readFileSync(refPath, "utf8"),
+                ) as OpenAPIV3_1.SchemaObject
+            }
+        }
+    }
+    configureApiDocumentAuth(apiDoc, opts.keycloakAuth)
 
     plugins.set("@fastify/accepts", {
         plugin: FastifyAccepts,
@@ -52,6 +158,7 @@ export default function defaultPlugins(opts: {
             global: true,
             contentSecurityPolicy: {
                 directives: {
+                    connectSrc: ["'self'", "https://cdn.jsdelivr.net/"],
                     fontSrc: [
                         "'self'",
                         "https://fonts.googleapis.com/",
@@ -85,6 +192,33 @@ export default function defaultPlugins(opts: {
             prefix: "/",
         },
     })
+    plugins.set("@fastify/swagger", {
+        plugin: FastifySwagger,
+        opts: {
+            mode: "static",
+            specification: { document: apiDoc },
+            exposeRoute: true,
+        },
+    })
+    plugins.set("@fastify/swagger-ui", {
+        plugin: FastifySwaggerUi,
+        opts: {
+            routePrefix: "/docs",
+            uiConfig: {
+                deepLinking: true,
+                docExpansion: "list",
+                dom_id: "#swagger-ui",
+                jsonEditor: true,
+                showRequestHeaders: true,
+                tryItOutEnabled: false,
+                onComplete: () => {
+                    // @ts-expect-error — runs in browser context, not Node
+                    const topbar = document.querySelector("div.topbar")
+                    topbar?.remove()
+                },
+            },
+        },
+    })
 
     return plugins
 }

package/src/defaults/defaultRoutes.ts

@@ -7,6 +7,11 @@ import type { RouteOptions } from "fastify"
  * Registers:
  * - `GET /` — renders `index.ejs` for `text/html`, throws 406 otherwise.
  * - `DELETE|PATCH|POST|PUT|OPTIONS /` — responds with 405 Method Not Allowed.
+ * - `GET /api/` — returns a JSON welcome message.
+ * - `DELETE|PATCH|POST|PUT /api/` — responds with 405 Method Not Allowed.
+ *
+ * Authentication is handled globally by the `preHandler` hook registered in
+ * {@link launcher} when `locals.authPaths` is set.
  */
 export default function defaultRoutes(): Map<string, RouteOptions> {
     const routes = new Map<string, RouteOptions>()
@@ -28,7 +33,6 @@ export default function defaultRoutes(): Map<string, RouteOptions> {
             }
         },
     })
-
     routes.set("INDEX_405", {
         method: ["DELETE", "PATCH", "POST", "PUT", "OPTIONS"],
         url: "/",
@@ -37,6 +41,31 @@ export default function defaultRoutes(): Map<string, RouteOptions> {
             throw methodNotAllowed()
         },
     })
+    routes.set("API_INDEX", {
+        method: "GET",
+        url: "/api/",
+        exposeHeadRoute: true,
+        handler: async (request, reply) => {
+            const { locals } = request.server
+            const accept = request.accepts()
+            switch (accept.type(["json"])) {
+                case "json":
+                    return reply.type("application/json").send({
+                        message: `Welcome to the index page of the server API :: ${locals.pkg?.["name"]}`,
+                    })
+                default:
+                    throw notAcceptable()
+            }
+        },
+    })
+    routes.set("API_INDEX_405", {
+        method: ["DELETE", "PATCH", "POST", "PUT"],
+        url: "/api/",
+        handler: async (_request, reply) => {
+            reply.header("allow", "GET, HEAD")
+            throw methodNotAllowed()
+        },
+    })
 
     return routes
 }

package/src/hooks/authPreHandler.ts

@@ -0,0 +1,41 @@
+import { unauthorized } from "@hapi/boom"
+import type { FastifyReply, FastifyRequest } from "fastify"
+import picomatch from "picomatch"
+
+/**
+ * Factory that creates a Fastify `preHandler` hook enforcing bearer-token
+ * authentication on any route whose URL matches one of the given glob patterns.
+ *
+ * The returned hook is intended to be registered globally via
+ * `fastify.addHook("preHandler", createAuthPreHandler(authPaths))`.
+ * For every request, `request.routeOptions.url` is tested against the compiled
+ * picomatch matcher; non-matching routes pass through unconditionally.
+ *
+ * When a route is protected, token verification is delegated to the
+ * `verifyToken` decorator registered on the Fastify instance.
+ *
+ * @param authPaths - Array of picomatch glob patterns (e.g. `["/api/**"]`).
+ * @param realm - Protection-space label used in the `WWW-Authenticate` challenge
+ *   (RFC 6750). Typically the Keycloak realm name. Defaults to `"api"`.
+ */
+export function createAuthPreHandler(
+    authPaths: string[],
+    realm = "api",
+): (request: FastifyRequest, reply: FastifyReply) => Promise<void> {
+    const isProtected = picomatch(authPaths)
+    return async function authPreHandler(
+        request: FastifyRequest,
+        reply: FastifyReply,
+    ): Promise<void> {
+        if (!isProtected(request.routeOptions.url ?? "")) {
+            return
+        }
+        const isAuthorized = await request.server.verifyToken(
+            request.headers.authorization,
+        )
+        if (!isAuthorized) {
+            reply.header("www-authenticate", `Bearer realm="${realm}"`)
+            throw unauthorized("Missing or invalid bearer token")
+        }
+    }
+}

package/src/index.ts

@@ -8,16 +8,23 @@ import defaultErrorHandler from "./defaults/defaultErrorHandler.ts"
 import defaultFastifyOptions from "./defaults/defaultFastifyOptions.ts"
 import defaultPlugins from "./defaults/defaultPlugins.ts"
 import defaultRoutes from "./defaults/defaultRoutes.ts"
+import { createAuthPreHandler } from "./hooks/authPreHandler.ts"
 import onResponse from "./hooks/onResponse.ts"
 import preHandler from "./hooks/preHandler.ts"
 import launcher from "./launcher.ts"
 
+export { createKeycloakVerifier } from "./auth/keycloak.ts"
 export type {
+    DefaultPluginsOptions,
     FSTPlugin,
+    KeycloakAuthConfig,
     LauncherLocals,
     LauncherOptions,
+    TokenVerifier,
 } from "./types.ts"
+
 export {
+    createAuthPreHandler,
     defaultErrorHandler,
     defaultFastifyOptions,
     defaultPlugins,

package/src/launcher.ts

@@ -3,6 +3,7 @@ import { notFound } from "@hapi/boom"
 import Fastify, { type FastifyInstance } from "fastify"
 import defaultErrorHandler from "./defaults/defaultErrorHandler.ts"
 import defaultFastifyOptions from "./defaults/defaultFastifyOptions.ts"
+import { createAuthPreHandler } from "./hooks/authPreHandler.ts"
 import { onResponse, preHandler } from "./index.ts"
 import type { LauncherOptions } from "./types.ts"
 
@@ -11,7 +12,7 @@ import type { LauncherOptions } from "./types.ts"
  *
  * Steps performed:
  * 1. Creates a `FastifyInstance` merging {@link defaultFastifyOptions} with `opts`.
- * 2. Decorates the instance with `locals` and any extra `decorators`.
+ * 2. Decorates the instance with `locals`, `verifyToken`, and any extra `decorators`.
  * 3. Registers all `plugins` and `routes`.
  * 4. Sets a `notFound` handler (throws Boom 404) and {@link defaultErrorHandler}.
  * 5. Registers {@link preHandler} and {@link onResponse} hooks.
@@ -25,6 +26,7 @@ export default function launcher({
     plugins,
     routes,
     decorators,
+    verifyToken,
     opts,
     done,
 }: LauncherOptions): FastifyInstance {
@@ -37,6 +39,7 @@ export default function launcher({
     })
 
     fastify.decorate("locals", locals)
+    fastify.decorate("verifyToken", verifyToken ?? (async () => false))
 
     if (decorators instanceof Map) {
         for (const [key, value] of decorators) {
@@ -58,6 +61,13 @@ export default function launcher({
 
     fastify.setErrorHandler(defaultErrorHandler)
 
+    if (locals.authPaths?.length) {
+        fastify.addHook(
+            "preHandler",
+            createAuthPreHandler(locals.authPaths, locals.authRealm),
+        )
+    }
+
     // TODO: Add hook for `onRequestAbort`
     fastify.addHook("preHandler", preHandler)
     fastify.addHook("onResponse", onResponse)

package/src/openapi/api.yaml

@@ -0,0 +1,150 @@
+openapi: 3.1.0
+
+##### Info
+info:
+  title: Basic API
+  description: |
+    Reference implementation of the HTTP server.
+  version: 0.6.0
+
+##### Servers
+servers:
+  - url: http://localhost:8888/
+    description: Local server
+
+##### Tags
+tags:
+  - name: index
+    description: Operations related to the root of the API
+
+##### Paths
+paths:
+  /api/:
+    summary: API index routes
+    get:
+      operationId: getApiIndex
+      summary: Returns a welcome message
+      tags:
+        - index
+      responses:
+        200:
+          description: Welcome message
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WelcomeMessage"
+    head:
+      operationId: headApiIndex
+      summary: Returns headers for the API index
+      tags:
+        - index
+      responses:
+        200:
+          description: Empty response with headers
+    delete:
+      operationId: deleteApiIndex
+      summary: Not allowed on the API index
+      tags:
+        - index
+      responses:
+        405:
+          description: Method not allowed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              examples:
+                405:
+                  $ref: "#/components/examples/http_405"
+    patch:
+      operationId: patchApiIndex
+      summary: Not allowed on the API index
+      tags:
+        - index
+      responses:
+        405:
+          description: Method not allowed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              examples:
+                405:
+                  $ref: "#/components/examples/http_405"
+    post:
+      operationId: postApiIndex
+      summary: Not allowed on the API index
+      tags:
+        - index
+      responses:
+        405:
+          description: Method not allowed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              examples:
+                405:
+                  $ref: "#/components/examples/http_405"
+    put:
+      operationId: putApiIndex
+      summary: Not allowed on the API index
+      tags:
+        - index
+      responses:
+        405:
+          description: Method not allowed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              examples:
+                405:
+                  $ref: "#/components/examples/http_405"
+
+##### Components
+components:
+  securitySchemes:
+    openIdConnect:
+      type: openIdConnect
+      # Placeholder — overridden at runtime by defaultPlugins when KEYCLOAK_* env vars are set
+      openIdConnectUrl: https://keycloak.example.com/realms/placeholder/.well-known/openid-configuration
+  schemas:
+    Error:
+      $ref: "schemas/Error.yaml"
+    WelcomeMessage:
+      type: object
+      required: [message]
+      properties:
+        message:
+          description: Welcome message text.
+          type: string
+  examples:
+    http_400:
+      value:
+        code: 400
+        message: Bad Request
+    http_401:
+      value:
+        code: 401
+        message: Unauthorized
+    http_403:
+      value:
+        code: 403
+        message: Forbidden
+    http_404:
+      value:
+        code: 404
+        message: Not Found
+    http_405:
+      value:
+        code: 405
+        message: Method Not Allowed
+    http_406:
+      value:
+        code: 406
+        message: Not Acceptable
+    http_500:
+      value:
+        code: 500
+        message: Internal Server Error