@query-farm/vgi-rpc 0.3.4 → 0.4.0

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { RecordBatch, type Schema } from "@query-farm/apache-arrow";
+import { AuthContext } from "./auth.js";
 export declare enum MethodType {
     UNARY = "unary",
     STREAM = "stream"
@@ -7,6 +8,10 @@ export declare enum MethodType {
 export interface LogContext {
     clientLog(level: string, message: string, extra?: Record<string, string>): void;
 }
+/** Extended context with authentication info, available to handlers. */
+export interface CallContext extends LogContext {
+    readonly auth: AuthContext;
+}
 /** Handler for unary (request-response) RPC methods. */
 export type UnaryHandler = (params: Record<string, any>, ctx: LogContext) => Promise<Record<string, any>> | Record<string, any>;
 /** Initialization function for producer streams. Returns the initial state object. */
@@ -45,7 +50,7 @@ export interface EmittedBatch {
  * Accumulates output batches during a produce/exchange call.
  * Enforces that exactly one data batch is emitted per call (plus any number of log batches).
  */
-export declare class OutputCollector implements LogContext {
+export declare class OutputCollector implements CallContext {
     private _batches;
     private _dataBatchIdx;
     private _finished;
@@ -53,7 +58,8 @@ export declare class OutputCollector implements LogContext {
     private _outputSchema;
     private _serverId;
     private _requestId;
-    constructor(outputSchema: Schema, producerMode?: boolean, serverId?: string, requestId?: string | null);
+    readonly auth: AuthContext;
+    constructor(outputSchema: Schema, producerMode?: boolean, serverId?: string, requestId?: string | null, authContext?: AuthContext);
     get outputSchema(): Schema;
     get finished(): boolean;
     get batches(): EmittedBatch[];

package/dist/types.d.ts.map

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

package/dist/wire/response.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/wire/response.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,WAAW,EACX,KAAK,MAAM,EAGZ,MAAM,0BAA0B,CAAC;AAGlC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAc5F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,WAAW,CAwCb;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAiBrH;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,WAAW,CAeb;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAyB3F"}
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/wire/response.ts"],"names":[],"mappings":"AAGA,OAAO,EAKL,WAAW,EACX,KAAK,MAAM,EAGZ,MAAM,0BAA0B,CAAC;AAGlC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAc5F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,IAAI,GACvB,WAAW,CAwCb;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,WAAW,CAiBrH;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3B,QAAQ,CAAC,EAAE,MAAM,EACjB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,WAAW,CAeb;AA6BD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,WAAW,CAY3F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@query-farm/vgi-rpc",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "license": "Apache-2.0",
   "homepage": "https://vgi-rpc-typescript.query.farm",
   "repository": {
@@ -22,7 +22,8 @@
     "src"
   ],
   "dependencies": {
-    "@query-farm/apache-arrow": "*"
+    "@query-farm/apache-arrow": "*",
+    "oauth4webapi": "^3.8.5"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.5",

package/src/auth.ts

@@ -0,0 +1,31 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+import { RpcError } from "./errors.js";
+
+/** Authentication context available to RPC handlers. */
+export class AuthContext {
+  readonly domain: string;
+  readonly authenticated: boolean;
+  readonly principal: string | null;
+  readonly claims: Record<string, any>;
+
+  constructor(domain: string, authenticated: boolean, principal: string | null, claims: Record<string, any> = {}) {
+    this.domain = domain;
+    this.authenticated = authenticated;
+    this.principal = principal;
+    this.claims = claims;
+  }
+
+  /** Create an unauthenticated (anonymous) context. */
+  static anonymous(): AuthContext {
+    return new AuthContext("", false, null);
+  }
+
+  /** Throw an RpcError if this context is not authenticated. */
+  requireAuthenticated(): void {
+    if (!this.authenticated) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
+  }
+}

package/src/client/connect.ts

@@ -3,6 +3,7 @@
 
 import type { RecordBatch, Schema } from "@query-farm/apache-arrow";
 import { LOG_LEVEL_KEY, STATE_KEY } from "../constants.js";
+import { RpcError } from "../errors.js";
 import { ARROW_CONTENT_TYPE } from "../http/common.js";
 import { httpIntrospect, type MethodInfo, type ServiceDescription } from "./introspect.js";
 import {
@@ -29,6 +30,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
   const prefix = (options?.prefix ?? "/vgi").replace(/\/+$/, "");
   const onLog = options?.onLog;
   const compressionLevel = options?.compressionLevel;
+  const authorization = options?.authorization;
 
   let methodCache: Map<string, MethodInfo> | null = null;
   let compressFn: CompressFn | undefined;
@@ -55,6 +57,9 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
       headers["Content-Encoding"] = "zstd";
       headers["Accept-Encoding"] = "zstd";
     }
+    if (authorization) {
+      headers.Authorization = authorization;
+    }
     return headers;
   }
 
@@ -65,6 +70,12 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
     return content;
   }
 
+  function checkAuth(resp: Response): void {
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
+  }
+
   async function readResponse(resp: Response): Promise<Uint8Array<ArrayBuffer>> {
     let body = new Uint8Array(await resp.arrayBuffer());
     if (resp.headers.get("Content-Encoding") === "zstd" && decompressFn) {
@@ -75,7 +86,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
 
   async function ensureMethodCache(): Promise<Map<string, MethodInfo>> {
     if (methodCache) return methodCache;
-    const desc = await httpIntrospect(baseUrl, { prefix });
+    const desc = await httpIntrospect(baseUrl, { prefix, authorization });
     methodCache = new Map(desc.methods.map((m) => [m.name, m]));
     return methodCache;
   }
@@ -98,6 +109,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
         headers: buildHeaders(),
         body: prepareBody(body) as unknown as BodyInit,
       });
+      checkAuth(resp);
 
       const responseBody = await readResponse(resp);
       const { batches } = await readResponseBatches(responseBody);
@@ -146,6 +158,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
         headers: buildHeaders(),
         body: prepareBody(body) as unknown as BodyInit,
       });
+      checkAuth(resp);
 
       const responseBody = await readResponse(resp);
 
@@ -288,6 +301,7 @@ export function httpConnect(baseUrl: string, options?: HttpConnectOptions): RpcC
         compressionLevel,
         compressFn,
         decompressFn,
+        authorization,
       });
     },
 

