@query-farm/vgi-rpc 0.3.4 → 0.6.0

package/src/http/auth.ts

@@ -0,0 +1,110 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AuthContext } from "../auth.js";
+
+/** Async function that authenticates an incoming HTTP request. */
+export type AuthenticateFn = (request: Request) => AuthContext | Promise<AuthContext>;
+
+/** RFC 9728 OAuth Protected Resource Metadata. */
+export interface OAuthResourceMetadata {
+  resource: string;
+  authorizationServers: string[];
+  scopesSupported?: string[];
+  bearerMethodsSupported?: string[];
+  resourceSigningAlgValuesSupported?: string[];
+  resourceName?: string;
+  resourceDocumentation?: string;
+  resourcePolicyUri?: string;
+  resourceTosUri?: string;
+  /** OAuth client_id that clients should use with the authorization server. */
+  clientId?: string;
+  /** OAuth client_secret that clients should use with the authorization server. */
+  clientSecret?: string;
+  /** OAuth client_id for device code flow. */
+  deviceCodeClientId?: string;
+  /** OAuth client_secret for device code flow. */
+  deviceCodeClientSecret?: string;
+  /** When true, clients should use the OIDC id_token as the Bearer token instead of access_token. */
+  useIdTokenAsBearer?: boolean;
+}
+
+/** Convert OAuthResourceMetadata to RFC 9728 snake_case JSON object. */
+export function oauthResourceMetadataToJson(metadata: OAuthResourceMetadata): Record<string, any> {
+  const json: Record<string, any> = {
+    resource: metadata.resource,
+    authorization_servers: metadata.authorizationServers,
+  };
+  if (metadata.scopesSupported) json.scopes_supported = metadata.scopesSupported;
+  if (metadata.bearerMethodsSupported) json.bearer_methods_supported = metadata.bearerMethodsSupported;
+  if (metadata.resourceSigningAlgValuesSupported)
+    json.resource_signing_alg_values_supported = metadata.resourceSigningAlgValuesSupported;
+  if (metadata.resourceName) json.resource_name = metadata.resourceName;
+  if (metadata.resourceDocumentation) json.resource_documentation = metadata.resourceDocumentation;
+  if (metadata.resourcePolicyUri) json.resource_policy_uri = metadata.resourcePolicyUri;
+  if (metadata.resourceTosUri) json.resource_tos_uri = metadata.resourceTosUri;
+  if (metadata.clientId) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.clientId)) {
+      throw new Error(`Invalid client_id: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.client_id = metadata.clientId;
+  }
+  if (metadata.clientSecret) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.clientSecret)) {
+      throw new Error(`Invalid client_secret: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.client_secret = metadata.clientSecret;
+  }
+  if (metadata.deviceCodeClientId) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.deviceCodeClientId)) {
+      throw new Error(`Invalid device_code_client_id: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.device_code_client_id = metadata.deviceCodeClientId;
+  }
+  if (metadata.deviceCodeClientSecret) {
+    if (!/^[A-Za-z0-9\-._~]+$/.test(metadata.deviceCodeClientSecret)) {
+      throw new Error(`Invalid device_code_client_secret: must contain only URL-safe characters [A-Za-z0-9\\-._~]`);
+    }
+    json.device_code_client_secret = metadata.deviceCodeClientSecret;
+  }
+  if (metadata.useIdTokenAsBearer) {
+    json.use_id_token_as_bearer = true;
+  }
+  return json;
+}
+
+/** Compute the well-known path for OAuth Protected Resource Metadata. */
+export function wellKnownPath(prefix: string): string {
+  return `/.well-known/oauth-protected-resource${prefix}`;
+}
+
+/** Build a WWW-Authenticate header value with optional resource_metadata URL, client_id, client_secret, device_code_client_id, device_code_client_secret, and use_id_token_as_bearer. */
+export function buildWwwAuthenticateHeader(
+  metadataUrl?: string,
+  clientId?: string,
+  clientSecret?: string,
+  useIdTokenAsBearer?: boolean,
+  deviceCodeClientId?: string,
+  deviceCodeClientSecret?: string,
+): string {
+  let header = "Bearer";
+  if (metadataUrl) {
+    header += ` resource_metadata="${metadataUrl}"`;
+  }
+  if (clientId) {
+    header += `, client_id="${clientId}"`;
+  }
+  if (clientSecret) {
+    header += `, client_secret="${clientSecret}"`;
+  }
+  if (deviceCodeClientId) {
+    header += `, device_code_client_id="${deviceCodeClientId}"`;
+  }
+  if (deviceCodeClientSecret) {
+    header += `, device_code_client_secret="${deviceCodeClientSecret}"`;
+  }
+  if (useIdTokenAsBearer) {
+    header += `, use_id_token_as_bearer="true"`;
+  }
+  return header;
+}

package/src/http/bearer.ts

@@ -0,0 +1,107 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+import { timingSafeEqual } from "node:crypto";
+import type { AuthContext } from "../auth.js";
+import type { AuthenticateFn } from "./auth.js";
+
+/** Receives the raw bearer token string, returns an AuthContext on success. Must throw on failure. */
+export type BearerValidateFn = (token: string) => AuthContext | Promise<AuthContext>;
+
+/**
+ * Create a bearer-token authenticate callback.
+ *
+ * Extracts the `Authorization: Bearer <token>` header and delegates
+ * validation to the user-supplied `validate` callback.
+ */
+export function bearerAuthenticate(options: { validate: BearerValidateFn }): AuthenticateFn {
+  const { validate } = options;
+
+  return async function authenticate(request: Request): Promise<AuthContext> {
+    const authHeader = request.headers.get("Authorization") ?? "";
+    if (!authHeader.startsWith("Bearer ")) {
+      throw new Error("Missing or invalid Authorization header");
+    }
+    const token = authHeader.slice(7);
+    return validate(token);
+  };
+}
+
+/** Constant-time string comparison to prevent timing attacks on token lookup. */
+function safeEqual(a: string, b: string): boolean {
+  const enc = new TextEncoder();
+  const bufA = enc.encode(a);
+  const bufB = enc.encode(b);
+  if (bufA.byteLength !== bufB.byteLength) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+/**
+ * Create a bearer-token authenticate callback from a static token map.
+ *
+ * Convenience wrapper around `bearerAuthenticate` that looks up the
+ * token in a pre-built mapping using constant-time comparison.
+ */
+export function bearerAuthenticateStatic(options: {
+  tokens: ReadonlyMap<string, AuthContext> | Record<string, AuthContext>;
+}): AuthenticateFn {
+  const entries: [string, AuthContext][] =
+    options.tokens instanceof Map ? [...options.tokens.entries()] : Object.entries(options.tokens);
+
+  function validate(token: string): AuthContext {
+    for (const [key, ctx] of entries) {
+      if (safeEqual(token, key)) return ctx;
+    }
+    throw new Error("Unknown bearer token");
+  }
+
+  return bearerAuthenticate({ validate });
+}
+
+/**
+ * Check whether an error represents a credential rejection (should be
+ * caught by the chain) vs a bug or authorization failure (should propagate).
+ *
+ * Mirrors Python's semantics where only `ValueError` is caught:
+ * - Plain `Error` (constructor === Error) without `PermissionError` name → credential rejection
+ * - `TypeError`, `RangeError`, etc. (Error subclasses) → bug, propagate
+ * - `PermissionError` name → authorization failure, propagate
+ * - Non-Error throws → propagate
+ */
+function isCredentialError(err: unknown): err is Error {
+  return err instanceof Error && err.constructor === Error && err.name !== "PermissionError";
+}
+
+/**
+ * Chain multiple authenticate callbacks, trying each in order.
+ *
+ * Each authenticator is called in sequence. Plain `Error` (credential
+ * rejection) causes the next authenticator to be tried. Error subclasses
+ * (`TypeError`, `RangeError`, etc.), `PermissionError`-named errors, and
+ * non-Error throws propagate immediately.
+ *
+ * @throws Error if no authenticators are provided.
+ */
+export function chainAuthenticate(...authenticators: AuthenticateFn[]): AuthenticateFn {
+  if (authenticators.length === 0) {
+    throw new Error("chainAuthenticate requires at least one authenticator");
+  }
+
+  return async function authenticate(request: Request): Promise<AuthContext> {
+    let lastError: Error | null = null;
+    for (const authFn of authenticators) {
+      try {
+        return await authFn(request);
+      } catch (err) {
+        if (isCredentialError(err)) {
+          lastError = err;
+          continue;
+        }
+        throw err;
+      }
+    }
+    const error = new Error("No authenticator accepted the request");
+    if (lastError) error.cause = lastError;
+    throw error;
+  };
+}

package/src/http/dispatch.ts

@@ -2,8 +2,10 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { RecordBatch, RecordBatchReader, Schema } from "@query-farm/apache-arrow";
+import type { AuthContext } from "../auth.js";
 import { STATE_KEY } from "../constants.js";
 import { buildDescribeBatch, DESCRIBE_SCHEMA } from "../dispatch/describe.js";
+import { type ExternalLocationConfig, maybeExternalizeBatch } from "../external.js";
 import type { MethodDefinition } from "../types.js";
 import { OutputCollector } from "../types.js";
 import { conformBatchToSchema } from "../util/conform.js";
@@ -28,6 +30,8 @@ export interface DispatchContext {
   serverId: string;
   maxStreamResponseBytes?: number;
   stateSerializer: StateSerializer;
+  authContext?: AuthContext;
+  externalLocation?: ExternalLocationConfig;
 }
 
 /** Dispatch a __describe__ request. */
@@ -55,16 +59,22 @@ export async function httpDispatchUnary(
     throw new HttpRpcError(`Method name in request '${parsed.methodName}' does not match URL '${method.name}'`, 400);
   }
 
-  const out = new OutputCollector(schema, true, ctx.serverId, parsed.requestId);
+  const out = new OutputCollector(schema, true, ctx.serverId, parsed.requestId, ctx.authContext);
 
   try {
     const result = await method.handler!(parsed.params, out);
-    const resultBatch = buildResultBatch(schema, result, ctx.serverId, parsed.requestId);
+    let resultBatch = buildResultBatch(schema, result, ctx.serverId, parsed.requestId);
+    if (ctx.externalLocation) {
+      resultBatch = await maybeExternalizeBatch(resultBatch, ctx.externalLocation);
+    }
     const batches = [...out.batches.map((b) => b.batch), resultBatch];
     return arrowResponse(serializeIpcStream(schema, batches));
   } catch (error: any) {
     const errBatch = buildErrorBatch(schema, error, ctx.serverId, parsed.requestId);
-    return arrowResponse(serializeIpcStream(schema, [errBatch]), 500);
+    const response = arrowResponse(serializeIpcStream(schema, [errBatch]), 500);
+    // Attach the error so the dispatch hook can see it
+    (response as any).__dispatchError = error;
+    return response;
   }
 }
 
@@ -96,7 +106,9 @@ export async function httpDispatchStreamInit(
   } catch (error: any) {
     const errSchema = method.headerSchema ?? EMPTY_SCHEMA;
     const errBatch = buildErrorBatch(errSchema, error, ctx.serverId, parsed.requestId);
-    return arrowResponse(serializeIpcStream(errSchema, [errBatch]), 500);
+    const response = arrowResponse(serializeIpcStream(errSchema, [errBatch]), 500);
+    (response as any).__dispatchError = error;
+    return response;
   }
 
   // Support dynamic output schemas (same as pipe transport)
@@ -107,14 +119,16 @@ export async function httpDispatchStreamInit(
   let headerBytes: Uint8Array | null = null;
   if (method.headerSchema && method.headerInit) {
     try {
-      const headerOut = new OutputCollector(method.headerSchema, true, ctx.serverId, parsed.requestId);
+      const headerOut = new OutputCollector(method.headerSchema, true, ctx.serverId, parsed.requestId, ctx.authContext);
       const headerValues = method.headerInit(parsed.params, state, headerOut);
       const headerBatch = buildResultBatch(method.headerSchema, headerValues, ctx.serverId, parsed.requestId);
       const headerBatches = [...headerOut.batches.map((b) => b.batch), headerBatch];
       headerBytes = serializeIpcStream(method.headerSchema, headerBatches);
     } catch (error: any) {
       const errBatch = buildErrorBatch(method.headerSchema, error, ctx.serverId, parsed.requestId);
-      return arrowResponse(serializeIpcStream(method.headerSchema, [errBatch]), 500);
+      const response = arrowResponse(serializeIpcStream(method.headerSchema, [errBatch]), 500);
+      (response as any).__dispatchError = error;
+      return response;
     }
   }
 
@@ -205,7 +219,7 @@ export async function httpDispatchStreamExchange(
     // Exchange path — also handles exchange-registered methods acting as
     // producers (__isProducer=true). Use producer mode on the OutputCollector
     // when effectiveProducer so finish() is allowed.
-    const out = new OutputCollector(outputSchema, effectiveProducer, ctx.serverId, null);
+    const out = new OutputCollector(outputSchema, effectiveProducer, ctx.serverId, null, ctx.authContext);
 
     // Cast compatible input types (e.g., decimal→double, int32→int64)
     const conformedBatch = conformBatchToSchema(reqBatch, inputSchema);
@@ -224,7 +238,9 @@ export async function httpDispatchStreamExchange(
           error.stack?.split("\n").slice(0, 5).join("\n"),
         );
       const errBatch = buildErrorBatch(outputSchema, error, ctx.serverId, null);
-      return arrowResponse(serializeIpcStream(outputSchema, [errBatch]), 500);
+      const response = arrowResponse(serializeIpcStream(outputSchema, [errBatch]), 500);
+      (response as any).__dispatchError = error;
+      return response;
     }
 
     // Collect emitted batches
@@ -281,9 +297,10 @@ async function produceStreamResponse(
   const allBatches: RecordBatch[] = [];
   const maxBytes = ctx.maxStreamResponseBytes;
   let estimatedBytes = 0;
+  let producerError: Error | undefined;
 
   while (true) {
-    const out = new OutputCollector(outputSchema, true, ctx.serverId, requestId);
+    const out = new OutputCollector(outputSchema, true, ctx.serverId, requestId, ctx.authContext);
 
     try {
       if (method.producerFn) {
@@ -300,6 +317,7 @@ async function produceStreamResponse(
       if (process.env.VGI_DISPATCH_DEBUG)
         console.error(`[produceStreamResponse] error:`, error.message, error.stack?.split("\n").slice(0, 3).join("\n"));
       allBatches.push(buildErrorBatch(outputSchema, error, ctx.serverId, requestId));
+      producerError = error instanceof Error ? error : new Error(String(error));
       break;
     }
 
@@ -334,7 +352,11 @@ async function produceStreamResponse(
   } else {
     responseBody = dataBytes;
   }
-  return arrowResponse(responseBody);
+  const response = arrowResponse(responseBody);
+  if (producerError) {
+    (response as any).__dispatchError = producerError;
+  }
+  return response;
 }
 
 function concatBytes(...arrays: Uint8Array[]): Uint8Array {

package/src/http/handler.ts

@@ -3,11 +3,13 @@
 
 import { randomBytes } from "node:crypto";
 import { Schema } from "@query-farm/apache-arrow";
+import type { AuthContext } from "../auth.js";
 import { DESCRIBE_METHOD_NAME } from "../constants.js";
 import type { Protocol } from "../protocol.js";
-import { MethodType } from "../types.js";
+import { type CallStatistics, type DispatchInfo, MethodType } from "../types.js";
 import { zstdCompress, zstdDecompress } from "../util/zstd.js";
 import { buildErrorBatch } from "../wire/response.js";
+import { buildWwwAuthenticateHeader, oauthResourceMetadataToJson, wellKnownPath } from "./auth.js";
 import { ARROW_CONTENT_TYPE, arrowResponse, HttpRpcError, serializeIpcStream } from "./common.js";
 import {
   httpDispatchDescribe,
@@ -15,6 +17,7 @@ import {
   httpDispatchStreamInit,
   httpDispatchUnary,
 } from "./dispatch.js";
+import { buildDescribePage, buildLandingPage, buildNotFoundPage } from "./pages.js";
 import { type HttpHandlerOptions, jsonStateSerializer } from "./types.js";
 
 const EMPTY_SCHEMA = new Schema([]);
@@ -35,7 +38,7 @@ export function createHttpHandler(
   protocol: Protocol,
   options?: HttpHandlerOptions,
 ): (request: Request) => Response | Promise<Response> {
-  const prefix = (options?.prefix ?? "/vgi").replace(/\/+$/, "");
+  const prefix = (options?.prefix ?? "").replace(/\/+$/, "");
   const signingKey = options?.signingKey ?? randomBytes(32);
   const tokenTtl = options?.tokenTtl ?? 3600;
   const corsOrigins = options?.corsOrigins;
@@ -43,17 +46,39 @@ export function createHttpHandler(
   const maxStreamResponseBytes = options?.maxStreamResponseBytes;
   const serverId = options?.serverId ?? crypto.randomUUID().replace(/-/g, "").slice(0, 12);
 
+  const authenticate = options?.authenticate;
+  const oauthMetadata = options?.oauthResourceMetadata;
+
   const methods = protocol.getMethods();
 
   const compressionLevel = options?.compressionLevel;
   const stateSerializer = options?.stateSerializer ?? jsonStateSerializer;
+  const dispatchHook = options?.dispatchHook;
+
+  // HTML page configuration
+  const enableLandingPage = options?.enableLandingPage ?? true;
+  const enableDescribePage = options?.enableDescribePage ?? true;
+  const enableNotFoundPage = options?.enableNotFoundPage ?? true;
+  const displayName = options?.protocolName ?? protocol.name;
+  const repoUrl = options?.repositoryUrl ?? null;
+
+  // Pre-render HTML pages for zero per-request overhead
+  const landingHtml = enableLandingPage
+    ? buildLandingPage(displayName, serverId, enableDescribePage ? `${prefix}/describe` : null, repoUrl)
+    : null;
+  const describeHtml = enableDescribePage ? buildDescribePage(displayName, serverId, methods, repoUrl) : null;
+  const notFoundHtml = enableNotFoundPage ? buildNotFoundPage(prefix, displayName) : null;
+
+  const externalLocation = options?.externalLocation;
 
-  const ctx = {
+  // ctx is built per-request to include authContext; base fields set here
+  const baseCtx = {
     signingKey,
     tokenTtl,
     serverId,
     maxStreamResponseBytes,
     stateSerializer,
+    externalLocation,
   };
 
   function addCorsHeaders(headers: Headers): void {
@@ -88,6 +113,20 @@ export function createHttpHandler(
     const url = new URL(request.url);
     const path = url.pathname;
 
+    // Well-known endpoint: RFC 9728 OAuth Protected Resource Metadata
+    if (oauthMetadata && path === wellKnownPath(prefix)) {
+      if (request.method !== "GET") {
+        return new Response("Method Not Allowed", { status: 405 });
+      }
+      const body = JSON.stringify(oauthResourceMetadataToJson(oauthMetadata));
+      const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "public, max-age=60",
+      });
+      addCorsHeaders(headers);
+      return new Response(body, { status: 200, headers });
+    }
+
     // CORS preflight
     if (request.method === "OPTIONS") {
       if (path === `${prefix}/__capabilities__`) {
@@ -108,6 +147,32 @@ export function createHttpHandler(
       return new Response(null, { status: 405 });
     }
 
+    // HTML pages for GET requests
+    if (request.method === "GET") {
+      // Landing page: GET {prefix}/ or GET {prefix}
+      if (landingHtml && (path === prefix || path === `${prefix}/`)) {
+        const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+        addCorsHeaders(headers);
+        return new Response(landingHtml, { status: 200, headers });
+      }
+
+      // Describe page: GET {prefix}/describe
+      if (describeHtml && path === `${prefix}/describe`) {
+        const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+        addCorsHeaders(headers);
+        return new Response(describeHtml, { status: 200, headers });
+      }
+
+      // 404 page for any other GET
+      if (notFoundHtml) {
+        const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
+        addCorsHeaders(headers);
+        return new Response(notFoundHtml, { status: 404, headers });
+      }
+
+      return new Response("Not Found", { status: 404 });
+    }
+
     if (request.method !== "POST") {
       return new Response("Method Not Allowed", { status: 405 });
     }
@@ -135,6 +200,36 @@ export function createHttpHandler(
       body = zstdDecompress(body);
     }
 
+    // Build per-request dispatch context
+    const ctx = { ...baseCtx } as typeof baseCtx & { authContext?: AuthContext };
+
+    // Authentication
+    if (authenticate) {
+      try {
+        ctx.authContext = await authenticate(request);
+      } catch (error: any) {
+        const headers = new Headers({ "Content-Type": "text/plain" });
+        addCorsHeaders(headers);
+        if (oauthMetadata) {
+          const metadataUrl = new URL(request.url);
+          metadataUrl.pathname = wellKnownPath(prefix);
+          metadataUrl.search = "";
+          headers.set(
+            "WWW-Authenticate",
+            buildWwwAuthenticateHeader(
+              metadataUrl.toString(),
+              oauthMetadata.clientId,
+              oauthMetadata.clientSecret,
+              oauthMetadata.useIdTokenAsBearer,
+              oauthMetadata.deviceCodeClientId,
+              oauthMetadata.deviceCodeClientSecret,
+            ),
+          );
+        }
+        return new Response(error.message || "Unauthorized", { status: 401, headers });
+      }
+    }
+
     // Route: {prefix}/__describe__
     if (path === `${prefix}/${DESCRIBE_METHOD_NAME}`) {
       try {
@@ -174,6 +269,20 @@ export function createHttpHandler(
       return compressIfAccepted(makeErrorResponse(err, 404), clientAcceptsZstd);
     }
 
+    const methodType = method.type === MethodType.UNARY ? "unary" : "stream";
+    const info: DispatchInfo = { method: methodName, methodType, serverId, requestId: null };
+    const stats: CallStatistics = {
+      inputBatches: 0,
+      outputBatches: 0,
+      inputRows: 0,
+      outputRows: 0,
+      inputBytes: 0,
+      outputBytes: 0,
+    };
+
+    const hookToken = dispatchHook?.onDispatchStart(info);
+    let dispatchError: Error | undefined;
+
     try {
       let response: Response;
 
@@ -200,13 +309,21 @@ export function createHttpHandler(
         response = await httpDispatchStreamExchange(method, body, ctx);
       }
 
+      // Check if the dispatch function caught an error internally
+      const internalError = (response as any).__dispatchError;
+      if (internalError) {
+        dispatchError = internalError instanceof Error ? internalError : new Error(String(internalError));
+      }
       addCorsHeaders(response.headers);
       return compressIfAccepted(response, clientAcceptsZstd);
     } catch (error: any) {
+      dispatchError = error instanceof Error ? error : new Error(String(error));
       if (error instanceof HttpRpcError) {
         return compressIfAccepted(makeErrorResponse(error, error.statusCode), clientAcceptsZstd);
       }
       return compressIfAccepted(makeErrorResponse(error, 500), clientAcceptsZstd);
+    } finally {
+      dispatchHook?.onDispatchEnd(hookToken, info, stats, dispatchError);
     }
   };
 }

package/src/http/index.ts

@@ -1,8 +1,22 @@
 // © Copyright 2025-2026, Query.Farm LLC - https://query.farm
 // SPDX-License-Identifier: Apache-2.0
 
+export type { AuthenticateFn, OAuthResourceMetadata } from "./auth.js";
+export { oauthResourceMetadataToJson } from "./auth.js";
+export type { BearerValidateFn } from "./bearer.js";
+export { bearerAuthenticate, bearerAuthenticateStatic, chainAuthenticate } from "./bearer.js";
 export { ARROW_CONTENT_TYPE } from "./common.js";
 export { createHttpHandler } from "./handler.js";
+export type { JwtAuthenticateOptions } from "./jwt.js";
+export { jwtAuthenticate } from "./jwt.js";
+export type { CertValidateFn, XfccElement, XfccValidateFn } from "./mtls.js";
+export {
+  mtlsAuthenticate,
+  mtlsAuthenticateFingerprint,
+  mtlsAuthenticateSubject,
+  mtlsAuthenticateXfcc,
+  parseXfcc,
+} from "./mtls.js";
 export { type UnpackedToken, unpackStateToken } from "./token.js";
 export type { HttpHandlerOptions, StateSerializer } from "./types.js";
 export { jsonStateSerializer } from "./types.js";

package/src/http/jwt.ts

@@ -0,0 +1,80 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+import * as oauth from "oauth4webapi";
+import { AuthContext } from "../auth.js";
+import type { AuthenticateFn } from "./auth.js";
+
+export interface JwtAuthenticateOptions {
+  /** The expected `iss` claim (also used to discover AS metadata). */
+  issuer: string;
+  /** The expected `aud` claim. If an array, tries each audience in order. */
+  audience: string | string[];
+  /** Explicit JWKS URI. If omitted, discovered from issuer metadata. */
+  jwksUri?: string;
+  /** JWT claim to use as the principal. Default: "sub". */
+  principalClaim?: string;
+  /** AuthContext domain. Default: "jwt". */
+  domain?: string;
+}
+
+/**
+ * Create an AuthenticateFn that validates JWT Bearer tokens using oauth4webapi.
+ *
+ * On first call, discovers the Authorization Server metadata from the issuer
+ * to obtain the JWKS URI (unless `jwksUri` is provided directly).
+ */
+export function jwtAuthenticate(options: JwtAuthenticateOptions): AuthenticateFn {
+  const principalClaim = options.principalClaim ?? "sub";
+  const domain = options.domain ?? "jwt";
+  const audience = options.audience;
+
+  let asPromise: Promise<oauth.AuthorizationServer> | null = null;
+
+  async function getAuthorizationServer(): Promise<oauth.AuthorizationServer> {
+    if (options.jwksUri) {
+      return {
+        issuer: options.issuer as `https://${string}`,
+        jwks_uri: options.jwksUri,
+      };
+    }
+    const issuerUrl = new URL(options.issuer);
+    const response = await oauth.discoveryRequest(issuerUrl);
+    return oauth.processDiscoveryResponse(issuerUrl, response);
+  }
+
+  return async function authenticate(request: Request): Promise<AuthContext> {
+    if (!asPromise) {
+      asPromise = getAuthorizationServer();
+    }
+
+    let as: oauth.AuthorizationServer;
+    try {
+      as = await asPromise;
+    } catch (error) {
+      // Reset so next request retries discovery
+      asPromise = null;
+      throw error;
+    }
+
+    // validateJwtAccessToken throws on failure, returns claims on success
+    // oauth4webapi only accepts a single string, so iterate if multiple audiences
+    const audiences = Array.isArray(audience) ? audience : [audience];
+    let claims: oauth.JWTAccessTokenClaims | undefined;
+    let lastError: unknown;
+    for (const aud of audiences) {
+      try {
+        claims = await oauth.validateJwtAccessToken(as, request, aud);
+        break;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if (!claims) {
+      throw lastError;
+    }
+    const principal = (claims[principalClaim] as string | undefined) ?? null;
+
+    return new AuthContext(domain, true, principal, claims as unknown as Record<string, any>);
+  };
+}