@darthcav/ts-http-server 0.5.0 → 0.6.0

package/src/openapi/schemas/Error.yaml

@@ -0,0 +1,14 @@
+# Error schema
+$id: https://darthcav.github.io/api/v1/schemas/Error
+$schema: https://json-schema.org/draft/2020-12/schema
+title: Error schema for the APIs
+description: Error model for the APIs
+type: object
+required: [ message ]
+properties:
+  message:
+    description: Error message.
+    type: string
+  code:
+    description: HTTP status code.
+    type: integer

package/src/start.ts

@@ -1,20 +1,59 @@
 import process, { env } from "node:process"
 import { getConsoleLogger, main } from "@darthcav/ts-utils"
 import pkg from "../package.json" with { type: "json" }
-import { defaultPlugins, defaultRoutes, launcher } from "./index.ts"
+import { createKeycloakVerifier } from "./auth/keycloak.ts"
+import {
+    defaultPlugins,
+    defaultRoutes,
+    type KeycloakAuthConfig,
+    launcher,
+} from "./index.ts"
 
 const logger = await getConsoleLogger(pkg.name, "info")
 
-main(pkg.name, logger, () => {
+main(pkg.name, logger, async () => {
+    const authPaths = env["API_AUTH_PATHS"]
+        ?.split(",")
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0)
+
+    const keycloakUrl = env["KEYCLOAK_URL"]?.trim()
+    const keycloakRealm = env["KEYCLOAK_REALM"]?.trim()
+    const keycloakClientId = env["KEYCLOAK_CLIENT_ID"]?.trim()
+    const keycloakClientSecret = env["KEYCLOAK_CLIENT_SECRET"]?.trim()
+
+    const keycloakAuth: KeycloakAuthConfig | undefined =
+        keycloakUrl && keycloakRealm && keycloakClientId && keycloakClientSecret
+            ? {
+                  url: keycloakUrl,
+                  realm: keycloakRealm,
+                  clientId: keycloakClientId,
+                  clientSecret: keycloakClientSecret,
+              }
+            : undefined
+
     const locals = {
         pkg,
         host: env["HOST"] ?? "localhost",
-        port: Number(env["CONTAINER_EXPOSE_PORT"]) ?? 8888,
+        port: Number(env["CONTAINER_EXPOSE_PORT"]) || 8888,
+        ...(authPaths?.length ? { authPaths } : {}),
+        ...(keycloakRealm ? { authRealm: keycloakRealm } : {}),
     }
-    const plugins = defaultPlugins({ locals })
+    const plugins = keycloakAuth
+        ? defaultPlugins({ locals, keycloakAuth })
+        : defaultPlugins({ locals })
     const routes = defaultRoutes()
 
-    const fastify = launcher({ logger, locals, plugins, routes })
+    const fastify = keycloakAuth
+        ? launcher({
+              logger,
+              locals,
+              plugins,
+              routes,
+              verifyToken: createKeycloakVerifier(keycloakAuth),
+          })
+        : launcher({ logger, locals, plugins, routes })
+
     for (const signal of ["SIGINT", "SIGTERM"] as const) {
         process.on(signal, async (signal) =>
             fastify

package/src/types.ts

@@ -13,23 +13,60 @@ import type {
  */
 export type FSTPlugin = {
     /** The Fastify plugin function to register. */
-    // biome-ignore lint/suspicious/noExplicitAny: third-party plugins use varied option types
+    // biome-ignore lint/suspicious/noExplicitAny: plugin opts types vary per third-party plugin; any is required for assignability
     plugin: FastifyPluginCallback<any> | FastifyPluginAsync<any>
     /** 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
 }
@@ -48,8 +85,40 @@ 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
+    }
+}

package/src/views/index.ejs

@@ -25,6 +25,10 @@
             <code><%= process.pid %></code>
         </td>
     </tr>
+    <tr>
+        <th>Documentation</th>
+        <td><a href="/docs/">OpenAPI documentation</a></td>
+    </tr>
 </table>
 
 <%- include ("./include/footer.ejs") -%>