package/src/client/index.ts

@@ -3,6 +3,8 @@
 
 export { httpConnect, type RpcClient } from "./connect.js";
 export { httpIntrospect, type MethodInfo, parseDescribeResponse, type ServiceDescription } from "./introspect.js";
+export type { OAuthResourceMetadataResponse } from "./oauth.js";
+export { fetchOAuthMetadata, httpOAuthMetadata, parseResourceMetadataUrl } from "./oauth.js";
 export { PipeStreamSession, pipeConnect, subprocessConnect } from "./pipe.js";
 export { HttpStreamSession } from "./stream.js";
 export type {

package/src/client/introspect.ts

@@ -3,6 +3,7 @@
 
 import { Schema as ArrowSchema, type RecordBatch, RecordBatchReader, type Schema } from "@query-farm/apache-arrow";
 import { DESCRIBE_METHOD_NAME, PROTOCOL_NAME_KEY } from "../constants.js";
+import { RpcError } from "../errors.js";
 import { ARROW_CONTENT_TYPE } from "../http/common.js";
 import { buildRequestIpc, dispatchLogOrError, readResponseBatches } from "./ipc.js";
 import type { LogMessage } from "./types.js";
@@ -116,16 +117,27 @@ export async function parseDescribeResponse(
 /**
  * Send a __describe__ request and return a ServiceDescription.
  */
-export async function httpIntrospect(baseUrl: string, options?: { prefix?: string }): Promise<ServiceDescription> {
+export async function httpIntrospect(
+  baseUrl: string,
+  options?: { prefix?: string; authorization?: string },
+): Promise<ServiceDescription> {
   const prefix = options?.prefix ?? "/vgi";
   const emptySchema = new ArrowSchema([]);
   const body = buildRequestIpc(emptySchema, {}, DESCRIBE_METHOD_NAME);
 
+  const headers: Record<string, string> = { "Content-Type": ARROW_CONTENT_TYPE };
+  if (options?.authorization) {
+    headers.Authorization = options.authorization;
+  }
+
   const response = await fetch(`${baseUrl}${prefix}/${DESCRIBE_METHOD_NAME}`, {
     method: "POST",
-    headers: { "Content-Type": ARROW_CONTENT_TYPE },
+    headers,
     body: body as unknown as BodyInit,
   });
+  if (response.status === 401) {
+    throw new RpcError("AuthenticationError", "Authentication required", "");
+  }
 
   const responseBody = new Uint8Array(await response.arrayBuffer());
   const { batches } = await readResponseBatches(responseBody);

package/src/client/oauth.ts

@@ -0,0 +1,74 @@
+// © Copyright 2025-2026, Query.Farm LLC - https://query.farm
+// SPDX-License-Identifier: Apache-2.0
+
+/** RFC 9728 OAuth Protected Resource Metadata (client-side response). */
+export interface OAuthResourceMetadataResponse {
+  resource: string;
+  authorizationServers: string[];
+  scopesSupported?: string[];
+  bearerMethodsSupported?: string[];
+  resourceName?: string;
+  resourceDocumentation?: string;
+  resourcePolicyUri?: string;
+  resourceTosUri?: string;
+}
+
+function parseMetadataJson(json: Record<string, any>): OAuthResourceMetadataResponse {
+  const result: OAuthResourceMetadataResponse = {
+    resource: json.resource,
+    authorizationServers: json.authorization_servers,
+  };
+  if (json.scopes_supported) result.scopesSupported = json.scopes_supported;
+  if (json.bearer_methods_supported) result.bearerMethodsSupported = json.bearer_methods_supported;
+  if (json.resource_name) result.resourceName = json.resource_name;
+  if (json.resource_documentation) result.resourceDocumentation = json.resource_documentation;
+  if (json.resource_policy_uri) result.resourcePolicyUri = json.resource_policy_uri;
+  if (json.resource_tos_uri) result.resourceTosUri = json.resource_tos_uri;
+  return result;
+}
+
+/**
+ * Discover OAuth Protected Resource Metadata (RFC 9728) from a vgi-rpc server.
+ * Returns `null` if the server does not serve the well-known endpoint.
+ */
+export async function httpOAuthMetadata(
+  baseUrl: string,
+  prefix?: string,
+): Promise<OAuthResourceMetadataResponse | null> {
+  const effectivePrefix = (prefix ?? "/vgi").replace(/\/+$/, "");
+  const metadataUrl = `${baseUrl.replace(/\/+$/, "")}/.well-known/oauth-protected-resource${effectivePrefix}`;
+
+  try {
+    return await fetchOAuthMetadata(metadataUrl);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fetch OAuth Protected Resource Metadata from an explicit metadata URL.
+ */
+export async function fetchOAuthMetadata(metadataUrl: string): Promise<OAuthResourceMetadataResponse> {
+  const response = await fetch(metadataUrl);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch OAuth metadata from ${metadataUrl}: ${response.status}`);
+  }
+  const json = await response.json();
+  return parseMetadataJson(json);
+}
+
+/**
+ * Extract the `resource_metadata` URL from a WWW-Authenticate Bearer challenge.
+ * Returns `null` if no resource_metadata parameter is found.
+ */
+export function parseResourceMetadataUrl(wwwAuthenticate: string): string | null {
+  // Parse Bearer challenge parameters per RFC 6750
+  const bearerMatch = wwwAuthenticate.match(/^Bearer\s+(.*)/i);
+  if (!bearerMatch) return null;
+
+  const params = bearerMatch[1];
+  const metadataMatch = params.match(/resource_metadata="([^"]+)"/);
+  if (!metadataMatch) return null;
+
+  return metadataMatch[1];
+}

package/src/client/stream.ts

@@ -25,6 +25,7 @@ export class HttpStreamSession implements StreamSession {
   private _compressionLevel?: number;
   private _compressFn?: CompressFn;
   private _decompressFn?: DecompressFn;
+  private _authorization?: string;
 
   constructor(opts: {
     baseUrl: string;
@@ -40,6 +41,7 @@ export class HttpStreamSession implements StreamSession {
     compressionLevel?: number;
     compressFn?: CompressFn;
     decompressFn?: DecompressFn;
+    authorization?: string;
   }) {
     this._baseUrl = opts.baseUrl;
     this._prefix = opts.prefix;
@@ -54,6 +56,7 @@ export class HttpStreamSession implements StreamSession {
     this._compressionLevel = opts.compressionLevel;
     this._compressFn = opts.compressFn;
     this._decompressFn = opts.decompressFn;
+    this._authorization = opts.authorization;
   }
 
   get header(): Record<string, any> | null {
@@ -68,6 +71,9 @@ export class HttpStreamSession implements StreamSession {
       headers["Content-Encoding"] = "zstd";
       headers["Accept-Encoding"] = "zstd";
     }
+    if (this._authorization) {
+      headers.Authorization = this._authorization;
+    }
     return headers;
   }
 
@@ -154,6 +160,9 @@ export class HttpStreamSession implements StreamSession {
       headers: this._buildHeaders(),
       body: this._prepareBody(body) as unknown as BodyInit,
     });
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
 
     const responseBody = await this._readResponse(resp);
     const { batches: responseBatches } = await readResponseBatches(responseBody);
@@ -261,6 +270,9 @@ export class HttpStreamSession implements StreamSession {
       headers: this._buildHeaders(),
       body: this._prepareBody(body) as unknown as BodyInit,
     });
+    if (resp.status === 401) {
+      throw new RpcError("AuthenticationError", "Authentication required", "");
+    }
 
     return this._readResponse(resp);
   }

package/src/client/types.ts

@@ -5,6 +5,8 @@ export interface HttpConnectOptions {
   prefix?: string;
   onLog?: (msg: LogMessage) => void;
   compressionLevel?: number;
+  /** Authorization header value (e.g. "Bearer <token>"). Sent with every request. */
+  authorization?: string;
 }
 
 export interface LogMessage {

package/src/dispatch/stream.ts

@@ -107,12 +107,20 @@ export async function dispatchStream(
       let inputBatch = await reader.readNextBatch();
       if (!inputBatch) break;
 
-      // Cast compatible input types when schema doesn't match exactly
+      // Cast compatible input types when schema doesn't match exactly.
+      // If conformance fails (e.g., completely different schemas like a dummy
+      // registration schema vs actual data), pass the original batch through —
+      // the exchange handler may handle dynamic schemas internally.
       if (expectedInputSchema && !isProducer && inputBatch.schema !== expectedInputSchema) {
         try {
           inputBatch = conformBatchToSchema(inputBatch, expectedInputSchema);
-        } catch {
-          throw new TypeError(`Input schema mismatch: expected ${expectedInputSchema}, got ${inputBatch.schema}`);
+        } catch (e) {
+          if (e instanceof TypeError) {
+            // Field name/count mismatch — propagate as error (matches Python behavior).
+            throw e;
+          }
+          // Other conformance failures: pass through for dynamic schema handlers.
+          console.debug?.(`Schema conformance skipped: ${e instanceof Error ? e.message : e}`);
         }
       }
 

package/src/http/auth.ts

@@ -0,0 +1,47 @@
+// © 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[];
+  resourceName?: string;
+  resourceDocumentation?: string;
+  resourcePolicyUri?: string;
+  resourceTosUri?: string;
+}
+
+/** 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.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;
+  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. */
+export function buildWwwAuthenticateHeader(metadataUrl?: string): string {
+  if (metadataUrl) {
+    return `Bearer resource_metadata="${metadataUrl}"`;
+  }
+  return "Bearer";
+}

package/src/http/dispatch.ts

@@ -2,6 +2,7 @@
 // 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 { MethodDefinition } from "../types.js";
@@ -28,6 +29,7 @@ export interface DispatchContext {
   serverId: string;
   maxStreamResponseBytes?: number;
   stateSerializer: StateSerializer;
+  authContext?: AuthContext;
 }
 
 /** Dispatch a __describe__ request. */
@@ -55,7 +57,7 @@ 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);
@@ -107,7 +109,7 @@ 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];
@@ -205,7 +207,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);
@@ -283,7 +285,7 @@ async function produceStreamResponse(
   let estimatedBytes = 0;
 
   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) {

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 { 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,
@@ -43,12 +45,16 @@ 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 ctx = {
+  // ctx is built per-request to include authContext; base fields set here
+  const baseCtx = {
     signingKey,
     tokenTtl,
     serverId,
@@ -88,6 +94,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=3600",
+      });
+      addCorsHeaders(headers);
+      return new Response(body, { status: 200, headers });
+    }
+
     // CORS preflight
     if (request.method === "OPTIONS") {
       if (path === `${prefix}/__capabilities__`) {
@@ -135,6 +155,26 @@ 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()));
+        }
+        return new Response(error.message || "Unauthorized", { status: 401, headers });
+      }
+    }
+
     // Route: {prefix}/__describe__
     if (path === `${prefix}/${DESCRIBE_METHOD_NAME}`) {
       try {

package/src/http/index.ts

@@ -1,8 +1,12 @@
 // © 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 { ARROW_CONTENT_TYPE } from "./common.js";
 export { createHttpHandler } from "./handler.js";
+export type { JwtAuthenticateOptions } from "./jwt.js";
+export { jwtAuthenticate } from "./jwt.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,66 @@
+// © 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. */
+  audience: 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
+    const claims = await oauth.validateJwtAccessToken(as, request, audience);
+    const principal = (claims[principalClaim] as string | undefined) ?? null;
+
+    return new AuthContext(domain, true, principal, claims as unknown as Record<string, any>);
+  };
+}